Local CLI · V6.5.3 state

Documentation that knows what it knows.

AgentDoc is a compiler for organizational knowledge. Write readable source files. Get typed, evidence-backed objects with lifecycle, ownership, retrieval, review, and patch workflows — for humans and the agents acting on their behalf.

Read the README$cargo install --path crates/adoc-cli --locked
Open source · MIT
Rust · single binary
CLI · MCP · artifacts
billing.adoc→ KnowledgeObject
compiled in 12ms
Source→
# Billing — credit accounting::claim billing.credits.decrement-after-success status: verified owner: @platform-billing source: apps/backend/src/features/credits/consume.use-case.ts test: credits.consume_succeeds impacts: [apps/backend/src/features/credits/consume.use-case.ts] verified_at: 2026-05-02 expires_at: 2120-01-01 Credits are decremented after generation completes successfully.
Knowledge Object
::claimbilling.credits.decrement-after-success
“Credits are decremented after generation completes successfully.”
status
verified
owner
@platform-billing
scope
graph v4
evidence
source_code · test
verified
2026-05-02 · expires 2120
Current CLI surface
adoc checkadoc buildadoc whyadoc graphadoc searchadoc staleadoc contradictionsadoc impacted-byadoc patchadoc diffadoc review
01The problem

Markdown says things.
It does not know them.

A paragraph cannot tell you who wrote it, when it was last verified, what evidence it stands on, or whether an agent is allowed to act on it. AgentDoc encodes all of that — without taking the readability away.

Plain markdownA paragraph in a wiki

Credits are deducted after generation completes.

  • Is it still true?
  • Who wrote it, who owns it?
  • What evidence supports it?
  • Which code paths or sources does it cite?
  • Was it verified by tests, code, or just a meeting?
  • Can an agent retrieve it without scraping prose?
AgentDocA typed Knowledge Object

“Credits are decremented after generation completes successfully.”

  • Verified · expires_at checked
  • Owned by @platform-billing
  • Typed evidence and source refs
  • Impacts: credits/consume.use-case.ts
  • Retrieved by Object ID
  • Patch proposals checked before apply
02Object kinds

Fourteen shipped kinds.
One graph.

The current compiler supports the V0 core set, the V5 expanded model, and V6.5 api, observation, and question objects. Task is still the remaining vocabulary slice.

::claim
Claim
A statement with lifecycle status, optional evidence, owner, expiry, and impacts.
::decision
Decision
A position the team has taken, with relations, evidence, and review impact.
::glossary
Glossary
A named term that gives agents and humans one vocabulary to cite.
::warning
Warning
A known sharp edge with severity, rendered and retrieved as typed knowledge.
::constraint
Constraint
A rule the system must obey, carried by severity rather than lifecycle status.
::policy
Policy
A binding rule with approvers, effective dates, and review-overdue checks.
::procedure
Procedure
An ordered set of steps with structured rendering and graph projection.
::example
Example
Illustrative code, query, or payload material with format-aware rendering.
::agent_instruction
Agent instruction
Explicit guidance for agents, shown with the runtime-not-enforced boundary.
::contradiction
Contradiction
A manually authored conflict that can mark implicated claims contradicted.
::source
Source
A typed evidence source for files, URLs, schemas, incidents, and datasets.
::api
API
A typed API contract with method/interface, path/symbol, and schema evidence.
::observation
Observation
An observed finding with sample size, observed date, and optional evidence refs.
::question
Question
An open or answered question; answered questions point to a claim or decision.

Agents do not follow prose.
They follow objects with owners,
evidence, and a lifecycle.

— AgentDoc thesis · local-first

03Local surfaces

Wherever you write,
wherever you ask.

The shipped product is local-first: a Rust CLI, compiled JSON artifacts, and an MCP gateway. Hosted web, editor LSP, and governance workflows remain later roadmap items.

iCLI · adoc check

A compiler that fails loudly.

adoc check and adoc build validate AgentDoc Source and Markdown compatibility input, then emit source-located diagnostics with stable codes and fix-oriented help.

  • Strict diagnostics for malformed blocks, unsafe links, broken references, and invalid object metadata
  • Lifecycle warnings for expired objects, overdue policy review, contradicted claims, and low evidence quality
  • Output as docs.html, docs.graph.json, and optional docs.search.json
  • Config-backed defaults with local, deterministic, or disabled embeddings
~/billing-pilot — adoc check
$ adoc check examples/expanded-pilot Loading AgentDoc Source and Markdown compatibility input Resolving 14 supported Knowledge Object kinds Validating references, evidence, lifecycle, and graph shape warning[lifecycle.expired]: object expired before the query date --> examples/expanded-pilot/billing/claims.adoc:42 |42 | expires_at: 2024-01-01 = object_id: billing.credits.legacy-export = help: inspect with adoc stale --format json warning[schema.claim_contradicted_by_unresolved]: claim is implicated by auth.session.conflict $ adoc build examples/expanded-pilot Wrote dist/docs.html Wrote dist/docs.graph.json Wrote dist/docs.search.json
dist/docs.graph.json /billing.consume-credit
::apibilling.consume-creditverified

“Consumes one or more credits for a completed generation job, with schema evidence required.”

Kind
api
adoc.graph.v4
Evidence
api_schema
required
Surface
why/search
local retrieval
iiArtifacts · retrieval

Graph and search artifacts,
not scraped prose.

The graph artifact is the canonical local read model. Retrieval commands load it directly, with an optional search sidecar for local lexical, semantic, and hybrid search.

  • adoc why and adoc graph over compiled Knowledge Object IDs
  • adoc search with lexical, semantic, hybrid, and relation-filtered modes
  • adoc stale and adoc contradictions re-derive lifecycle signals from the artifact
  • adoc impacted-by maps changed files to knowledge that needs review
iiiMCP · agent gateway

Agents ask through
versioned tools.

The local MCP gateway exposes CLI-equivalent tools, guidance resources, workflow prompts, and contract-tested schemas so agents do not guess file paths or artifact internals.

  • adoc_project_status before retrieval or patch validation
  • adoc_diff and adoc_review for team review workflows
  • adoc_patch_check for typed proposals with proof obligations
  • adoc_patch_apply is registered but config-gated for explicit opt-in
project-status.jsonusage-contract.md
31tool adoc_project_status
32 retrieval: trueready
33 semantic_search: trueready
34 patch_validation: trueready
35 patch_apply: disabledgated
36
37resource adoc://agent/v0/usage-contract
38 read guidance before retrieval
39 cite Knowledge Object IDs in answersschema
40
41tools registered via rmcp14 tools
04Capabilities

What a knowledge graph
does for you.

Beyond compilation: retrieval, lifecycle-signal reads, object diff/review, MCP tools, and gated source patching all build on the same local artifacts.

Evidence
Knowledge shows its work.
Claims, decisions, APIs, and observations can carry typed inline evidence or references to source objects.
Lifecycle
Signals are queryable.
Expired objects, overdue policies, contradicted claims, and impacted knowledge have first-class CLI and MCP surfaces.
Diff and review
Not what changed — what it means.
Object diffs, required reviewers, source-path impact, proof obligations, and Markdown output support PR workflows.
Retrieval
Search starts from artifacts.
why, graph, and search read docs.graph.json plus optional docs.search.json instead of scraping rendered docs.
Patch loop
Propose, check, apply.
Patches validate against content hashes and proof obligations; CLI apply splices source and MCP apply requires project opt-in.
Contradictions
Conflict is a first-class event.
Manually authored contradiction objects mark implicated claims and can be listed before an agent answers definitively.
Ownership
Review follows ownership.
Verified claims, accepted decisions, policies, and API contracts tie review obligations to object metadata.
MCP
Agents use supported tools.
The local gateway exposes 14 tools plus versioned guidance resources and workflow prompts over the project sandbox.
Open format
.adoc is plaintext.
Source files stay git-friendly. The public read contracts are JSON artifacts and versioned envelopes.
05Roadmap

Boring infrastructure,
shipped quietly.

The local CLI, retrieval, MCP, review, Markdown compatibility, expanded model, lifecycle reads, and gated patch apply are already implemented. The current cycle finishes vocabulary, prose retrieval, docs-truth guards, and pilot readiness.

implemented
Local compiler and retrieval
Native AgentDoc Source and Markdown compatibility input compile into human HTML, graph JSON, and optional search artifacts.
  • adoc init / check / build
  • why / graph / search
  • docs.graph.json + docs.search.json
implemented
Review and agent loop
Object diffs, review reports, lifecycle-signal reads, impacted knowledge, patch validation, and gated source patch apply.
  • diff / review
  • stale / contradictions / impacted-by
  • patch --check / --apply
current V6.5.3
Vocabulary completion
Fourteen Knowledge Object kinds ship today. The remaining task slice completes the fifteen-kind PRD vocabulary.
  • api
  • observation
  • question
  • task next
next V1.7
Prose retrieval
Search will index prose blocks as well as Knowledge Objects, across .adoc and .md sources.
  • adoc.retrieval.v1
  • adoc.search.v1
  • objects-only / prose-only
later
Hosted product and governance
Read-only object explorer, review dashboard, SSO/RBAC/audit, approval workflows, and hosted storage stay deferred until pilot evidence warrants them.
  • web surfaces
  • governance
  • composition and migration

Write what you believe.
Compile what you know.

The pre-release Rust CLI is open source today. Run it on .adoc or compatible .md docs, then inspect the graph, search, review, and MCP surfaces locally.

Quick startRead the PRDgithub.com/alex-bako/adoc ↗