Skip to main content
Using Claude Code, Cursor, or another coding agent? Paste this into your prompt to run cross-browser and real-device tests, debug sessions, and wire up CI on the TestMu AI cloud:
kane-cli context builds a local, content-addressed knowledge store (.context/ in your project directory) from your requirement documents, and extracts use-cases from them with an AI agent. It is the first stage of the assurance lifecycle: Source → Use-case → Scenario → AC → Test.

​
context ingest — snapshot your sources

Snapshots one or more files into .context/ (the store is created on first use). Each source gets a stable id — by default the filename slug (prd-online-store.md → prd-online-store), or pass --as <id> to name it yourself. Ingest is deterministic about identity:
Accepted media: text (.txt) and markdown (.md, .markdown) up to 2 MB — cited verbatim by line; PNG/JPEG/WebP images up to 5 MB — cited whole-image. Anything else is rejected with UNSUPPORTED_MEDIA; oversized files with FILE_TOO_LARGE. When the new bytes are a changed version of a source you already extracted from, prefer kane-cli maintain reconcile over a bare re-ingest — it records the same head move and triages what the change means for your suite, in one step.

​
context extract — propose use-cases

Runs the extraction agent over every ingested source whose current snapshot has no committed extraction yet (already-extracted snapshots are skipped — re-run with --force to redo one). On a terminal the default is an interactive chat. Headless use is an explicit opt-in: a bare non-TTY invocation exits 2 and asks you to pass --mode agent|ci|override — see Automation for the headless contract. What the agent does:
  • Reads each source and proposes use-cases with verbose descriptions (flows, inputs, states, boundaries) and criteria[] — short, cited sketches of the acceptance-relevant promises the source states. Criteria are hints for kane-cli design, never test oracles.
  • Cites everything. Every proposal must quote an exact line from the source; fabricated evidence is rejected before anything is written. (Image sources cite the whole image — there is no text to quote.)
  • Asks when the source is ambiguous. Conflicting requirements become clarifying questions with options, a recommended default, and a risk level — low/medium-risk questions can be defaulted, high-risk ones want a real answer.
  • Grounds itself in what you already have. The agent explores the existing graph read-only before proposing, so a use-case you already committed becomes new evidence on the existing node (shown as ≈ matches) instead of a duplicate.
Extraction stops at the use-case. Scenarios, ACs, and tests are minted by the design engine — each stage can only create its own kinds. Flags:

​
The interactive chat

The chat has two zones. The scrollback is the complete session journey — your words, the agent’s narrative, its reasoning segments and tool lines, each proposal list as it arrived, answer receipts, commit receipts, and per-turn credit costs. The live region below shows only what is happening now: the current thinking line (ctrl+t expands it), the question panel, and the composer. Answering questions happens right in the composer:
  • Bare input answers the active question (marked ›), and the cursor advances: 1 picks option 1, typing an option’s name matches it, anything else is free text where allowed.
  • N: targets question N explicitly (2: yes). Without the colon, 2 business days stays free text.
  • Empty Enter accepts the recommended defaults for low/medium-risk questions only — each is echoed back as ↳ assumed … (flagged). High-risk questions are never bulk-defaulted: answer them, or type defer to leave the rest with the agent.
  • The batch submits when every question is answered, assumed, or deferred — never silently partial.
Ctrl+C asks for a pause, not a crash. The first press asks the agent to save the session; on success you get a pause card with the exact resume command (including the --message form) and the run exits 3. If the save can’t complete within a few seconds you get an honest interrupted — session not saved (exit 130, not resumable), and a second Ctrl+C at any point is an immediate hard exit. /pause does the same from the composer; /done ends the session cleanly. Slash commands (everything else you type is conversation for the agent):

​
The review checklist

After the agent proposes, the same session walks you through a review checklist: space cycles approve / edit / reject / skip per item, e opens an edit form, and Enter commits the whole batch as one record:
  • approve / edit → committed as trusted
  • reject → committed + archived (kept on record, not deleted)
  • skip → committed as derived — queued for later review

​
Pausing and resuming

When the agent needs an answer you’re not there to give (or you Ctrl+C), the session is saved and the run exits 3. Resume it any time within 24 hours:
--message answers in plain words — no question ids, no option indexes. The agent maps your statement to its own pending questions. A statement that answers nothing pending is treated as steering (“also cover the coupon path”). If your answer leaves a high-risk ambiguity standing, the run pauses again with refreshed questions.

​
context review — review outside the extract session

Walks existing nodes through the same review checklist, landing every verdict as one batched record:
  • derived (default) — everything unreviewed
  • skipped — strictly the items you skipped during an extract review
  • archived — resurrection candidates: an explicit approve restores trust
  • drift — a listing only (works without a TTY): nodes whose evidence is stale or orphaned, with their pinned sources — the re-extract worklist
In any queue: approve promotes, reject archives (a trusted node can be demoted), and edit mints a new version that supersedes the old one — nodes are immutable, so edits never rewrite history and existing references never break. Headless verdicts — --verdicts <file.json> is the one non-TTY write path: a JSON array of
with resolution one of approved | edited | rejected | skipped | supersede (plus optional reason, edit, supersede_target). It is atomic: every ref must resolve and sit in a verdict queue, or nothing commits (exit 2). With --json, each landed verdict echoes as one NDJSON row. There is deliberately no auto-approve mode for review — trust requires a human decision.

​
Inspecting the graph

​
context list

Lists nodes with their trust and freshness. --inferred shows only unreviewed (derived) nodes, --stale only stale or orphaned nodes (evidence pinned to an outdated snapshot, or no live source at all), --all includes superseded versions (hidden by default). --json emits one JSON object per line.

​
context view

Renders the whole graph as a single self-contained HTML page — swimlanes per use-case, provenance edges back to the source, trust and staleness at a glance, a commit rail along the bottom, and click-through detail panels with each node’s lineage. It is a snapshot (no server; works offline); re-run to refresh. Piped runs write the file and print its path instead of opening a browser; --json prints the computed payload for scripting.

​
context explain

Replays a node’s recorded history straight from the store — no model call, ever: when it was minted and why, every review verdict, edits and supersessions, name assignments. <ref> is a logical id (uc-manage-the-cart) or a cid.

​
context sessions

Paused extract and design sessions live under .context/sessions/ for 24 hours. list shows each with its pending-question count, expiry, and ready-to-paste resume command. show <sid> prints everything the paused agent is waiting on — the questions in full, any defaults it assumed in your absence, and both resume forms. clean garbage-collects expired sessions (clean <sid> removes one; --all removes everything).

​
Housekeeping

​
context retire

Retires a source. Its use-cases are not deleted — they read orphaned once no live source evidences them. Fully reversible via revert.

​
context name

Assigns a stable kebab-case name. Names are never part of a node’s identity — renaming never re-addresses — and names follow edits, so a name assigned to version 1 keeps resolving to the current version.

​
context revert

Inverts a record’s effects by appending a compensation record — mints are tombstoned, heads move back, trust states are restored. History is never rewritten: the store keeps both the mistake and its correction. Reverting a revert restores the original effects.

​
context fsck / context rebuild

fsck verifies the full record chain and checks the read caches for drift (exit 1 on any issue) — run it whenever hands touched .context/ directly. rebuild wipes the derived caches and regenerates them from the verified records; it is always safe. Destructive-verb rule: retire, revert, name --backfill, and rebuild prompt for confirmation on a terminal (default No) and require an explicit --yes headless. Read commands never create a .context/ store in a directory that has none — only ingest and extract do.

​
Trust and freshness

Freshness is orthogonal: fresh / stale (the source snapshot moved) / orphaned (no live source evidences it) / superseded (this version was replaced). A stale use-case is still trusted — it just needs re-verification against the new snapshot, which is exactly what kane-cli maintain reconcile is for.

​
The store on disk

Two rules worth repeating from the overview: the store is single-writer, and it is not git-mergeable — gitignore it and share by re-ingesting sources. Every extract run also writes a per-run trace to .context/logs/extract-<ts>.log (the path is printed at the start of the run) — the first place to look when a run surprises you.

​
For agents and CI

Headless extraction (--mode agent|ci|override), the NDJSON event stream, exit codes, and the pause/resume contract are documented in Automation.

​
Next steps