v0.1 — Compiler shipping today

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, and scope — for humans and the agents acting on their behalf.

Read the spec$ brew install adoc
Open source · MIT
Rust · single binary
CLI · LSP · Web
billing.adoc→ KnowledgeObject
compiled in 12ms
Source→
# Billing — credit accounting::claim billing.credits.decrement-after-success status: verified owner: @platform-billing scope: {env: prod, plan: *} evidence: - tests/billing/credits.rs::test_atomic - src/billing/credits.rs#L142 verified-at: 2026-05-02 expires: 90d 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
env=prod · plan=*
evidence
2 sources · current
verified
2026-05-02 · expires 88d
In production at
StoryworkNorthbeamLatch OSFoundry LabsPeripheryMercator
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?
  • Does it apply to staging or only prod?
  • Was it verified by tests, code, or just a meeting?
  • May an agent act on it?
AgentDocA typed Knowledge Object

“Credits are decremented after generation completes successfully.”

  • Verified · expires in 88 days
  • Owned by @platform-billing
  • 2 evidence sources, currently passing
  • Scope: env=prod, plan=*
  • Linked to credits.rs#L142
  • Agents: read · cite · not patch
02Object kinds

Eight types. One graph.

Every sentence in your docs becomes an object of a specific kind. Each kind has its own schema, lifecycle rules, and agent permissions. The compiler enforces them.

::claim
Claim
A statement the organization believes is true. Requires evidence and an owner.
::decision
Decision
A position taken with rationale. Linked to ADRs. Cannot be silently reversed.
::constraint
Constraint
A rule the system must obey. Surfaces during code generation and review.
::procedure
Procedure
An ordered set of steps. Verifiable by replay; agent-executable when permitted.
::example
Example
Illustrative code, queries, or payloads. Compiled and tested with the docs.
::warning
Warning
A known sharp edge. Severity-graded. Always retrieved with related claims.
::policy
Policy
A binding rule with audit. Maps to controls. Patches require a reviewer.
::agent-instruction
Agent instruction
An explicit directive to an agent. Scoped, signed, and revocable.

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

— AgentDoc thesis · v0.1

03Three surfaces

Wherever you write,
wherever you ask.

The same compiler powers a CLI, an IDE language server, a query API, and a web app. One source of truth. Many ways in.

iCLI · adoc check

A compiler that fails loudly.

adoc checkvalidates schemas, freshness, scope coherence, and contradictions. Errors point to source lines with diagnostic codes — not “something is off”. CI-ready, single-binary, no daemon.

  • Diagnostic codes (E0341, W0118) you can grep
  • Stale evidence detection on every build
  • Strict mode for regulated knowledge
  • Output as docs.html + docs.agent.json
~/storywork-platform — adoc check
$ adoc check --strict billing/ Compiling billing.adoc Compiling refunds.adoc Validating 47 objects error[E0341]: claim contradicts a verified claim --> refunds.adoc:34 |34 | Credits are restored on refund within 24h. | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | = note: contradicts billing.credits.decrement-after-success = help: link via supersedes: or scope to env=staging warning[W0118]: evidence stale (verified 142d ago) --> billing.adoc:12 adoc check failed: 1 error, 1 warning, 17 ok
app.agentdoc.dev/storywork/billing.credits.decrement-after-success
::claimbilling.credits.decrement-after-successverified

“Credits are decremented after generation completes successfully, except during pending reconciliation.”

Owner
@platform-billing
3 reviewers
Evidence
2 sources
all current
Verified
2026-05-02
expires 88d
iiWeb · Knowledge Explorer

A workspace for organizational memory.

Browse claims, decisions, and constraints by owner, scope, and lifecycle. Open any object to see its evidence, its history, its agent permissions, and the patches waiting on a reviewer.

  • Evidence inspector with file + line links
  • Semantic diff: not what changed, what it means
  • Contradiction inbox with severity
  • Per-object agent permission panel
iiiIDE · Language server

Diagnostics where you already are.

The AgentDoc LSP runs in your editor. It checks every keystroke against the graph: stale claims, missing owners, contradictions, scope drift. Quick-fixes write valid metadata for you.

  • Inline diagnostics with code citations
  • Hover-peek for referenced claims
  • Quick-fix code actions for E0341, W0118, I0042
  • Workspace-wide find-references on any object ID
refunds.adocbilling.adoc
31::claim refunds.credits.restore-window
32 status: acceptedW0118 stale 142d
33 owner: @support-ops
34 Credits are restored on refundE0341 contradicts
35 within 24h.
36
37# Hover: billing.credits.decrement-after-success
38# "...decremented after generation completes."
39# verified · @platform-billing · 2026-05-02peek
40
41::example refunds.partial-cycleverified
04Capabilities

What a knowledge graph
does for you.

Beyond compilation: an evidence layer, a semantic diff engine, an agent patch protocol, and a permission model — all driven by the same source files engineers already write.

Evidence
Claims show their work.
Every assertion links to tests, code, runbooks, or external sources. Stale evidence ages the claim automatically.
Lifecycle
Status is data.
Draft, proposed, accepted, verified, stale, contradicted, superseded, revoked. Transitions are auditable.
Semantic diff
Not what changed — what it means.
A semantic diff explains the implication of a patch in the schema's terms, not in line numbers.
Scope
Truth lives where it lives.
Every object carries a scope expression — env, plan, region, version. Agents respect it during retrieval.
Agent patch protocol
Agents propose, humans review.
Agents cannot edit prose directly. They submit typed patches with proof obligations. Reviewers accept or reject.
Contradictions
Conflict is a first-class event.
When two objects disagree, the compiler flags it, attributes it, and refuses to retrieve either without resolution.
Ownership
Every object has a name on it.
Owners are required for verified objects. Routing, escalation, and review queues fall out of the graph.
Permissions
Read, cite, propose, apply.
Per-object agent permissions. A retrieval token cannot become an edit token. Tokens scope to a workspace.
Open format
.adoc is plaintext.
Your knowledge is yours. Source files are git-friendly. Compiled outputs are JSON. No lock-in.
05Roadmap

Boring infrastructure,
shipped quietly.

A compiler today. A graph next. A web app and IDE after that. Enterprise governance and an agent registry at v1.0. We ship in increments because correctness is a feature.

v0.1 · shipping
Compiler
CLI parses .adoc, validates, emits docs.html and docs.agent.json. Strict-mode rules.
  • adoc check / build
  • 11 object kinds
  • Diagnostic codes E0001–E0399
v0.4 · Q3 2026
Graph & query
A queryable knowledge graph. Semantic diff. Stale-evidence propagation across object relations.
  • adoc query
  • graph index format
  • relation walks
v0.7 · Q1 2027
Web app & LSP
The Knowledge Explorer, contradiction inbox, semantic review. Editor LSP for VS Code, Zed, Neovim.
  • app.agentdoc.dev
  • adoc-lsp
  • code actions / quick fixes
v1.0 · 2027
Agents & governance
Agent patch protocol, permissioned retrieval, audit trails, regulator-grade exports.
  • agent registry
  • patch proof obligations
  • SOC 2 export

Write what you believe.
Compile what you know.

The v0.1 compiler is open source today. Run it on a folder of .adocfiles. See your organization's beliefs typed for the first time.

Get startedRead the PRDgithub.com/agentdoc-dev/adoc ↗