@agent-teams/docs-protocol
A deterministic, repository-native documentation library and CLI for humans
and coding agents. It keeps Markdown/YAML as authority, provides safe
create-only authoring, advisory fuzzy search, bounded llms.txt context, and a
portable setup that does not require an Agent Teams managed repository.
The package is the portable application layer over direct dependencies on
@agent-teams/document-authoring and @agent-teams/repository-mutation. The
optional read-only MCP transport is published separately as
@agent-teams/docs-protocol-mcp.
Boundary
- Document Authoring owns authoring contracts, catalogs, Plans, Receipts, deterministic compilation, protected materialization, and strict sidecar merge.
- Repository Mutation owns the operation barrier, journal persistence, filesystem mutation safety, and exact-build recovery mechanism.
- Docs Protocol owns portable application and command semantics, the shared metadata vocabulary, relation queries, agent routing, and adoption checks.
- A consumer owns its data-only profiles, metadata schema, owners, templates, explicit reachability, and opaque semantic validator IDs.
Profiles cannot contain commands, hooks, callbacks, dynamic imports, remote
references, environment interpolation, or executable consumer code. Semantic
validator IDs are reported by docs:info and docs:check; this package never
executes them.
Portable quick start
Use the canonical community workflow to prove and install the exact artifact-qualified coordinate. It is the single authority for versions, registry pinning, package-manager support, and optional MCP pairing.
Portable bootstrap apply and recovery are initially POSIX-only. Windows is capability-qualified for read-only CLI and MCP use of authority initialized on a supported POSIX host, committed, and then cloned; local Windows bootstrap mutation is not yet a support claim.
Preview setup without writing:
docs-protocol init --project-id example/widgets \
--owner documentation/team --dry-run --json
Review the returned files and digest, then repeat the same authority inputs:
docs-protocol init --project-id example/widgets \
--owner documentation/team --apply \
--expect sha256:PLAN_DIGEST_FROM_PREVIEW --json
Bootstrap creates inert local profiles, a metadata schema, owners, Diataxis
templates and indexes, a documentation Skill, and one marker-bounded route in
AGENTS.md. It does not edit a package manifest, lockfile, workflow, or existing
create-only target. A changed preimage requires a fresh preview.
The generated docs.config.yaml is discovered automatically. Preview a decision:
docs-protocol new --type adr --id ADR-0001 --title "Portable documentation" \
--owner documentation/team --summary "Adopt portable documentation." \
--dry-run --json
Review its compiled bytes, then apply the new-document preview digest:
docs-protocol new --type adr --id ADR-0001 --title "Portable documentation" \
--owner documentation/team --summary "Adopt portable documentation." \
--apply --expect sha256:NEW_PLAN_DIGEST_FROM_PREVIEW --json
Add the returned markdownLink to the returned indexPath, then verify:
docs-protocol find "portable documentation" --fuzzy --json
docs-protocol context "portable documentation" --fuzzy --max-documents 12 --json
docs-protocol check --json
Fuzzy ranking and context are disposable advice; identity, metadata, paths, collision checks, and writes come from the canonical catalog. The public Node API exposes the same operations without a terminal.
See the community workflow for the complete safety contract.
Portable commands
Install this tooling package at one exact version in devDependencies, never in
production dependencies. The portable profile is docs.config.yaml; override
it explicitly with --profile and override the repository with --consumer.
new requires exactly one of --dry-run or --apply. Preview never reserves
an ID or writes. For reviewed Apply, pass its planDigest as --expect (Node:
DocsNewRequest.expectedPlanDigest). Malformed digests return invalid-input
(exit 2); a different compiled Plan returns authority-stale (exit 1). Both
have no mutation effects. --expect is valid only with --apply. Explicit
direct --apply without --expect compiles and applies current authority;
it does not claim approval of an earlier preview. Matching the digest still
requires current profile policy, authority, anchors, and transaction checks.
Apply creates only the planned document and reports the exact
index path and Markdown link; it never edits an index.
Every authoring request selects Document Authoring's closed
create-missing-real-directories policy. The resulting Plan v2 may create only
its verified missing parent chain and records directory evidence for recovery.
agent-teams-docs find --type adr --owner architecture/tooling --related ADR-0004
agent-teams-docs new --type adr --id ADR-0083 --title "Tenant isolation" \
--owner architecture/tooling --summary "Defines tenant isolation." \
--blocked-by ADR-0082 --metadata evidence='["test:tenant-isolation"]' --dry-run
All filters are combined with AND. Results use binary ID/path ordering and zero
matches are success. related, blocked_by, and code_anchors are the stable
v1 vocabulary. Repeat --code-anchor with one strict JSON value. Repeat
--metadata key=<strict JSON> for additional consumer-schema-validated data.
Profile routing
Portable profile v4 routes to a Document Authoring profile v3. Existing portable profile v3 remains readable with its historical semantics. Document Authoring alone loads inline frontmatter and any declared metadata sidecar, performs the strict path-to-full-metadata merge, validates the final instance, and exposes a bounded inert metadata projection. Docs Protocol never reparses documents.
The referenced Document Authoring profile is the only authority for authorable
types, identity, placement, heading, owners, required metadata, and explicit
reachability. not-required requires a human-readable reason; omission is
invalid. The Docs Protocol profile contains only routing, protocol identity,
the agent Skill route, opaque semantic validator IDs, and v4's required data-only
relations.blockers policy. Its types and statuses admit blocker targets;
subjectIncompatibleStatuses forbids blockers on those subject states. Starter
v4 data permits proposed ADR/Diataxis blockers; consumers choose their own
vocabulary. Profile v4 migration records wire identities,
frozen v3 compatibility, portable path rules, migration and rollback.
Metadata JSON Schema format is an annotation: Document Authoring uses
validateFormats: false. It does not assert URI, date, or other format validity.
Use explicit supported schema constraints when validity is required.
The data-only feature example demonstrates
consumer-owned DDD/Clean boundaries using the existing source policy schema.
The portable JSON schemas are exported under
@agent-teams/docs-protocol/schemas/*.
Machine output uses one JSON envelope with protocol ID/version and stable exit
codes: 0 success, 1 violation/conflict/stale/recovery, 2 invalid input, 3
execution failure, and 130 cancellation.
Human --help, subcommand --help, and --version use stdout and exit 0.
With --json, help/version return a schema-valid invocation error on stdout,
exit 2, and empty stderr; their human text has no JSON success contract.
Generic v1/v2 commands retain their existing envelope shapes. Portable
init, bounded context, and opt-in fuzzy find use the additive v3 envelope;
default exact find remains v2. Consumers must dispatch on schemaVersion and
validate against the matching exported schema.
Recovery is bound to the persisted transaction and exact installed Document
Authoring build, so it does not parse mutable authoring profiles before
resuming. Historical wire names that contain foundation remain unchanged
persisted contract identities.
Consumer qualification
@agent-teams/docs-protocol/qualification exports
runDocsProtocolQualification. A consumer supplies a deliberately disposable
fixture and one authoring scenario. The runner copies that fixture into its own
temporary directory, then proves info, deterministic find, preview/apply parity,
explicit reachability, check, doctor, and recovery end to end. It rejects fixture
symlinks, verifies that the source tree did not change, and removes only the
temporary directory it created.
Managed cohort qualification is intentionally outside this package. Agent Teams users
install @agent-teams/docs-protocol-agent-teams and use its distinct
agent-teams-docs-managed executable; the portable core neither discovers nor
imports that adapter.