Core Concepts

Core Concepts

The five ideas everything else builds on: docs bound to sources, verdicts computed from git, trust and altitude labels that route behavior, layers that separate mechanics from judgment, and a write gate that keeps humans in charge of the judgment half. Ten minutes here makes every other page obvious. (Normative detail: SCHEMA.md in the repository; mechanics: docs/HANDBOOK.md.)

The architecture in one picture

flowchart LR
    subgraph clients["Clients"]
        direction TB
        HARNESS["AI agents\nany MCP-capable harness"]
        HUMAN["Humans and CI\nshell, scripts"]
        ORCH["Orchestrator, e.g. TAUT\n(optional)"]
    end

    subgraph engine["KAUT engine - stateless, zero-dep Node, no daemon"]
        direction TB
        SURF["Two surfaces\nmcp.mjs - 7 MCP tools\nkaut.mjs - CLI"]
        READP["READ path (lock-free)\nlookup / stale / digest\nfreshness verdict = pure git computation\n+ trust tier + altitude on every answer"]
        WRITEP["WRITE path (one chokepoint)\nlayered write gate + draft queue\nagent tier lands, judgment tier\nwaits for owner review"]
        MAINTP["Maintenance loop\nrefresh / touched / note\nmap collectors (stack adapters)"]
    end

    subgraph home["Knowledge data home - set once with kaut home"]
        direction TB
        STORES["One store per repo\ntyped markdown + frontmatter\nown private git = audit + rollback\njournal telemetry"]
        REG["workspaces registry\nmember stores + one system store"]
        BACK["backups/\nkaut backup / restore"]
    end

    REPOS["Your repositories\nREAD-ONLY sources\n(at most one git-ignored pointer file)"]
    OKFB["OKF v0.2 bundle\nkaut okf export"]

    HARNESS --> SURF
    HUMAN --> SURF
    ORCH --> SURF
    SURF --> READP
    SURF --> WRITEP
    SURF --> MAINTP
    READP -- "diff sources against\nthe anchor commit" --> REPOS
    MAINTP -- "derive maps from code" --> REPOS
    READP <--> STORES
    WRITEP --> STORES
    STORES --> OKFB

Loading

Stateless engine, knowledge outside your repos in per-repo git-backed stores, verdicts computed on read, one write chokepoint. The rest of this page defines the vocabulary the diagram uses.

Docs, sources, anchors

The unit of knowledge is a doc: a short markdown file with strict frontmatter. Two fields carry the whole model:

• sources — typed bindings naming where the fact comes from (file:, file-glob:, and friends; sections of a doc can carry their own narrower bindings). No sources, no doc: the contract is validated at the door.
• derived_from_commit — the anchor: the main-branch commit the fact was true at.

Together they make every fact checkable: the engine can always ask git "did any source of this doc change between its anchor and the current main tip?" — no model calls, no guessing.

Freshness verdicts

Every read answers with a verdict, computed on the spot:

Verdict	Meaning	Reader's move
healthy	sources unchanged since the anchor	use it; skip the re-derivation
stale	sources changed on the main line	re-check; kaut refresh says exactly what changed
branch-advisory	your current branch moved relevant files (main is clean)	fine on main; mind the branch delta
broken	a bound source no longer exists at the anchor tree	re-bind or re-derive
tampered	store content edited outside the pipeline	withheld entirely — content is not served

The engine errs toward stale: whenever git cannot prove freshness (unknown anchor, diverged history, unresolvable ref), the verdict degrades. A false "stale" costs one re-check; a false "fresh" ships a bug.

Trust tiers and altitude

Two labels ride along with every answer:

• Trust (T0–T4) — provenance quality: T0 = mechanically generated from code, up through human-confirmed. Low trust = read skeptically, verify against code.
• Altitude — coverage granularity (landscape / component / endpoint), back-derived from the doc's source bindings. A coarse (landscape) doc can be healthy and still too zoomed-out for your question — its answer arrives with an explicit "confirm in code" directive. Freshness tells you when the doc was true; altitude tells you how closely it covers what you're asking.

The standing discipline both labels serve: knowledge informs — it never authorizes. Healthy + precise is permission to skip re-derivation, never permission to act blindly.

Layers

The store is organized into directories that are the taxonomy:

Layer	Holds	Typical write policy
map/	mechanical maps (routes, packages, services)	regenerated by collectors
runbook/	verified operational procedures	agent tier (through the gate)
domains/	how a domain actually works	owner-gated
decisions/	why it is this way (and not the obvious other way)	owner-gated
contracts/	cross-component invariants	owner-gated
flows/	end-to-end behavior across parts	owner-gated
bootstrap/	how to get a working setup from zero	per policy

What gets stored at all is decided by the litmus test: expensive to re-derive, not cheaply visible in the code, true at the anchor. If an agent can re-derive it from the code in seconds, don't store it — that's what the code is for.

The layer is also the doc's OKF type: KAUT implements the vendor-neutral Open Knowledge Format v0.2, so every concept document is typed, plain markdown any OKF consumer can read (kaut okf export produces a fully idiomatic bundle; see the FAQ).

The write gate and the draft queue

Every write funnels through one chokepoint (a commit into the store's own private git), and the gate decides by layer and provenance. Which layers are agent-tier and which are owner-gated is policy, set per store or workspace; a store with no policy configured runs open (single-user mode — you are both the agent and the owner). The recommended policy:

• Mechanical (map/*): regenerate freely — it is a cache of the code, not an opinion.
• Agent tier (e.g. runbook/*): an agent that verified the fact in this session may land the update directly; the commit is journalled and auditable.
• Owner-gated (decisions / domains / contracts / flows, and every novel doc): nothing lands without a human. Updates queue as drafts — validated at the queue door (contract + anchor), committed durably, but never served to readers — and the owner lands or rejects the batch with kaut review, one keystroke per doc.

The gate's flip side is tamper containment: content that did not come through the pipeline (an out-of-band edit, a crashed half-write) is not argued with — it is withheld from every reader until restored or legitimately landed. The store is read by AI agents; unreviewed bytes are an injection channel, and the engine treats them as one.

One store per project, outside the repo

Each project gets its own store — a small private git repository outside your working copy (your repo is never modified; a single ignored pointer file links them). Multi-repo landscapes add a registry and one system store for cross-repo knowledge — see Connecting Your Project.

Next: Connecting Your Project · Maintenance Loop