Docent

The museum guide who explains the collection.

Docent is a local-first, code-first knowledge tool that converts codebase evidence into validated, traceable, agent-readable OKF markdown — using the coding-agent subscription your organization already has. No model API keys: any coding agent can do the writing via the cooperative protocol, and GitHub Copilot CLI (or Claude Code) can do it autonomously.

Status: pre-release.

Why

Agent-generated repo wikis (the OpenWiki pattern) work, but the common implementations need their own model API keys, produce free-form pages with no provenance, and write into your workspace with no guardrails. Docent is the enterprise-constraint version of the pattern:

• No API keys — reuses an installed, authenticated coding agent. This potentially avoids a separate model-API integration and credential path; organizations may still review unattended execution, CI use, repo-wide access, persistent generated knowledge, and token scope.
• Validated OKF v0.2 output — one concept per file, typed frontmatter, and a three-class validation gate (execution safety / structural / semantic quality). Every concept cites the source_commit and source_paths that ground its claims and carries the v0.2 trust signals below; agents are instructed to omit rather than guess.
• Workspace-safe by construction — autonomous runs happen in an isolated git worktree and only validated output is copied back; cooperative runs are guarded by an introduced-delta snapshot, so your uncommitted work survives every run. A backend crash cannot corrupt anything.

Markdown is the canonical store. Indexes, the concept graph, and impact models are derived and disposable; index.md and log.md are tool-generated.

Quickstart

Prerequisites: Node >= 20, git on PATH, and a git repository with at least one commit. Autonomous mode additionally needs an installed and authenticated coding agent — GitHub Copilot CLI (copilot, the default) or Claude Code (claude). The cooperative flow below works with any agent that can edit files.

npm install -g okf-docent@next   # or: bun add -g okf-docent@next

cd your-repo
docent init                 # writes docent.config.json, creates .okf/
docent start                # prints a work order for ANY coding agent
docent accept               # check the agent's work, accept it, regenerate indexes
docent link                 # point AGENTS.md / CLAUDE.md at the knowledge base

Between start and accept, your coding agent does the writing. Pick whichever fits your setup:

docent start -p | claude -p          # pipe the work order to a headless agent
docent start -p | copilot -p
docent start                         # or paste the printed order into any agent session

-p/--print emits only the work order, so it pipes cleanly. Or install skill/docent/SKILL.md into .claude/skills/ (see Agent skill) and just ask your agent to update the knowledge base.

Autonomous mode (uses the configured backend, Copilot CLI by default):

docent update               # runs the whole protocol in an isolated worktree

docent status explains freshness ("HEAD is 14 commits ahead", "prompt hash changed"); docent validate --json emits a machine-readable report.

Exit codes

Scripts and CI gates branch on these; they are part of the interface.

| Code | Meaning | | --- | --- | | 0 | success, or nothing to do | | 1 | the knowledge base needs work — validation errors, unsafe agent output, or stale under status --check | | 2 | the command was invoked wrong — bad config, no open work order, unknown agent | | 3 | docent could not run the work — the agent is missing, unauthenticated, or crashed |

Configuration

docent.config.json (written by docent init). Precedence is flags > environment > file > defaults. Unknown keys and wrong types are rejected with a diagnostic rather than silently ignored.

| Key | Default | Flag / env | Notes | | --- | --- | --- | --- | | backend | copilot | --backend, DOCENT_BACKEND | copilot or claude-code | | model | default | --model, DOCENT_MODEL | passed through to the agent | | dir | .okf | --dir, DOCENT_DIR | knowledge-base directory; must be relative and inside the repo | | format | okf | — | only OKF (v0.2) today | | conceptTypes | 9 OKF types | — | affects configHash → changing it marks the base stale | | relationshipTypes | 7 OKF types | — | affects configHash | | exclude | secrets, node_modules, .git | — | globs never read as evidence or cited; affects configHash | | timeoutMs | 1200000 (20 min) | --timeout | per agent invocation | | experimental | [] | DOCENT_EXPERIMENTAL | feature flags, e.g. visualize; never affects output |

backend, model, and timeoutMs are runtime knobs and deliberately excluded from configHash, so switching agents does not invalidate the knowledge base.

How it stays safe

| Run type | Isolation | Guard | | --- | --- | --- | | Cooperative (start/accept) | your live workspace | pre-run snapshot; only the introduced delta is checked; unauthorized introduced changes are reverted; your pre-existing changes always survive | | Autonomous (update) | git worktree at HEAD | backend never touches your workspace; output is validated before copy-back; worktree always deleted |

Execution-safety violations (writes to source, .git changes, symlinks, binaries, secret-looking output) abort the run and discard everything — they are never sent back to an agent for repair.

Freshness policy

The state file records the documented revision plus hashes of the prompts, format contract, and config. New commits → update proceeds. Input drift only (tool upgrade, prompt change) → reported as stale, but regeneration requires explicit --refresh-inputs — never automatic in CI, so tool upgrades cannot cause premium-request storms. No changes → exit 0 with no agent call. No material output change → state untouched, so scheduled CI never loops on PRs.

Trust signals (OKF v0.2)

Docent writes three frontmatter fields itself and forbids agents from touching them — an agent cannot be relied on to name its own actor, and review is an attestation only the tool observing the workflow can make:

generated: { by: claude-code/opus-5, at: 2026-08-03T14:42:00Z }
verified:
  - { by: human:[email protected], at: 2026-08-03T14:43:10Z }
sources:
  - { id: src-quote, resource: src/quote/** }

generated is stamped only on concepts that actually changed in a run, so an untouched concept keeps the time it was last meaningfully rewritten. sources is derived from source_paths for consumers that read standard OKF; docent's own freshness still runs off source_commit + source_paths, which is commit-precise where a date is not.

verified produces the spec's three trust tiers, and docent's two workflows map onto them directly:

| Tier | How a concept earns it | | --- | --- | | unverified | no verified entry — nothing has confirmed this content | | machine-confirmed | autonomous docent update; no human reviewed the result | | human-reviewed | docent start → you review → docent accept, stamped with your git identity |

A rewrite drops any prior verified entry rather than carrying it forward: the old approval attested to content that no longer exists. With no git identity configured, the concept simply stays at the machine tier — an absent signal, never an error.

Visualize (experimental)

docent visualize renders the concept graph as one self-contained HTML file (default .okf/viz.html): typed, labeled relationship edges, plain body links drawn distinctly, per-concept provenance (source commit and evidence paths), composable type/relationship/status filters, full-text search, orphan detection, light and dark themes, keyboard navigation, and PNG/JSON export. No CDN, no network calls — it opens from file://, works offline and behind any CSP, and regenerating an unchanged knowledge base produces a byte-identical file. Concept bodies are sanitized at generation time, so a hostile knowledge base cannot script the viewer.

Gated while pre-GA — enable one of:

DOCENT_EXPERIMENTAL=visualize docent visualize
# or in docent.config.json: "experimental": ["visualize"]

The output is derived and disposable, like the indexes — commit it or gitignore it as you prefer. --json emits the raw graph model for other tooling. See docs/visualize.md.

CI

See examples/github-actions/docent-update.yml: weekly schedule + manual dispatch, auth via a fine-grained PAT with the "Copilot Requests" permission (COPILOT_GITHUB_TOKEN), PR-only publishing via create-pull-request, human review mandatory. Cost notes are in the workflow comments.

Agent skill

skill/docent/SKILL.md follows the open Agent Skills standard. Install it into .github/skills/, .claude/skills/, or .agents/skills/ (or distribute via gh skill), and any supporting agent picks up the start → work order → accept flow.

Relation to prior art

• openwiki (MIT) pioneered the agent-maintained repo wiki with an update loop and instruction-file block. Docent re-implements the mechanism without API keys and adds provenance, deterministic validation, and workspace safety.
• okf-skills (MIT) drives OKF authoring through agent skills. Docent moves the deterministic parts (freshness, impact, validation, indexes) out of prose into a tool.
• Both are credited in docs/prior-art.md.

Platform support

macOS, Linux, and Windows (Node ≥ 20 plus git on PATH). CI runs the suite on all three. Windows notes: vendor-CLI shims are handled via cross-spawn, knowledge-base files are pinned to LF via .gitattributes (written by docent init) and a CRLF-normalizing auto-fix, and symlink-related guard checks require Developer Mode to be exercised (they fail safe otherwise).

Development

bun install
bun test            # unit + protocol suites
DOCENT_E2E=1 bun test update   # real Copilot CLI end-to-end (spends requests)

AGENTS.md documents the layering rules, where to add a command/backend/source, and the error/exit-code conventions — read it before contributing (human or agent).

Design records live in docs/:

| Doc | What it is for | | --- | --- | | docs/adr/ADR-001-*.md | accepted architecture decisions, one file each | | docs/boundaries.md | what docent does and deliberately does not do | | docs/terminology.md | shared vocabulary (concept, evidence, freshness, …) | | docs/threat-model.md | what the guards defend against, and what they do not | | docs/verified.md | vendor-CLI facts with verification dates — re-verify per release | | docs/prior-art.md | related projects and what docent borrows | | docs/visualize.md | the experimental viewer |

Add an ADR when a decision constrains future work or would otherwise be re-litigated (a new seam, a format change, dropping a guarantee). Smaller decisions are recorded as an amendment to the doc they affect. Milestones land as conventional commits, one per PR.

License

Apache-2.0. See LICENSE and NOTICE.