# CKM — Codebase Knowledge Manifest
**Machine-readable operational knowledge for CLI tools. Any language. Any framework. One implementation.**
[](https://crates.io/crates/ckm)
[](https://www.npmjs.com/package/ckm-sdk)
[](LICENSE)
---
## What is CKM?
CKM bridges the gap between API documentation and actionable help. While `--help` gives you flags and `llms.txt` gives you API signatures, CKM tells you what your tool **does**, what **concepts** it has, what **config** controls what **behavior**, and what **constraints** are enforced.
A `ckm.json` manifest captures structured knowledge about a CLI tool. The CKM SDK reads it and provides:
- **Auto-derived topics** — zero manual mapping
- **Progressive disclosure** — 4 levels from discovery to full API dump
- **Human + machine output** — terminal text for humans, JSON for LLM agents
- **Framework adapters** — Commander.js, Click, Clap, Cobra, and more
```
$ mytool ckm calver
# Configures CalVer validation rules.
## Concepts
CalVerConfig — Configures CalVer validation rules.
format: CalVerFormat = YYYY.MM.DD
preventFutureDates: boolean = true
## Operations
validate() — Validates a CalVer string against formatting and date rules.
@param version: Version string to validate.
## Config Fields
calver.format: CalVerFormat = YYYY.MM.DD
calver.preventFutureDates: boolean = true
```
## Install
### Node.js / TypeScript
```bash
npm install ckm-sdk
```
```javascript
const { createCkmEngine, validateManifest } = require('ckm-sdk');
const fs = require('fs');
// Load your ckm.json (generated by forge-ts or hand-authored)
const manifest = JSON.parse(fs.readFileSync('docs/ckm.json', 'utf-8'));
const engine = createCkmEngine(manifest);
// Progressive disclosure
console.log(engine.getTopicIndex('mytool')); // Level 0: topic list
console.log(engine.getTopicContent('calver')); // Level 1: topic detail
console.log(engine.getTopicJson('calver')); // Level 1J: structured JSON
console.log(engine.getTopicJson()); // Level 2: full index
console.log(engine.getManifest()); // Raw v2 manifest
console.log(engine.inspect()); // Metadata and counts
```
### Rust
```bash
cargo add ckm
```
```rust
use ckm::CkmEngine;
let data: serde_json::Value = serde_json::from_str(&manifest_json).unwrap();
let engine = CkmEngine::new(data);
println!("{}", engine.topic_index("mytool"));
if let Some(content) = engine.topic_content("calver") {
println!("{}", content);
}
```
### Python
```bash
pip install ckm # (PyPI — coming soon, available via maturin develop)
```
```python
from ckm import create_engine
engine = create_engine(open('docs/ckm.json').read())
print(engine.topic_index('mytool'))
print(engine.topic_content('calver'))
```
## Architecture: Rust Core SSoT
CKM is implemented **once in Rust** and exposed to every language through thin FFI wrappers:
```
ckm.json v2 (input)
│
▼
┌─────────────┐
│ rust-core │ ← THE implementation (types, engine, migration, validation, formatting)
└──────┬──────┘
│
┌───┼───┬───────┐
│ │ │ │
▼ ▼ ▼ ▼
napi PyO3 CGo Direct
(npm) (PyPI)(Go) (Rust)
```
**Why single-source?** Four independent implementations of the same algorithm *will* diverge on edge cases. One implementation + mechanical wrappers eliminates drift by construction. When the algorithm changes, it changes once in Rust. All languages follow.
## The ckm.json Manifest
A `ckm.json` file captures five dimensions of CLI tool knowledge:
| **concepts** | What domain objects does this tool have? |
| **operations** | What can I do with this tool? |
| **constraints** | What rules are enforced? |
| **workflows** | How do I accomplish multi-step goals? |
| **configSchema** | What config controls what behavior? |
### Generating ckm.json
**With [forge-ts](https://github.com/kryptobaseddev/forge-ts)** (for TypeScript projects):
```bash
npx forge-ts build # generates docs/ckm.json from TSDoc annotations
```
**By hand** (for any language):
```json
{
"$schema": "https://ckm.dev/schemas/v2.json",
"version": "2.0.0",
"meta": {
"project": "my-tool",
"language": "typescript",
"generator": "hand-authored",
"generated": "2026-03-29T00:00:00.000Z"
},
"concepts": [{
"id": "concept-calver-config",
"name": "CalVerConfig",
"slug": "calver",
"what": "Configures CalVer validation rules.",
"tags": ["config"],
"properties": [{
"name": "format",
"type": { "canonical": "string", "original": "CalVerFormat" },
"description": "Calendar format.",
"required": true,
"default": "YYYY.MM.DD"
}]
}],
"operations": [],
"constraints": [],
"workflows": [],
"configSchema": []
}
```
## Progressive Disclosure
CKM enforces four levels of output, each with a token budget:
| 0 | `mytool ckm` | Human/Agent discovery | 300 tokens |
| 1 | `mytool ckm calver` | Drill-down | 800 tokens |
| 1J | `mytool ckm calver --json` | Agent structured | 1200 tokens |
| 2 | `mytool ckm --json` | Agent full index | 3000 tokens |
LLM agents get structured data under tight token budgets. Humans get formatted text. Same command, different flags.
## API Reference
### `createCkmEngine(manifest)`
Creates an engine from a parsed `ckm.json` or JSON string (v1 or v2). v1 manifests are auto-migrated.
Returns an engine with:
- `topicsCount` — number of derived topics (property)
- `getTopicIndex(toolName?)` — formatted topic list for terminal display (string)
- `getTopicContent(topicName)` — formatted topic detail (string | null)
- `getTopicJson(topicName?)` — structured JSON output (CkmTopicIndex, CkmTopic, or CkmErrorResult)
- `getManifest()` — raw v2 manifest (CkmManifest)
- `inspect()` — metadata and counts (CkmInspectResult)
### `validateManifest(data)`
Validates data against the v2 schema. Returns `{ valid: boolean, errors: [{ path, message }] }`.
### `migrateV1toV2(data)`
Deterministic migration from v1 to v2 format. Returns a CkmManifest.
### `detectVersion(data)`
Returns `1` or `2`.
### `createManifestBuilder(project, language)`
Creates a fluent builder for constructing valid v2 manifests (producer API).
Returns a builder with chainable methods:
- `generator(name)`, `sourceUrl(url)`
- `addConcept(name, slug, what, tags)`, `addConceptProperty(...)`
- `addOperation(name, what, tags)`, `addOperationInput(...)`
- `addConstraint(rule, enforcedBy, severity)`, `addConfig(key, type, desc, required, default)`
- `build()` — returns JSON string
- `buildJson()` — returns parsed object
## Integrating CKM into Your CLI
### Step 1: Generate or write `ckm.json`
Use forge-ts for TypeScript projects, or hand-author for any language.
### Step 2: Install ckm-sdk
```bash
npm install ckm-sdk
```
### Step 3: Wire into your CLI (3 lines)
```javascript
const { createCkmEngine } = require('ckm-sdk');
const fs = require('fs');
const manifest = JSON.parse(fs.readFileSync('docs/ckm.json', 'utf-8'));
const engine = createCkmEngine(manifest);
// Add to your Commander.js program:
program
.command('ckm [topic]')
.option('--json', 'Machine-readable output')
.action((topic, { json }) => {
if (json) console.log(JSON.stringify(engine.getTopicJson(topic), null, 2));
else if (topic) console.log(engine.getTopicContent(topic) || engine.getTopicIndex('mytool'));
else console.log(engine.getTopicIndex('mytool'));
});
```
That's it. Your users get `mytool ckm [topic]` with progressive disclosure.
## Monorepo Structure
```
packages/
rust-core/ ← THE SSoT: pure Rust library, all algorithms
node/ ← napi-rs wrapper → npm: ckm-sdk
python/ ← PyO3 wrapper → PyPI: ckm
go/ ← CGo/WASM wrapper → Go modules
cli-rs/ ← Rust CLI binary → crates.io: ckm-cli
conformance/ ← Test fixtures shared across all languages
```
## Origin
CKM was born inside [VersionGuard](https://github.com/kryptobaseddev/versionguard), a versioning enforcement tool. After proving the concept — auto-derived topics, progressive disclosure for LLM agents, zero-config integration — it was extracted into a standalone SDK.
## License
MIT