istok

istok knowledge

Create, distill, search, read, review, promote, supersede, and export project knowledge.

istok knowledge works with knowledge items: longer, reviewed project documents stored in the Istok database, outside your repository. Agents manage them through MCP; the CLI is handy for reviewing drafts, checking what agents wrote, and exporting. For the draft, review, promote lifecycle, see Context and knowledge.

Commands

Command Purpose
add TITLE Create a draft.
distill TITLE Create a draft from explicit provenance sources.
list (alias catalog) List the catalog without full bodies.
search QUERY Search knowledge and return catalog entries.
show ID Show one complete item.
read ID Read one complete item.
update ID Update a draft.
review ID Record an explicit review of a draft.
promote ID Promote a reviewed draft to current.
supersede ID REPLACEMENT Replace current knowledge with a reviewed replacement.
export ID Export an item to a file you choose.

All knowledge commands operate on the Istok project associated with the current directory. Items are identified by canonical UUIDv7 IDs.

Kinds and statuses

Every item has a kind:

Kind Use
architecture How the system or a part of it is structured.
domain Domain concepts and business rules.
decision Decisions and their reasons.
runbook Operational procedures.
note Anything else. This is the default.

And a status:

Status Meaning
draft Proposed. Can be edited, reviewed, and promoted.
current Promoted. Included in run briefings. Cannot be edited.
superseded Replaced by another item. Kept for history. Cannot be edited.

Items also carry tags, --visibility (shared or local_only), and --sensitivity (normal or private), with the same meaning as for context records.

Create a draft

Every item needs a title and a short summary. The summary is what appears in catalogs and run briefings, so write it for someone deciding whether to read the full item.

istok knowledge add "Authentication" \
  --kind architecture \
  --summary "How sessions, refresh tokens, and the JWKS cache fit together" \
  --body-file ./auth-notes.md \
  --tag auth

Provide the body either inline with --body or from a file with --body-file, not both. The file is read once; Istok stores the content in its database and does not keep a link to the file.

Limits: the title is up to 200 bytes, the summary up to 500 bytes, and the body up to 1 MiB.

Distill a draft from existing work

distill creates a draft in the same way as add, but requires at least one provenance source:

istok knowledge distill "Token refresh failure modes" \
  --summary "Why refresh requests time out and how retries behave" \
  --body-file ./findings.md \
  --source task:TASK_ID \
  --source run:RUN_ID \
  --source repository:internal/auth/refresh.go

A source has the form:

TYPE:ID[@REVISION][#DETAIL]

TYPE is one of task, run, context, knowledge, repository, or import. For task, run, context, and knowledge, ID is the canonical UUIDv7 of that object (for a task, the UUID shown by istok task show 12 --json, not the task number). A repository source is a normalized path relative to the repository root. An import source is free-form. --source can be repeated, and add accepts it as well.

List the catalog:

istok knowledge list

Filter it:

istok knowledge list --status current
istok knowledge list --kind runbook --kind decision

list also accepts --visibility and --sensitivity filters. It returns up to 50 entries by default; use --limit (at most 200) and --offset to page through larger catalogs.

Search titles, summaries, bodies, tags, and provenance:

istok knowledge search "JWKS cache"

Catalog and search results contain metadata and a short snippet, not the full body.

Read an item

Show one complete item, including its body, provenance, review state, and history:

istok knowledge show KNOWLEDGE_ID

istok knowledge read KNOWLEDGE_ID returns the same output. Use whichever name you prefer.

Update a draft

Only drafts can be changed:

istok knowledge update KNOWLEDGE_ID \
  --expected-revision 2 \
  --summary "Sessions, refresh tokens, JWKS cache, and key rotation"

update accepts replacement values for the title, summary, body (--body or --body-file), kind, tags, sources, visibility, and sensitivity.

Updating a draft clears its review. A changed draft must be reviewed again before it can be promoted.

To change current knowledge, create a new draft and supersede the current item with it.

Review a draft

Record that the draft was checked, with a note describing how:

istok knowledge review KNOWLEDGE_ID \
  --expected-revision 1 \
  --note "Verified against internal/auth at the current main branch"

Only drafts can be reviewed. The note is required and is limited to 1000 bytes.

Promote a draft

Make a reviewed draft current:

istok knowledge promote KNOWLEDGE_ID --expected-revision 2

Promotion fails for a draft that has not been reviewed, or whose review was cleared by a later update.

Supersede current knowledge

Replace a current item with a newer one:

istok knowledge supersede OLD_ID NEW_ID --expected-revision 3

--expected-revision is the revision of the current item being replaced. The replacement must be a reviewed draft or an already current item. A reviewed draft replacement is promoted to current in the same step, and the old item becomes superseded.

Export an item

Knowledge lives in the Istok database. To get a file, export it to an explicit destination:

istok knowledge export KNOWLEDGE_ID --output ~/notes/authentication.md

The default format is Markdown with a small metadata header. Use --format json for JSON.

Export never overwrites an existing file. Missing parent directories are created with 0700 permissions, and the file is written with 0600 permissions.

Revisions

update, review, promote, and supersede use compare-and-swap protection through --expected-revision. If the item changed since you read it, the command fails instead of overwriting newer state. Read it again with show and retry with the current revision.

JSON output

All knowledge commands accept --json and return a versioned response with schema_version: "1". See JSON output.

Help

istok knowledge distill --help
istok knowledge list --help
istok knowledge export --help