Open source · Rust · pre-release

Agents that know your codebase, and when to stop.

That takes documentation that knows what it knows. AgentDoc compiles your docs into typed, evidence-backed Knowledge Objects that your agent queries over MCP. When it proposes an edit your docs disallow, it stops and cites the rule. A single Rust binary, MIT licensed, and everything stays on your machine.

Quick start$cargo install --path crates/adoc-cli --locked
Open source · MIT
Rust · single binary
CLI · MCP · GitHub Action
~/project — claude
Claude Code
Opus 5 with xhigh effort
~/project
❯
The loop, end to end
adoc checkadoc buildadoc whyadoc graphadoc searchadoc staleadoc contradictionsadoc impacted-byadoc patchadoc diffadoc review
01The problem

Your agent read the wiki.
The wiki was wrong.

Coding agents rediscover your architecture every session. The real constraints live in senior engineers' heads and in a CLAUDE.md nobody has verified since spring. Prose can't tell an agent whether a claim is still true or who to ask before a risky change, so the agent guesses. Guesses ship.

Plain markdownWhat your agent gets

Credits are deducted after generation completes.

  • The agent can't tell whether this is still current, so it assumes it is.
  • Nobody owns the paragraph, so a risky change has no reviewer to route to.
  • A meeting note carries the same weight as the test suite.
  • Without source references, the agent greps and hopes.
  • Guidance that expired last quarter reads exactly like guidance written yesterday.
  • Retrieval means scraping prose into the context window.
AgentDocThe same fact, typed

“Credits are decremented after generation completes successfully.”

  • status: verified · expires_at enforced by adoc check
  • owner: @platform-billing, so review routes itself
  • evidence: source_code + test, typed and cited
  • impacted objects known before the edit
  • retrieved by Object ID over MCP
  • patches machine-checked before apply
02Object kinds

Write prose.
Fence the facts.

An .adoc file is ordinary readable prose, plus fenced, typed Knowledge Objects where the facts live. Fifteen kinds cover what teams actually know: decisions, constraints, warnings, procedures, open questions. adoc build compiles them into HTML for humans and graph and search artifacts for agents.

::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.
::task
Task
Trackable work bound to the Knowledge Objects it changes.

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

— AgentDoc thesis · local-first

03Local surfaces

Watch it cite.
Then watch it refuse.

Three live demos, all local, one binary: Claude Code citing and halting over MCP, plain-English search over your graph, and the versioned JSON artifacts behind both.

iMCP · agent gateway

The edit your docs
disallow.

The local MCP gateway gives any agent the same typed answers the CLI gets. When a proposal breaks a documented rule, the agent finds out before the write, and it can cite the object that stopped it.

  • Works with any MCP client that can launch a binary; 14 versioned tools over local stdio
  • Every answer carries the object ID, its owner, and the evidence behind it
  • adoc_patch_check proves a proposal before anything is written
  • Writes are off by default; adoc_patch_apply requires explicit project opt-in
~/project — claude
Claude Code
Opus 5 with xhigh effort
~/project
❯A
iiCLI · adoc search

Ask in plain English,
get typed answers.

adoc search retrieves typed Knowledge Objects from local artifacts using lexical, semantic, hybrid, filtered, or graph-scoped queries.

  • Hybrid BM25 and local embeddings out of the box; it never needs an API key or a network connection
  • Filter by kind, status, or owner, then narrow along graph relations
  • Every hit carries its lifecycle, ownership, and evidence
  • adoc why <id> takes you from a claim to its source in one command
~/project — adoc search
❯ S
iiiArtifacts · retrieval

Agents read 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 build emits docs.html, docs.graph.json, and docs.search.json
  • Envelopes are versioned, so scripts can depend on them safely
  • stale, contradictions, and impacted-by run as CI gates
  • --format markdown drops reports straight into PR comments
~/project — graph artifacts
❯
04Guarantees

Silent drift becomes
a failing check.

Nothing below is roadmap. This is what the compiler, the MCP gateway, and the GitHub Action enforce today.

Evidence
Knowledge shows its work.
Every claim cites source refs and tests, or says that it doesn't. adoc why prints the receipt.
Lifecycle
Rot becomes a list.
Objects carry verified_at and expires_at. adoc stale --within 30d turns quiet drift into work you can schedule.
PR assessment
Every PR checks the docs.
The GitHub Action runs assessment on every pull request and posts a report marking each changed path covered, provisional, or uncovered. Advisory by default, strict when you choose.
Retrieval
Search starts from artifacts.
Hybrid search over local artifacts. Filter by kind, status, or owner and narrow by graph relation.
Patch loop
Propose, check, apply.
Agents propose canonical patches; adoc patch --check proves them against content hashes before anything applies.
Contradictions
Conflict is a first-class event.
When two objects disagree, adoc contradictions lists the conflict as a diagnostic an agent can read before it answers.
Ownership
Review follows ownership.
Every object has an owner, and review routes to them. They see what a change means, not just what moved.
MCP
Agents use supported tools.
14 versioned tools for any MCP client. Read-only unless you enable patch_apply, and writes stay inside the project root.
Open format
.adoc is plaintext.
Typed kinds in plain text, living in your repo. One MIT-licensed binary with nothing to host.
05Vision

Local-first today.
Governed knowledge, eventually.

Everything above this line ships today and stays open source; the standalone tools will never be degraded to push an upgrade. What follows is where AgentDoc is heading. It is a design, not a commitment, and none of it is implemented yet.

in design
Two first-class modes
Standalone stays canonical: your git repo is the source of truth, permanently. Managed Cloud becomes an explicit opt-in for teams that need shared review, approval, and audit.
in design
Governed change
Candidate versions are proposals, never active truth. Only explicit governance events change what a team's agents treat as known, and every event is recorded.
in design
Source-neutral connectors
External systems stay canonical for their own artifacts. Immutable source records preserve provenance, and a per-scope authority policy decides what may promote.
in design
Permission-aware retrieval
Authorization is deny-by-default down to objects and fields. Checks run before search and traversal, so restricted knowledge can't leak through counts, rankings, or embeddings.
Read the V1 direction ↗

Teach it once.
Every agent remembers.

Install the CLI, run adoc init, and compile your first Knowledge Object in minutes. Then point any MCP agent at the gateway and watch it start citing. Everything runs locally, and your docs never leave the repo.

Quick startgithub.com/agentdoc-dev/adoc ↗