documentation-engine 0.3.1__tar.gz → 0.5.0__tar.gz

{documentation_engine-0.3.1 → documentation_engine-0.5.0}/.github/workflows/ci.yml

@@ -83,7 +83,8 @@ jobs:
           $env:TMP = $env:RUNNER_TEMP
           $env:TEMP = $env:RUNNER_TEMP
           uv run pytest tests/test_cli.py tests/test_cli_platform.py `
-            tests/test_context_cli.py tests/test_mcp_adapter.py tests/test_readiness.py
+            tests/test_context_cli.py tests/test_mcp_adapter.py tests/test_readiness.py `
+            tests/test_provider_artifact.py
 
       - name: Installed CLI UTF-8 PowerShell smoke
         shell: pwsh

{documentation_engine-0.3.1 → documentation_engine-0.5.0}/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to Documentation Engine are documented in this file.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-09
+
+### Highlights
+
+- Adopters can consume one complete, immutable and body-free provider artifact
+  without implementing Documentation Engine pagination or importing package
+  internals.
+- Standalone verification binds provider identity, exact retained generations,
+  scope, completeness, ordered entity evidence and a deterministic digest while
+  rejecting corrupt, partial or incompatible artifacts fail closed.
+
+### Added
+
+- Complete `traceability-provider-v1` snapshot and comparison artifacts hide
+  provider pagination from adopters, bind deterministic digests and can be
+  verified without project state while preserving the retained-generation
+  boundary of the paged provider contract.
+
+## [0.4.0] - 2026-08-09
+
+### Highlights
+
+- External consumers can reconcile exact retained documentation generations
+  through a provider-neutral, privacy-safe contract without importing package
+  internals or reading generated projection files directly.
+- Pinned comparison distinguishes content changes, relocation and genuine
+  entity absence while failing closed for unavailable, corrupt, unsupported or
+  incomplete provider evidence.
+
+### Added
+
+- Opt-in, provider-neutral `provider snapshot` and `provider compare` commands
+  export bounded body-free observations from explicitly pinned immutable
+  generations and classify exact stable entities as relocated, changed,
+  missing or added.
+- Projection schema 5 binds provider identity, visibility, advertised
+  capabilities, catalog completeness, coverage, document line counts and
+  explicit/generated anchor kind into the generation hash. Older generations
+  fail provider export as unsupported instead of receiving retroactive claims.
+
 ## [0.3.1] - 2026-07-19
 
 ### Fixed
@@ -197,7 +237,9 @@ documentation-engine` starts working only after the first successful release.
 - Measured context-reduction methodology and a reproducible consumer-install
   smoke test.
 
-[Unreleased]: https://github.com/Jafa7/DocumentationEngine/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/Jafa7/DocumentationEngine/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/Jafa7/DocumentationEngine/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/Jafa7/DocumentationEngine/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/Jafa7/DocumentationEngine/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/Jafa7/DocumentationEngine/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Jafa7/DocumentationEngine/compare/v0.1.2...v0.2.0

{documentation_engine-0.3.1 → documentation_engine-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documentation-engine
-Version: 0.3.1
+Version: 0.5.0
 Summary: Provider-neutral structured Markdown documentation engine.
 Project-URL: Repository, https://github.com/Jafa7/DocumentationEngine
 Project-URL: Documentation, https://github.com/Jafa7/DocumentationEngine/tree/main/docs
@@ -225,6 +225,7 @@ task rather than one mandatory process:
 | --- | --- | --- |
 | Core retrieval | Discover, read and inspect context/impact | Default for routine work |
 | Adoption | Connect or migrate an existing Markdown corpus | Setup and compatibility work |
+| Provider reconciliation | Export or compare explicitly pinned, body-free generations | External consumers that retain stable documentation evidence |
 | 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 |
@@ -342,6 +343,11 @@ docsystem migrate . --apply
 docsystem index . --write
 docsystem changes .
 docsystem changes . --json
+docsystem provider snapshot GENERATION . --json
+docsystem provider compare BEFORE AFTER . --json
+docsystem provider export snapshot GENERATION . --output snapshot.json
+docsystem provider export compare BEFORE AFTER . --output comparison.json
+docsystem provider artifact verify snapshot.json --json
 docsystem agent-instructions .
 docsystem agent-instructions . --json
 docsystem workspace list . --workspace /path/to/workspace
@@ -792,6 +798,18 @@ relations.
 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.
+Projects that expose immutable documentation evidence to another consumer may
+opt into `[provider]` identity and use `provider snapshot` or `provider compare`
+with explicit retained generation hashes. These commands never select the
+current pointer implicitly, never return Markdown bodies or absolute paths, and
+distinguish unavailable/corrupt provider state from a genuinely missing
+entity. See [pinned provider snapshots](docs/provider-snapshots.md) for the
+versioned JSON, relocation and bounded-pagination contract.
+For a durable process boundary, `provider export` assembles those pages into
+one complete immutable artifact and `provider artifact verify` checks it
+without project state. See
+[complete provider artifacts](docs/provider-artifacts.md). Artifact verification
+does not compare exported files or extend the configured retention window.
 `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,

{documentation_engine-0.3.1 → documentation_engine-0.5.0}/README.md

@@ -208,6 +208,7 @@ task rather than one mandatory process:
 | --- | --- | --- |
 | Core retrieval | Discover, read and inspect context/impact | Default for routine work |
 | Adoption | Connect or migrate an existing Markdown corpus | Setup and compatibility work |
+| Provider reconciliation | Export or compare explicitly pinned, body-free generations | External consumers that retain stable documentation evidence |
 | 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 |
@@ -325,6 +326,11 @@ docsystem migrate . --apply
 docsystem index . --write
 docsystem changes .
 docsystem changes . --json
+docsystem provider snapshot GENERATION . --json
+docsystem provider compare BEFORE AFTER . --json
+docsystem provider export snapshot GENERATION . --output snapshot.json
+docsystem provider export compare BEFORE AFTER . --output comparison.json
+docsystem provider artifact verify snapshot.json --json
 docsystem agent-instructions .
 docsystem agent-instructions . --json
 docsystem workspace list . --workspace /path/to/workspace
@@ -775,6 +781,18 @@ relations.
 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.
+Projects that expose immutable documentation evidence to another consumer may
+opt into `[provider]` identity and use `provider snapshot` or `provider compare`
+with explicit retained generation hashes. These commands never select the
+current pointer implicitly, never return Markdown bodies or absolute paths, and
+distinguish unavailable/corrupt provider state from a genuinely missing
+entity. See [pinned provider snapshots](docs/provider-snapshots.md) for the
+versioned JSON, relocation and bounded-pagination contract.
+For a durable process boundary, `provider export` assembles those pages into
+one complete immutable artifact and `provider artifact verify` checks it
+without project state. See
+[complete provider artifacts](docs/provider-artifacts.md). Artifact verification
+does not compare exported files or extend the configured retention window.
 `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,

{documentation_engine-0.3.1 → documentation_engine-0.5.0}/docs/README.md

@@ -31,6 +31,10 @@ link to that owner rather than repeat commands or policy.
   recommendation, prerequisites and exact source-contract scope.
 - [Compact context delivery](context-delivery.md) — lossless range
   deduplication, inclusion reasons and diagnostics drill-down.
+- [Pinned provider snapshots](provider-snapshots.md) — privacy-safe,
+  body-free export and comparison of explicit immutable generations.
+- [Complete provider artifacts](provider-artifacts.md) — transport-neutral,
+  self-verifying snapshot and comparison files for external consumers.
 - [Bounded workstream evidence](workstream-evidence.md) — versioned completion
   criteria, corrective lineage and fail-closed finish evidence.
 - [Deterministic idea intake](idea-intake.md) — place an agent-interpreted idea

{documentation_engine-0.3.1 → documentation_engine-0.5.0}/docs/agent-contract.md

@@ -594,6 +594,23 @@ context the delta deliberately left out. `--since` and
 every rejected combination fails closed with no packet, so an agent never acts
 on a partially applied request.
 
+When a separate consumer needs durable cross-process reconciliation rather
+than a task packet, use `provider snapshot` or `provider compare` with explicit
+retained generation hashes. Do not read `.docsystem/cache` directly and do not
+interpret provider unavailability, corruption or incomplete coverage as a
+missing document/section. Provider responses intentionally contain no Markdown
+bodies; fetch authored content through `read` or `context` only when the task
+requires it. The canonical contract is
+[pinned provider snapshots](provider-snapshots.md).
+
+When another process needs durable provider evidence, prefer
+`provider export snapshot` or `provider export compare` over implementing a
+cursor loop in the adopter. Run `provider artifact verify FILE --json` before
+import and bind the consumer record to the returned provider, generations and
+digest. Verification does not require project state and does not authorize
+comparison of exported files. See
+[complete provider artifacts](provider-artifacts.md).
+
 ## Report product issues without leaking adopter context
 
 When an agent finds a DocumentationEngine problem while working inside another

{documentation_engine-0.3.1 → documentation_engine-0.5.0}/docs/architecture.md

@@ -11,6 +11,7 @@ The core owns deterministic documentation retrieval mechanics:
 - inspectable context packets with explicit coverage and omissions;
 - impact and changed-section analysis;
 - versioned, sharded machine projections and diagnostics.
+- body-free export and comparison of explicitly pinned provider generations.
 
 The package also ships optional extensions over that same core:
 
@@ -58,6 +59,7 @@ The capability groups are progressive, not an execution checklist:
 | --- | --- | --- |
 | Core discovery and retrieval | `readiness`, `catalog`, `validate`, `read`, `context`, `dependencies`, `references`, `impact`, `change-plan` | Default path for understanding and changing documentation-backed work |
 | Adoption and derived state | `migration-report`, `migrate`, `profile-check`, `index`, `changes`, `report` | Connecting an existing corpus, checking policy or refreshing disposable projections |
+| Provider reconciliation | `provider snapshot`, `provider compare`, `provider export`, `provider artifact verify` | An external consumer needs exact body-free observations or one complete transport artifact from pinned generations |
 | Governed delivery | `roadmap`, `intake`, `admission`, `execution-handoff`, `execution-result`, `workstream`, `lifecycle`, `finish`, `promotion` | Genuinely multi-stage, delegated or risk-bearing work that requires bounded evidence |
 | Bounded mutation | `maintenance`, `maintenance-recover` | Explicitly approved mechanical synchronization with journal and recovery guarantees |
 | Multi-source operation | `workspace`, `federation` | A task that deliberately spans independently owned documentation sources |
@@ -94,6 +96,7 @@ Project policy may configure:
 - review policy;
 - graph-health advisory thresholds and required metadata fields;
 - projection retention;
+- stable provider identity and exported visibility classification;
 - legacy path-relation migration and historical snapshot document types;
 - provider adapters.
 
@@ -179,6 +182,29 @@ direct Markdown with a visible diagnostic rather than serving mixed state.
 Coordinating multiple writers is a caller/orchestrator responsibility, not
 core engine behavior.
 
+Provider reconciliation uses the same immutable generations but a different
+verification mode from live reads. A provider generation binds stable provider
+identity, visibility, supported capabilities, catalog completeness, coverage,
+scope and body-free export boundaries into the manifest root. `provider
+snapshot` and `provider compare` fully verify explicitly selected retained
+generations without comparing them with live Markdown or using `current.json`;
+historical drift is the evidence being requested. The provider model exposes
+only IDs, canonical anchors, hashes, root-relative paths and line hints. Its
+schema, deterministic cursor and byte/page bounds are independent from the
+internal projection schema. See [pinned provider snapshots](provider-snapshots.md).
+Portable comparison of complete exported snapshot artifacts is deliberately
+deferred. Losing a retained operand requires an explicit full rebaseline; it
+does not authorize heuristic reconstruction or an entity-absence conclusion.
+
+The `traceability-provider-v1` boundary adds complete snapshot and comparison
+artifacts without exposing pagination mechanics to adopters. Export walks and
+validates bounded pages internally, seals the complete ordered result with a
+deterministic digest and writes it atomically. Standalone artifact verification
+needs no project configuration or cache. It validates transport evidence only;
+consumer-owned semantic relations, reconciliation and impact remain outside
+Documentation Engine. See
+[complete provider artifacts](provider-artifacts.md).
+
 Retained generation manifests also drive two token-economy `context` modes
 that omit content only when omission is provably safe, never as a silent
 budget cut. `--assume-known ID@REV` is a client-declared cache: an agent

{documentation_engine-0.3.1 → documentation_engine-0.5.0}/docs/client-integration.md

@@ -35,14 +35,17 @@ adoption-oriented, read-only commands:
 - `docsystem catalog PROJECT --explain --json`
 - `docsystem changes PROJECT --json`
 - `docsystem context DOCUMENT_ID PROJECT --json`
+- `docsystem provider snapshot GENERATION PROJECT --json`
+- `docsystem provider compare BEFORE AFTER PROJECT --json`
+- `docsystem provider artifact verify FILE --json`
 
-Each prints one deterministic JSON object to stdout (sorted keys, stable
-field names) carrying the same diagnostics that the text form prints as
-human `ERROR`/`WARNING` lines on stderr. In `--json` mode those human
-stderr diagnostics may be suppressed since the JSON payload already carries
-the same information in structured form, so a wrapper does not need to read
-stderr to make a decision. Exit codes are unchanged by `--json`: `0` on
-success or a ready project, `1` otherwise.
+Each successful command prints one deterministic JSON object to stdout (sorted
+keys and stable field names). For the adoption/context commands, structured
+diagnostics may replace duplicate human `ERROR`/`WARNING` lines. Provider
+snapshot/compare instead fail closed with a stable error code on stderr and no
+stdout, because an unavailable generation must never resemble an entity result.
+Exit codes are unchanged by `--json`: `0` on success or a ready project, `1`
+otherwise.
 
 Every `--json` root is an object with a `"schema_version": 1` field; it is
 bumped only on a breaking change to an existing field, while new fields may
@@ -101,9 +104,23 @@ hash before comparison. `--since` and
 `--assume-known` are mutually exclusive, and neither combines with
 `--outline`; a rejected combination exits `1` with no stdout.
 
-A wrapper that speaks MCP can skip the CLI entirely and use
-[the MCP adapter](mcp-adapter.md), which exposes these same read-only
-commands as typed tools over the identical JSON contract.
+A wrapper that speaks MCP can use [the MCP adapter](mcp-adapter.md) for its
+document, context, graph and governance tools over the same core contracts.
+
+Provider snapshot/compare responses use their own versioned, body-free schema
+and bounded cursor contract. They require explicit retained generations and
+never infer either operand from current Markdown or `current.json`. These two
+commands are currently CLI-only. A wrapper must distinguish
+provider/generation failures on stderr from `missing` inside a successful
+comparison; see [pinned provider snapshots](provider-snapshots.md).
+
+Do not reproduce provider pagination in an adopter when the integration needs
+one durable import unit. Use `provider export snapshot` or
+`provider export compare`; Documentation Engine assembles all pages and writes
+a complete digest-bound artifact. The standalone verifier is the compatibility
+gate, so a consumer checks protocol/schema/capability rather than tracking
+package minor versions. See
+[complete provider artifacts](provider-artifacts.md).
 
 `docsystem readiness PROJECT --json` is the entry point for an adoption
 sequence: its `next_command` field names the single safe next command for

{documentation_engine-0.3.1 → documentation_engine-0.5.0}/docs/mcp-adapter.md

@@ -60,6 +60,12 @@ The adapter is deliberately a wrapper, not a second implementation:
   `maintenance-recover`) intentionally have no tools and stay
   with the human or calling system, matching
   [the agent contract](agent-contract.md);
+- pinned `provider snapshot` and `provider compare` are currently CLI-only.
+  An MCP wrapper may be added later only as a thin transport over the same
+  bounded, body-free contract; clients must not inspect projection files;
+- complete `provider export` and standalone `provider artifact verify` are also
+  CLI-only. They form the transport-neutral file boundary for consumers that
+  should not own provider pagination mechanics;
 - a non-zero CLI exit becomes a tool error carrying the CLI's stderr
   diagnostics, so a client never mistakes a failure for data. The one
   exception is `readiness`, whose "not ready" state is a legitimate answer:

documentation_engine-0.5.0/docs/provider-artifacts.md

@@ -0,0 +1,133 @@
+# Complete provider artifacts
+
+Complete provider artifacts are the transport-neutral boundary between
+Documentation Engine and an external traceability consumer. They remove the
+need for an adopter to invoke paged commands repeatedly, validate cursors or
+understand projection files. Documentation Engine owns that mechanical work;
+the consumer receives one complete, body-free JSON artifact.
+
+The capability name is `traceability-provider-v1`. It is generic: the
+artifact describes documentation entities and changes only. Product logic,
+code/test relations, reconciliation policy, attention queues and impact
+semantics remain consumer responsibilities.
+
+## Export complete evidence
+
+Build and retain the required projection generations first, then export them
+explicitly:
+
+```bash
+docsystem provider export snapshot GENERATION PROJECT \
+  --output snapshot.json
+
+docsystem provider export compare BEFORE AFTER PROJECT \
+  --output comparison.json
+```
+
+Both commands fully verify the selected retained generation or generations,
+walk the existing bounded provider pages internally and require the pages to
+reconstruct one complete ordered result. The output is written through a
+temporary file and atomically selected only after assembly and self-
+verification. An existing output path is never replaced.
+
+Export remains subject to provider retention. An evicted generation fails as
+unknown or unavailable and requires an explicit rebaseline. The command never
+reconstructs an operand from current Markdown and never interprets provider
+unavailability as entity absence.
+
+## Verify without project state
+
+Any process with the artifact file can validate its integrity and supported
+contract without a Documentation Engine project, provider cache or Python API:
+
+```bash
+docsystem provider artifact verify snapshot.json --json
+docsystem provider artifact verify comparison.json --json
+```
+
+A valid artifact returns deterministic JSON with `valid: true`, its kind,
+provider ID, pinned generation IDs, digest and item counts. Failure exits `1`,
+writes no stdout and emits a stable code on stderr.
+
+Important failure classes include:
+
+- `artifact-corrupt`: malformed content, invalid entity evidence or digest
+  mismatch;
+- `artifact-incomplete`: missing observations, changes, coverage or count
+  evidence;
+- `artifact-mixed-provider`: inconsistent provider identities;
+- `artifact-mixed-query`: incompatible scopes inside one comparison;
+- `artifact-schema-unsupported`: unsupported artifact schema;
+- `artifact-incompatible`: unsupported protocol, capability, kind or assembly
+  policy;
+- `artifact-output-exists`: export refused to replace existing evidence;
+- `artifact-write-failed`: the destination filesystem could not provide the
+  required atomic create operation.
+
+The SHA-256 digest detects accidental or unauthorized content changes when the
+expected digest is retained separately. It is not a digital signature and
+does not establish who created the artifact. Transport authentication and
+artifact provenance remain deployment responsibilities.
+
+## Artifact contract
+
+Every artifact contains:
+
+- `schema_version`: version of the JSON artifact layout;
+- `artifact_kind`: snapshot or comparison artifact;
+- `protocol`: `traceability-provider`, version `1`, with capability
+  `traceability-provider-v1`;
+- `provider`: stable provider ID, provider contract version, visibility and
+  generation-advertised capabilities;
+- `query`: exact pinned generation and scope identity;
+- `completeness`: `complete: true`, coverage, boundaries and exact counts;
+- `policy`: bounded-page assembly, complete-or-fail behavior, ordering and
+  body-omission policy;
+- complete ordered `observations` or `changes`;
+- `content_digest`: SHA-256 over canonical content excluding the digest field.
+
+Snapshot observations contain stable kind/document/anchor identity, content
+hash, provider-relative POSIX path, inclusive line hints, anchor kind and
+visibility. Comparison changes contain `relocated`, `changed`, `missing` or
+`added` plus exact before/after observations. Markdown bodies, headings,
+metadata values, relations, absolute paths and projection locations are never
+included.
+
+The entity identity and change semantics are identical to the paged
+[pinned provider contract](provider-snapshots.md). A consumer should store the
+complete artifact as immutable evidence and import only fields it understands.
+
+## Compatibility policy
+
+Consumers must negotiate the artifact, not the installed package release:
+
+1. Require protocol name `traceability-provider` and version `1`.
+2. Require capability `traceability-provider-v1`.
+3. Require a supported artifact `schema_version` and `artifact_kind`.
+4. Run `provider artifact verify` before import.
+5. Bind imported state to `provider.id`, exact generation IDs, query scope and
+   `content_digest`.
+
+Within protocol version 1, Documentation Engine may add optional fields or
+additional capabilities. Consumers must ignore unknown optional fields while
+continuing to validate the required v1 fields. Existing field meanings,
+identity rules, classifications and completeness semantics do not change
+within v1. A breaking change requires a new protocol/schema version or a new
+capability, so an adopter does not need to track Documentation Engine patch or
+minor releases merely to decide whether an artifact is importable.
+
+The paged `provider snapshot` and `provider compare` commands remain supported
+for streaming clients. New adopters that need a durable process boundary
+should prefer complete artifacts and should not read `.docsystem/cache`, shard
+files or internal Python modules.
+
+## Deliberate boundary
+
+Artifact verification does not enable Documentation Engine to compare two
+previously exported files. `provider export compare` still selects two retained
+provider generations and exports their verified comparison. Portable
+comparison after provider retention expiry remains a separate future
+capability; consumers must not infer it from `traceability-provider-v1`.
+
+See [`examples/provider-snapshots/`](../examples/provider-snapshots/) for a
+public synthetic provider fixture suitable for black-box integration tests.

documentation_engine-0.5.0/docs/provider-snapshots.md

@@ -0,0 +1,180 @@
+# Pinned provider snapshots
+
+Pinned provider snapshots let an external consumer reconcile two exact states
+of a Documentation Engine catalog without importing package internals or
+reading `.docsystem/cache` directly. The surface is read-only, body-free and
+provider-neutral.
+
+This contract answers a different question from `docsystem changes`:
+
+- `changes` compares live Markdown with the generation selected by
+  `current.json`;
+- `provider snapshot` exports observations from one explicitly named immutable
+  generation;
+- `provider compare` compares two explicitly named immutable generations and
+  does not substitute the current pointer for either operand.
+
+## Opt-in provider identity
+
+Configure a stable identity before building generations intended for external
+reconciliation:
+
+```toml
+[provider]
+id = "example-docs"
+visibility = "private"
+
+[projection]
+format = "sharded-json"
+keep_generations = 4
+```
+
+`provider.id` accepts 1–128 lowercase letters, digits, `.`, `_` and `-`.
+`visibility` is `private` by default and may be set to `public`; it is an
+exported classification, not an access-control mechanism. Filesystem,
+sandbox, service and transport policy still control who can invoke the CLI.
+
+Provider configuration is optional for all existing commands. The provider
+commands fail closed with `provider-not-configured` when the ID is absent.
+Never derive the ID from an absolute path, host name or repository remote.
+
+Run `docsystem index PROJECT --write` after configuring the provider. Each new
+projection generation binds the provider ID, visibility, capabilities,
+catalog-completeness evidence, coverage and fixed export boundaries into its
+content hash. Generations created by older projection schemas do not acquire
+those claims retroactively and are reported as `generation-unsupported`.
+
+## Export one pinned generation
+
+```bash
+docsystem provider snapshot GENERATION PROJECT --json
+docsystem provider snapshot GENERATION PROJECT --json \
+  --page-size 100 --cursor CURSOR
+```
+
+`GENERATION` is a full retained generation hash or an unambiguous prefix of at
+least twelve characters. It is required; the command never selects
+`current.json` implicitly.
+
+The versioned response identifies the provider and generation, advertises
+capabilities, states coverage/scope/boundaries, and returns a page of stable
+document and section observations. Each observation contains only:
+
+- `document_id` and canonical `anchor` (`null` for a document);
+- `anchor_kind` (`explicit` or `generated`) for a section;
+- exact content hash;
+- documentation-root-relative POSIX path;
+- one-based inclusive line hints;
+- configured visibility.
+
+Markdown bodies, titles, metadata values, relations, excluded paths, absolute
+paths and projection locations are not exported. Explicit anchors provide the
+strongest stable section identity. A generated anchor remains canonical for
+that generation, but changing its heading may produce a missing/added pair
+rather than an inferred match; the engine does not use title similarity.
+
+## Compare two pinned generations
+
+```bash
+docsystem provider compare BEFORE AFTER PROJECT --json
+docsystem provider compare BEFORE AFTER PROJECT --json \
+  --page-size 100 --cursor CURSOR
+```
+
+Both operands are verified independently and may be retained historical
+generations. They do not need to match live Markdown or the current pointer.
+They must belong to the configured provider and advertise the same supported
+capability.
+
+The comparison uses the exact key `(kind, document_id, canonical_anchor)`:
+
+| Classification | Meaning |
+| --- | --- |
+| `relocated` | Identity and content hash are unchanged, but path or line hints changed |
+| `changed` | Identity exists on both sides and its content hash changed |
+| `missing` | Identity exists only in `BEFORE` |
+| `added` | Identity exists only in `AFTER` |
+
+Every change carries the exact body-free `before` and `after` observation when
+that side exists. A content change takes precedence over relocation, while the
+two observations still expose any simultaneous location change. The summary
+also counts unchanged entities. Valid Documentation Engine catalogs prevent
+duplicate stable keys; ambiguity is never used to disguise corruption or an
+incomplete catalog.
+
+## Integrity and availability
+
+Pinned export verifies the selector, projection schema, manifest-to-generation
+hash, provider capability descriptor, completeness evidence, document coverage
+and every stored document/reverse/reference shard hash. It deliberately does
+not compare historical source hashes with live Markdown: a retained generation
+is immutable historical evidence and is expected to differ from current files.
+
+Failures return exit code `1`, write no stdout, and use a stable code in stderr,
+for example `ERROR [generation-corrupt]: ...`. Important distinctions include:
+
+- `provider-unavailable`: generation storage cannot be read;
+- `generation-unknown`: the requested retained generation does not exist;
+- `generation-selector-ambiguous`: a prefix selects more than one generation;
+- `generation-corrupt`: bound manifest or shard evidence is invalid;
+- `generation-unsupported`: the generation lacks this versioned capability;
+- `generation-incomplete`: catalog or coverage completeness cannot be proved;
+- `provider-mismatch`: generation identity differs from configured identity;
+- `page-invalid` / `page-too-large`: pagination evidence is invalid or cannot
+  fit the bounded response.
+
+Provider unavailability and corrupt/incomplete snapshots are never represented
+as missing entities.
+
+## Pagination and deterministic bytes
+
+Pages default to 100 entities, accept 1–500, and never exceed 262,144 UTF-8
+bytes. The response may return fewer than the requested count to respect the
+byte limit. If one observation cannot fit, the command fails instead of
+truncating a field. `next_cursor` is bound to the response kind and exact
+generation operand(s); using it for another query fails closed.
+
+Following `next_cursor` until `null` reconstructs the complete ordered result
+without loss or duplication. Repeating the same pinned request produces the
+same sorted JSON bytes with one trailing newline.
+
+Retention controls availability. Set `projection.keep_generations` high enough
+for the consumer's reconciliation window, or archive the body-free exported
+responses in the consumer. If either comparison generation has been evicted,
+the provider fails with `generation-unknown`/unavailable. The consumer must
+perform an explicit full rebaseline from a newly selected complete generation
+and record that the earlier delta chain ended. Retention loss is never evidence
+that an entity was removed, and the engine does not reconstruct the missing
+operand heuristically.
+
+## Deferred follow-up: portable snapshot artifacts
+
+Portable comparison after provider retention expiry is a named follow-up, not
+part of the first contract. A future command may accept complete exported
+snapshot artifacts as operands, but must bind and verify their schema, provider
+and generation identity, query/scope, coverage/completeness, complete ordered
+observations and canonical artifact digest before applying the same comparison
+semantics. It must reject partial page sets, mixed-query pages, tampering,
+unsupported schemas and incompatible providers. Persisted pages from this
+version are evidence for a consumer; they are not yet accepted back as
+Documentation Engine comparison operands.
+
+For v1, entity identity is exactly `(kind, document_id, canonical_anchor)`.
+Moving the same document ID to another provider-relative path can be
+`relocated`. Moving a section across document IDs is `missing` plus `added`,
+even when its anchor and content match; cross-document similarity is not safe
+structural identity and is not inferred.
+
+The first contract is CLI-only. A service or MCP adapter may wrap these exact
+read-only commands later, but it must preserve their integrity, privacy,
+pagination and failure semantics rather than inspect projection files itself.
+
+Adopters that need one durable process-boundary file instead of paged wire
+responses should use [complete provider artifacts](provider-artifacts.md).
+Documentation Engine assembles and verifies all pages internally while keeping
+these paged commands backward compatible.
+
+[`examples/provider-snapshots/`](../examples/provider-snapshots/) is a public
+synthetic corpus with explicit anchors and an opt-in provider profile. Copy it
+to a temporary directory, run `index --write`, make one source change and write
+a second generation to exercise the commands without exposing adopter data.

{documentation_engine-0.3.1 → documentation_engine-0.5.0}/docs/setup-guide.md

@@ -177,6 +177,14 @@ format = "sharded-json"
 keep_generations = 2
 ```
 
+Projects that expose immutable body-free observations to another consumer may
+also configure an explicit `[provider]` identity. This is optional for ordinary
+local use; see [pinned provider snapshots](provider-snapshots.md). Do not infer
+the identity from a private filesystem path.
+External processes that need one durable import unit should use
+[complete provider artifacts](provider-artifacts.md) instead of reproducing the
+paged provider protocol.
+
 Whole-graph smell policy is optional and should reflect the adopting project,
 not copied thresholds. With no thresholds, `graph-health` still reports the
 complete deterministic inventory and emits only intrinsic dead-link evidence: