CKM — Codebase Knowledge Manifest

Machine-readable operational knowledge for CLI tools. Any language. Any framework. One implementation.

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

npm install ckm-sdk

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

cargo add ckm

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

pip install ckm  # (PyPI — coming soon, available via maturin develop)

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:

| Section | What it answers | |---------|----------------| | 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 (for TypeScript projects):

npx forge-ts build  # generates docs/ckm.json from TSDoc annotations

By hand (for any language):

{
  "$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:

| Level | Command | Audience | 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

npm install ckm-sdk

Step 3: Wire into your CLI (3 lines)

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, 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