documentation-engine 0.3.1

Provider-neutral structured Markdown documentation engine.

Documentation Engine

Documentation Engine is a provider-neutral toolkit for maintaining structured Markdown knowledge that remains usable by humans and AI clients as a project grows.

The published documentation-engine package is pre-1.0. Public contracts may still evolve as adopter evidence exposes reusable compatibility requirements.

Complete access. Task-sized reads.

Every cataloged document remains fully available to the agent. Documentation Engine reads original Markdown in structured, task-relevant fragments and expands to related sections or complete documents on demand.

"Task-sized" means selected according to the current task, document relationships, and explicit requests—not compressed, summarized, or truncated to fit an arbitrary token budget. Sections outside the initial read are listed explicitly and remain available by anchor or as complete documents. An operation that claims a complete dependency answer fails closed when that completeness cannot be established.

The graph measures how much original documentation had to be loaded initially for three predefined tasks over a real 6.41 MB legacy Markdown corpus containing 292 documents. Each task retained access to the entire catalog and passed its predefined document and section coverage requirements. Lower initial reading is better when those quality requirements remain satisfied.

The efficiency comes from structured, on-demand reading rather than rewriting source material:

Read on demand instead of upfront	Quality safeguard
Unrelated documents	Selected source Markdown verbatim
Unrequested sections	Explicit omitted-section list and addressable anchors
Repeated full-corpus reads	Stable IDs, revisions and dependency coverage
Unproven dependency results	A fail-closed error instead of silent incompleteness

Omitted content is neither destroyed nor hidden. It remains in the Markdown source of truth and can be requested by section anchor or as a complete document.

Scenario	Required documents	Required sections	Packet	Corpus read	Reduction
Architecture analysis	4	6	120.7 KB	1.88%	98.12%
Roadmap phase	4	7	123.6 KB	1.93%	98.07%
Research continuation	4	9	60.2 KB	0.94%	99.06%

Each task passed a quality guard: every predefined required document and section was present, and every selected document carried an explicit coverage line. Navigation excerpts and requested sections remained verbatim Markdown. The smaller packet comes from excluding unrelated documents and unrequested sections, not from rewriting or degrading the selected material. The baseline is deliberately specific: reading every Markdown byte, not every possible manual or competing retrieval strategy. UTF-8 bytes are a deterministic provider-neutral proxy for context volume, not tokenizer-specific token counts or a claim about total engineering productivity.

See the measurement methodology for the corpus, shadow-overlay, formulas, quality checks and limitations. The chart is a static measured snapshot; it does not publish an unqualified forecast for larger corpora.

Get started

Installation

Choose one installation path. Do not run both published-package commands.

CLI and Python package

For local command-line use and Python imports:

pip install documentation-engine

CLI with MCP support

If an MCP host will launch Documentation Engine as a local stdio server, use the optional extra instead:

pip install "documentation-engine[mcp]"

The MCP extra includes the base package. It does not create or host a shared documentation service; it adds the SDK needed for an MCP client to launch the local docsystem-mcp adapter. See the MCP adapter guide for host configuration and the security boundary.

Contributor or unreleased checkout

Contributors and anyone intentionally tracking unreleased development should use the repository checkout rather than the published package:

git clone https://github.com/Jafa7/DocumentationEngine.git
cd DocumentationEngine
uv sync

Run development commands through uv run; do not mix this checkout with an unrelated globally installed docsystem executable.

Verify the selected installation

For a published-package installation:

docsystem --version
docsystem --help

For a contributor checkout:

uv run python -m docsystem --version
uv run python -m docsystem --help

The distribution is documentation-engine; the import package, docsystem and docsystem-mcp console scripts, and .docsystem.toml/.docsystem/ project files keep their existing names. Installation only makes the commands available and does not modify a project. Continue with Connecting Documentation Engine to your project to configure one deliberately.

Connecting Documentation Engine to your project

Connecting is project configuration, not package installation. It means choosing the documentation root and privacy boundary, reviewing or creating .docsystem.toml, validating the existing Markdown, and then writing the disposable projection. It does not require MCP.

Agent-guided setup

If you are an AI agent asked to connect a project: follow docs/setup-guide.md step by step. It contains the connection/adoption flow, required user questions, backup-policy setup and checks. Do not improvise a private documentation root or local backup path, and do not commit private planning paths.

If you are a human using an AI agent, paste this in the project you want to connect:

Connect Documentation Engine to this project.
Repository: https://github.com/Jafa7/DocumentationEngine
Read docs/setup-guide.md in that repository and follow it exactly.
Ask me for the exact private-documentation location before creating or moving
documents. Recommend a dedicated external project directory, but do not invent
or create a shared workspace path. If private documents already exist inside
the project, copy and verify them first and leave the original untouched until
I explicitly authorize its removal.
Ask me where local disaster-recovery backups should be stored before touching
ignored/private documentation or local configuration.

Manual setup

For a manual adoption, follow the same setup guide. Start with its fact-gathering and backup steps rather than running init blindly against an existing documentation tree. The compact readiness command will then report the next safe action:

docsystem readiness /path/to/project

Independent local documentation sources

For one project's external private documentation, place its complete profile in a local or mounted folder and use the ignored .docsystem.project.local.toml pointer. Commands and generated agent rules keep using the checkout path; generated rules do not embed the private absolute target, and the agent is instructed not to inspect parent or sibling directories. Filesystem-oriented operator output such as doctor remains private and may identify the resolved documentation root.

If several independently owned profiles need trusted cross-project queries, use workspace source selection to register and address them by name. Folder separation and instructions are not OS security; use sandbox/filesystem boundaries for untrusted callers.

Principles

• Markdown is the editable source of truth.
• Stable IDs survive file moves and title changes.
• Generated indexes are deterministic projections, never a second truth.
• Human navigation and machine retrieval use the same dependency model.
• Context selection exposes omissions instead of silently truncating meaning.
• Mechanical maintenance is automated; semantic decisions remain reviewable.
• AI integrations are adapters around a provider-neutral core.

Capability levels

Documentation Engine installs one package, but its capabilities are opt-in by task rather than one mandatory process:

Level	Purpose	Typical use
Core retrieval	Discover, read and inspect context/impact	Default for routine work
Adoption	Connect or migrate an existing Markdown corpus	Setup and compatibility work
Governed delivery	Roadmaps, admission, handoff and lifecycle evidence	Multi-stage, delegated or risk-bearing work
Bounded mutation	Journaled managed-block synchronization and recovery	Explicitly approved mechanical writes
Multi-source	Workspace selection and federation	Deliberate cross-project documentation queries

Start with core retrieval. The presence of configured governance does not make a routine correction follow the full lifecycle. See the architecture capability map and proportional agent contract for exact boundaries.

For work that splits into a new chat, module, repository or long-running idea, use the Workstream / Idea Branching pattern so the child context carries its inherited context, boundaries and return protocol.

For problems found while adopting Documentation Engine in another project, use the adopter reporting policy and issue templates. Reports start with compact diagnostics and sanitized evidence, not private document bodies or unbounded logs.

Documentation

Use the documentation map to find the canonical guide for setup, adoption, architecture, agent behavior, integrations, safety, reporting and releases. Specialized guides link back to their owning contract instead of repeating it.

Development and release verification

Contributor workflow and risk-based checks are defined in CONTRIBUTING.md. Packaging and publication are defined in the release guide. The contributor checkout uses uv run python -m docsystem ...; published-package consumers use the installed docsystem command. scripts/installed_cli_smoke.sh verifies that boundary.

CLI overview

This is a command reference, not a required sequence. Most routine tasks need only readiness, task-sized context/read, and optionally change-plan. Use the advanced capability groups above only when their applicability condition is present.

docsystem init .
docsystem doctor .
docsystem show-config .
docsystem catalog .
docsystem catalog . --explain
docsystem catalog . --explain --json
docsystem validate .
docsystem validate . --verbose-adoption
docsystem read DOC-001 .
docsystem read DOC-001 . --list
docsystem read DOC-001 . --anchor purpose
docsystem dependencies DOC-001 .
docsystem dependencies DOC-001 . --reverse
docsystem references DOC-001 .
docsystem references DOC-001#purpose . --reverse
docsystem references DOC-001 . --transitive
docsystem references DOC-001 . --json
docsystem change-plan DOC-001 .
docsystem change-plan DOC-001#purpose . --reverse
docsystem change-plan DOC-001 . --transitive
docsystem change-plan DOC-001 . --json
docsystem change-plan DOC-001#purpose . --with-delivery --json
docsystem maintenance install-version . --check
docsystem maintenance install-version . --preview
docsystem maintenance install-version . --check --json
docsystem maintenance install-version . --preview --expect-source-hash SHA256
docsystem maintenance install-version . --write --expect-source-hash SHA256 --workstream-id WS-001
docsystem maintenance-recover 20260714T100000Z-WS-001 .
docsystem context DOC-001 . --depth 1
docsystem context DOC-001 . --depth 1 --json
docsystem context DOC-001 . --compact --json
docsystem context DOC-001 . --outline
docsystem context DOC-001 . --outline --json
docsystem context DOC-001 . --view task --json
docsystem context DOC-001 . --assume-known DOC-001@3
docsystem context DOC-001 . --since 0a1b2c3d4e5f
docsystem impact DOC-001 .
docsystem graph-health .
docsystem graph-health . --json
docsystem metadata-inventory .
docsystem metadata-inventory . --field owner --values --json
docsystem profile-check .
docsystem profile-check . --json
docsystem promotion . --request promotion-request.json --json
docsystem delivery-map .
docsystem delivery-map . --json
docsystem delivery-map . --contract DOC-001#purpose --json
docsystem criteria .
docsystem criteria . --json
docsystem roadmap status .
docsystem roadmap next . --json
docsystem roadmap explain automated-validation .
docsystem workstream WS-001 . --record workstream-record.json
docsystem workstream WS-001 . --record workstream-record.json --json
docsystem intake . --request idea-intake-request.json --json
docsystem admission WS-001 . --request execution-admission-request.json --json
docsystem execution-handoff WS-001 . --admission execution-admission-request.json --json
docsystem execution-result WS-001 . --packet execution-packet.json --result execution-result.json --json
docsystem lifecycle WS-001 . --admission execution-admission-request.json --packet execution-packet.json --result execution-result.json --record workstream-record.json --json
docsystem migration-report .
docsystem migration-report . --json
docsystem readiness .
docsystem readiness . --json
docsystem finish DOC-001 .
docsystem finish DOC-001 . --json
docsystem finish DOC-001 . --context-expansion material-gap --context-gap-report drafted
docsystem finish WS-001 . --workstream-record workstream-record.json --json
docsystem report draft . --project-name "My Project" --type adoption-finding --source codex
docsystem report context-gap . --project-name "My Project" --type adoption-finding --source codex --reason missing_dependency --initial DOC-001#summary --expanded DOC-002#constraints --impact decision
docsystem migrate .
docsystem migrate . --apply
docsystem index . --write
docsystem changes .
docsystem changes . --json
docsystem agent-instructions .
docsystem agent-instructions . --json
docsystem workspace list . --workspace /path/to/workspace
docsystem workspace doctor . --workspace /path/to/workspace
docsystem context DOC-001 . --source example-project

init creates a project-local .docsystem.toml and the configured documentation root. It does not create empty documentation hierarchies.

catalog lists Markdown source files under paths mapped by logical roles in [areas]. catalog --explain classifies every Markdown file as included, excluded or unmapped. Unmapped Markdown is a validation error rather than a silent omission.

Catalog exclusions are optional, ordered POSIX globs relative to the documentation root:

[catalog]
exclude = ["templates/*-template.md"]

The first matching pattern is reported as the exclusion reason. An area mapped to . owns root documents and acts as a fallback when a more specific area does not match. validate requires each included document to be linked from the nearest README.md or index.md; nested indexes must themselves be linked from the nearest parent index. doctor includes membership, navigation and metadata validation.

Every cataloged Markdown document starts with YAML front matter containing a stable id and positive revision. Semantic relations use local stable IDs: derived_from, depends_on, related and supersedes contain ID lists; validated_against contains ID@revision freshness pins. A registered multi-catalog workspace may additionally author quoted source::ID and source::ID@revision targets for federated reads. Unknown fields are preserved for project-specific policy. Duplicate YAML mapping keys are invalid at every nesting level.

An overall roadmap may opt into the program_plan contract. roadmap status/next/explain then derives active, ready, waiting, delivered and deferred work from authored prerequisites and bounded roadmap lifecycle state. It provides a deterministic sequence for agents without creating a parallel task database or granting execution permission. Its source contracts are non-exclusive planning scope; verified delivery ownership remains in delivers and delivery-map.

read resolves a whole document, navigation prefix or ATX section by stable ID. read --list emits anchor, Hn, start:end and title as tab-separated fields in document order.

A heading may declare a stable canonical anchor on the immediately preceding line:

<a id="stable-section"></a>
## Section title

name is also accepted, as are single quotes. The standalone tag may contain only the id or name attribute. Anchor values start with a Unicode alphanumeric character and then use Unicode alphanumerics or -_.:. The value is preserved exactly. Malformed, orphaned, multiple, duplicate or colliding anchors are errors rather than silently repaired.

Navigation may extend the default prefix through the furthest matching H2:

[navigation]
extend_through = ["summary", "contents"]

If no configured anchor exists in a document, the original prefix before the first H2 is returned. A configured anchor resolving to another heading level is an error.

Projects may define progressive, purpose-specific authored context views:

[context.views.map]
tier = 1
delivery = "outline"
direction = "both"
depth = 0
relations = []
layers = ["authored"]

[context.views.task]
tier = 2
delivery = "navigation"
direction = "forward"
depth = 1
relations = ["depends_on", "derived_from", "validated_against"]
layers = ["authored"]

context ID PROJECT --view NAME applies that policy and emits the selected view plus every edge stopped by relation-filter or depth-limit. View names and tiers are stable project policy. The only currently supported layer is authored; observed links and generated containment remain available through references but cannot silently enter a context view. A view replaces manual --depth, --include-related and --outline; navigation views still allow explicit --include ID#anchor. A view controls the initial packet, not access: agents can always request another section or the full Markdown source.

dependencies reports deterministic forward or reverse semantic edges. It fails without partial stdout when metadata errors make the requested graph incomplete; stale revision warnings remain non-blocking.

graph-health PROJECT [--json] gives an inspectable whole-catalog inventory: document and section counts, edges by authority/relation, explicit boundaries, weak components, orphans, stale/historical pins and missing configured metadata. Metrics are facts; smell signals such as hubs, concentrated boundaries or disconnected components appear only when the project enables a threshold in [graph_health]; objectively missing Markdown anchors are always identified as dead references. Signals are advisory and never grant write authority. A structurally ambiguous graph fails closed with no partial stdout. See graph health for the configuration and output contract.

metadata-inventory PROJECT [--json] discovers the metadata vocabulary that the catalog actually uses and reports body-free per-document graph facts. By default it exposes field names, coverage and types but not additional metadata values or Markdown bodies. --field NAME --values is the explicit, bounded drill-down for one field. The result is observed evidence rather than schema authority, and invalid catalogs fail closed without partial stdout. See metadata and graph inventory for the privacy and output contract.

profile-check PROJECT [--json] validates matching document types against an optional project-authored [profiles] registry: required metadata, semantic roles expressed through canonical anchor aliases, allowed relations/statuses, and declared history mode. Unprofiled types remain visible for gradual adoption. The command never infers policy from inventory or changes Markdown. See document profiles for the configuration and failure contract.

promotion PROJECT --request PATH [--json] builds a body-free, evidence-backed plan for moving reviewed knowledge into its unique canonical owner. It uses explicit authority_for metadata and the destination profile's history mode, reports competing owners and impacted consumers, and never writes or deletes Markdown. See knowledge promotion.

delivery-map PROJECT [--contract ID#anchor ...] [--json] uses optional project-authored traceability metadata to map exact ID#anchor source contracts to delivery ownership and a profile-defined evidence section. Its deterministic output contains addresses and status, never Markdown bodies. Untracked delivery documents remain visible for gradual adoption. Repeatable --contract limits output to task-sized mappings and reports exact contracts without a configured owner under unowned_contracts; malformed claims fail delivery-map, validate and doctor. See delivery traceability for the configuration, targeted lookup, overlap and authority contract.

references ID[#anchor] PROJECT is a read-only inspection of the section and reference graph: authored metadata relations, observed Markdown links, and generated section containment, each tagged with its authority so an observed link or a generated containment edge is never mistaken for write permission. --reverse lists incoming edges, --transitive expands beyond direct neighbors, and --json carries the same rows structurally. Unknown addresses and metadata errors that make the requested graph ambiguous fail closed with no stdout; unresolved targets (external URLs, non-document resources, and missing anchors) remain visible, non-blocking boundaries. Relation-specific cycle diagnostics (depends_on, derived_from and supersedes are errors; related and observed references cycles are allowed) surface through doctor/validate, which cover the whole graph, rather than blocking an individual references call. It prefers a verified projection and reads only the shards a query touches, falling back to direct Markdown with one diagnostic on any staleness or corruption — either path produces byte-identical stdout.

change-plan ID[#anchor] PROJECT is a read-only explainable change plan built on the same graph: the requested document or section is always a read item at distance 0; an authored depends_on edge adds its target as read; everything else an agent should look at before changing the target — observed Markdown references, --reverse incoming impact, and authored related, derived_from, supersedes or validated_against edges — is review, never a promoted read. Generated section containment can prove a transitive path to a section-owned reference, but generated sections are not emitted as plan items and never expand a whole document by default. When more than one edge reaches the same address, the plan keeps one item and lists every distinct reason instead of picking one arbitrarily. --transitive expands both directions with a deterministic minimal proving path per reason. Completeness is reported per graph layer (authored, observed, generated) instead of one collapsing flag, and unresolved targets remain visible boundaries with their source address. There is no --write/--apply: like references, this command never edits Markdown.

For an exact section, opt-in --with-delivery adds a separate review-only layer containing authored delivery owners and their evidence. The layer reports owned, overlap, unowned or unconfigured; it never promotes an owner or historical evidence to read or write authority.

maintenance TARGET PROJECT --check|--preview|--write manages one project-declared [[maintenance]] target: a canonical source_document/source_anchor block and its bounded occurrences, each with an opt-in role (current, historical, example, snapshot or unmanaged). Only a current occurrence is preview eligible; every other role is reported as excluded evidence, never diffed. The block is delimited by exact <!-- docsystem:source target=NAME -->/ <!-- docsystem:managed target=NAME --> HTML-comment markers, one per line and inert inside fenced code. --check and --preview are read-only and print the same deterministic result; --check exits 0 clean or 2 on drift (a documented, non-error code), while --preview always exits 0 for a valid target. Invalid config, an unknown target/address or a graph-blocking error exit 1 with empty stdout. Reports include exact line ranges and content hashes for review and stale-input guards. Pass a previously reported source block_hash with --expect-source-hash to fail closed if the canonical block changed between inspection steps. --write additionally requires --workstream-id; it changes only drifted current block interiors in one journaled transaction, validates the rebuilt catalog/graph, and rolls back every touched file on failure. Other roles are never written. A successful write refreshes the disposable projection; refresh failure is a visible warning and direct Markdown remains authoritative. maintenance-recover GENERATION restores verified before bytes only when current files still equal that generation's after state, so newer authored work is never overwritten.

For a project selected from a local workspace, workspace.toml must explicitly set write = "managed-maintenance" (the default is none). The selected write also requires the preview's preview_sha256; selected recovery requires the journal manifest_hash. Each source has its own journal and lock. A source write never becomes an implicit cross-source transaction, and the aggregate federation projection remains stale until explicitly rebuilt. See workspace source selection.

Existing projects may opt into a migration bridge for relative path relations:

[relations]
legacy_paths = "resolve-with-warning"
snapshot_types = ["review", "experiment"]
snapshot_rules = [
  { source_type = "roadmap", source_status = "completed" },
]

Strict stable-ID relations remain the default. In the compatibility mode, resolvable paths become canonical graph edges and emit migration warnings. External URLs, resources and paths outside the catalog are never document relations, so they remain explicit, non-blocking boundaries in both strict and resolve-with-warning mode. A relative path that does resolve to a cataloged document is a real document relation: in strict mode it is a blocking error until it is migrated to a stable ID or the project opts into resolve-with-warning. migration-report reports both resolved mappings and boundaries as a deterministic dry-run, independent of the current relations.legacy_paths mode, without editing Markdown.

snapshot_types classifies every pin owned by the listed document types as historical. snapshot_rules is the narrower alternative: each rule matches the pin-owning document by optional source_type, source_status, or both. Matched stale pins remain visible as historical snapshot in context, impact and finish packets, but are not freshness warnings in validate, doctor or readiness. Unmatched pins retain normal stale-warning behavior.

By default, validate and doctor summarize expected resolved mappings and resource boundaries by count while printing stale pins and other warnings individually. Pass --verbose-adoption to either command for every row-level adoption warning. migration-report always remains the complete deterministic inventory.

readiness is a read-only report for adopting an existing Markdown project. It distinguishes blocking structural/configuration errors, resolvable legacy relation migrations, explicit unresolved/resource boundaries, stale freshness pins and projection state (absent/stale/current), and prints the single safe next command. It never writes to Markdown, configuration or the projection cache.

finish produces a compact handoff packet for returning a workstream or document-focused task to its parent context. It summarizes included context, omitted H2 sections, migration boundaries and stale versus historical snapshot pins. A project can opt into a stricter, versioned completion contract with workstreams.criteria, inspect it with criteria, validate a bounded JSON lifecycle/evidence record with workstream and require that record through finish --workstream-record. The strict gate preserves corrective attempts, requires configured check/review/change/omission/risk/return evidence and fails without a handoff when the completion claim is incomplete. See bounded workstream evidence.

intake evaluates a bounded, agent-prepared semantic request against a versioned project criterion. It deterministically selects one existing owner, proposes an ordinary draft or workstream, or returns an explainable blocked decision. The command is read-only: a proposed ID/path is not reserved and no Markdown is created. The engine validates addresses and policy but does not pretend to infer the human idea or verify an agent's semantic claims. See deterministic idea intake.

admission validates a bounded A0–A2 workstream intent before another agent or orchestrator executes it. Versioned project policy limits stable targets, local actions, risk, verification and required authorization evidence. It returns admitted or an explainable blocked result without running a worker or changing source. Commit, push, merge and release are deliberately outside this initial contract. See bounded execution admission.

execution-handoff freezes an admitted intent, mandate, exact target hashes and graph-derived read/review manifest into a bounded, body-free packet for an external executor. Verify the saved packet immediately before execution; any source, graph, policy or admission drift fails closed. Original Markdown remains fully available on demand. See immutable execution handoff.

When project policy requires it, admission also binds normalized local source paths to their pre-edit hashes (or explicit absence). After an executor returns, execution-result validates its structured changed-file inventory against that scope and current after-hashes. The inventory remains a caller assertion: use an authoritative host/runtime diff rather than worker prose.

lifecycle is the final read-only cross-artifact gate. It proves that the admission request, immutable packet, changed-file result and completed workstream record belong to one lineage, that all admitted targets are covered and that accepted independent review evidence is present. It does not execute, approve, commit or publish the result. See end-to-end workstream lifecycle evidence.

report draft produces a privacy-safe GitHub issue body for adopter runtime reports, adoption findings, core bugs or documentation pattern requests; it is read-only and leaves expected/actual/requested-action fields for the reporter to fill in.

When progressive reading exposes a reproducible context-coverage gap that materially changes the work, report context-gap adds body-free initial and expanded address evidence to the same adopter report format. Ordinary full-review, follow-up and precautionary reads remain normal behavior and are not reported. The agent always retains complete access to authored Markdown; the feature measures gaps in task-sized delivery rather than limiting source access.

An agent can carry only the classification back in finish: normal requires no report, while material-gap requires a drafted or filed report state. The default handoff stays byte-compatible when no classification is supplied.

agent-instructions prints a deterministic Markdown snippet — naming the configured documentation root, language, areas and identifier namespaces plus the configured purpose views and core agent rules (pass the project root explicitly, start with readiness --json, prefer --json, use the lowest suitable view, expand context deliberately, never run a mutating command without approval, follow local backup policy) — for pasting into an adopting project's AGENTS.md/CLAUDE.md. It is read-only, reads only project configuration and works even when the documentation root itself is missing, so the pasted snippet can never drift from docs/setup-guide.md Step 7 by hand-copying. Configured intake, admission and lifecycle guidance is emitted as conditional policy for durable ideas or governed/delegated/risk-bearing work; it does not turn a routine correction into a full evidence lifecycle merely because criteria exist.

readiness, migration-report, catalog --explain, changes, context, criteria, workstream, intake, admission, execution-handoff, execution-result, lifecycle and agent-instructions accept --json and print one deterministic JSON value (sorted keys, stable field names) instead of text, carrying the same information the text form prints plus what it sends to stderr, so a machine client never has to parse human prose. Every --json root is an object carrying "schema_version": 1; the version is bumped only on a breaking change to an existing field, so a consumer can detect format evolution without guessing. Exit codes are unchanged by --json. context --outline (with or without --json) prints section size maps instead of content for the same selected document set, so an agent can budget tokens with a cheap map before fetching.

An MCP adapter exposes the read-only commands as typed tools for any MCP-capable client; see the MCP adapter guide. It is a thin wrapper over this CLI contract and requires the optional MCP installation described in Installation. Text tools keep exact CLI stdout for compatibility; packet variants add non-fatal diagnostics such as projection fallback warnings.

migrate previews, by default, every legacy relation value that migration-report already classifies as unambiguously resolved. Preview is read-only. migrate --apply re-validates the same plan against a scratch copy of the documentation tree and then rewrites only the exact resolved scalar in derived_from, depends_on, related or supersedes for each affected document — front matter formatting, comments, unknown fields, the document body and unresolved boundaries are left byte-for-byte untouched. Multi-file runs are all-or-nothing: if validation or a write fails, no file is left partially migrated. Re-running migrate --apply after a successful migration reports no further changes. Once every resolvable legacy relation has been migrated, a project whose remaining legacy values are all boundaries (URLs and resources) can drop relations.legacy_paths = resolve-with-warning and use strict mode without those boundaries becoming errors.

context emits a deterministic Markdown packet containing navigation excerpts, semantic dependencies, explicit section selections, H2 coverage, omissions, stale pins and unresolved boundaries. It never silently truncates to a token budget. The packet ends with a Packet stats section reporting how many documents and explicit sections were included, how many H2 sections were omitted, and the line/byte size of the packet body above it, so a client can budget a follow-up --depth or --include expansion without re-measuring the output. context --json additionally exposes each document's typed revision and lists "sections": each section's anchor, title, level, lines and exact UTF-8 bytes size, in document order, so a client can retain the revision for a later --assume-known call and budget without fetching content first. The existing navigation field keeps its complete Markdown prefix, including YAML front matter. context --outline prints the same document set (--depth and --include-related still apply) with those section size tables instead of navigation excerpts or content — a cheap "map first, fetch second" packet. context --compact is the lossless content-delivery form for agents. It merges overlapping navigation, parent-section and child-section line ranges, so each source range appears once. Every requested address remains in content_manifest with its reasons, source line range, carrier fragment and delivery classification; content_fragments contains the original Markdown and its SHA-256. Document-level inclusion_reasons preserve every graph path that selected the document. Compact text aggregates repeated nonblocking adoption/view diagnostics and points to --json, which retains every row; stale/historical pins and unresolved boundaries remain individual. Compact delivery does not summarize content, impose a token budget or restrict later reads, and it cannot combine with outline delivery. Compact JSON assumes the outline-first workflow and omits the repeated full sections size map; it remains available through --outline or read --list. When --view NAME is selected, JSON adds purpose_view and deterministic view_omissions; text packets show the same policy and omission rows. Reverse view inclusions are labeled reverse:RELATION, so downstream context cannot be mistaken for an authored forward dependency. Reverse and bidirectional views fail closed unless the complete catalog semantic graph is valid; a broken document elsewhere could otherwise hide an incoming edge. Without --view, existing text and JSON output remain unchanged. --outline combines with --json for the structured form, but not with --anchor or --include, which select content the outline never returns. context --assume-known ID@REV (repeatable) lets an agent declare a document it already holds: when that document lands in the packet and its current revision still equals REV, its navigation excerpt is omitted and its coverage line becomes content omitted — declared known at revision REV (current), while --include ID#anchor still forces those explicit sections. A stale declaration (revision moved on) keeps full content and records a mismatch note, so a declared cache never silently hides a change. context --since GENERATION requests a delta against a retained projection generation (full hash or an unambiguous prefix of at least twelve characters): unchanged documents are omitted with an unchanged since GEN12 coverage line, changed documents keep navigation and gain a ### Changed section block per changed H2 not already covered by navigation (a changed H1 or navigation.extend_through H2 is already served by the navigation excerpt), and a document absent from that generation is reported as new and served in full. Removed anchors and semantic metadata before/after values are reported separately, and a source change outside addressable sections is explicit. A requested --anchor or --include still wins over unchanged-content omission. The retained generation is verified against its manifest, document and reverse shards, active configuration fingerprint and reconstructed generation hash before it can authorize any omission. --since cannot combine with --assume-known, and neither combines with --outline; every rejected combination fails closed with no packet. impact reports reverse metadata dependencies and distinguishes semantic, related-navigation, freshness and configured historical-snapshot relations.

index --write derives immutable generations below .docsystem/cache, hashed over both the derived content and a fingerprint of the projection- relevant configuration, then atomically selects the current generation. index checks freshness and changes reports changed documents and sections. read, context and impact serve from the verified projection when it is current: verification re-hashes every included source byte-for-byte, checks the configuration fingerprint, and reconstructs the generation hash from the shards, so a served read can never disagree with the Markdown truth or the active configuration, while Markdown, metadata and link parsing plus graph reconstruction are skipped. When the projection is absent, stale, corrupt or incompatible, reads visibly fall back to direct Markdown with a stderr diagnostic and identical output. Markdown remains the only editable truth.

See the adoption guide for a complete profile and migration sequence, the AI client integration guide for downstream consumer guidance, and the agent contract for how an AI client should safely drive this CLI. Projects that keep private documentation or local configuration outside git should also define a local backup command; see local state safety.

For several independent catalogs, register them in a local workspace and use qualified source::ID[#anchor] reads:

docsystem federation catalog . --workspace /path/to/workspace --json
docsystem federation context project-a::DOC-001 . \
  --workspace /path/to/workspace --depth 1 --json
docsystem federation references project-a::DOC-001#purpose . \
  --workspace /path/to/workspace --transitive --json
docsystem federation impact shared-guides::GUIDE-004 . \
  --workspace /path/to/workspace --json
docsystem federation index . --workspace /path/to/workspace --write
docsystem federation changes . --workspace /path/to/workspace --json
docsystem federation finish WS-001 . --workspace /path/to/workspace \
  --record shared-finish.json --json

Cross-source relations stay in Markdown as authored "source::ID" metadata. Federated queries require every registered source to be available and valid, preserve task-sized source text with visible omissions, and never grant cross-source write authority. A workspace-owned incremental projection reuses unchanged source objects and skips repeated parsing while keeping direct/projected output identical. Narrow selected-source managed maintenance is opt-in and separately guarded. A read-only shared finish packet can verify caller-declared independent source outcomes without claiming atomicity; see multi-catalog federation.

Deliberate project-local boundaries

Registry synchronization, distributed write orchestration, private history/backup and provider-specific adapters are not generalized by this vertical slice. They remain project-local until reusable contracts are proven.

Contributing

See CONTRIBUTING.md for contributor setup and required checks, and SECURITY.md to report a vulnerability.

License

Documentation Engine is available under the MIT License. Copyright (c) 2026 Oleg Synelnykov (Jafa7).