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

{documentation_engine-0.4.0 → 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.4.0 → documentation_engine-0.5.0}/CHANGELOG.md

@@ -4,6 +4,24 @@ 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
@@ -219,7 +237,8 @@ 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.4.0...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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documentation-engine
-Version: 0.4.0
+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
@@ -345,6 +345,9 @@ 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
@@ -802,6 +805,11 @@ 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.4.0 → documentation_engine-0.5.0}/README.md

@@ -328,6 +328,9 @@ 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
@@ -785,6 +788,11 @@ 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.4.0 → documentation_engine-0.5.0}/docs/README.md

@@ -33,6 +33,8 @@ link to that owner rather than repeat commands or policy.
   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.4.0 → documentation_engine-0.5.0}/docs/agent-contract.md

@@ -603,6 +603,14 @@ 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.4.0 → documentation_engine-0.5.0}/docs/architecture.md

@@ -59,7 +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` | An external consumer needs exact body-free observations from one or two pinned generations |
+| 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 |
@@ -196,6 +196,15 @@ 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.4.0 → documentation_engine-0.5.0}/docs/client-integration.md

@@ -37,6 +37,7 @@ adoption-oriented, read-only commands:
 - `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 successful command prints one deterministic JSON object to stdout (sorted
 keys and stable field names). For the adoption/context commands, structured
@@ -113,6 +114,14 @@ 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
 the project's current state (`init`, `doctor`, `migrate`, `index --write`, or

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

@@ -63,6 +63,9 @@ The adapter is deliberately a wrapper, not a second implementation:
 - 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.4.0 → documentation_engine-0.5.0}/docs/provider-snapshots.md

@@ -169,6 +169,11 @@ 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

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

@@ -181,6 +181,9 @@ 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

{documentation_engine-0.4.0 → documentation_engine-0.5.0}/scripts/installed_cli_smoke.sh

@@ -163,18 +163,42 @@ MARKDOWN
     env -u PYTHONPATH -u PYTHONHOME "${docsystem_bin}" provider compare \
       "${first_generation}" "${second_generation}" . --json \
       > provider-compare.json
+    env -u PYTHONPATH -u PYTHONHOME "${docsystem_bin}" provider export snapshot \
+      "${first_generation}" . --output provider-snapshot-artifact.json
+    env -u PYTHONPATH -u PYTHONHOME "${docsystem_bin}" provider export compare \
+      "${first_generation}" "${second_generation}" . \
+      --output provider-compare-artifact.json
+    (
+      cd "${work_dir}"
+      env -u PYTHONPATH -u PYTHONHOME "${docsystem_bin}" provider artifact verify \
+        "${project_dir}/provider-snapshot-artifact.json" --json \
+        > "${project_dir}/provider-snapshot-verification.json"
+      env -u PYTHONPATH -u PYTHONHOME "${docsystem_bin}" provider artifact verify \
+        "${project_dir}/provider-compare-artifact.json" --json \
+        > "${project_dir}/provider-compare-verification.json"
+    )
     env -u PYTHONPATH -u PYTHONHOME "${venv_python}" - <<'PY'
 import json
 from pathlib import Path
 
 snapshot_text = Path("provider-snapshot.json").read_text(encoding="utf-8")
 comparison = json.loads(Path("provider-compare.json").read_text(encoding="utf-8"))
+snapshot_artifact_text = Path("provider-snapshot-artifact.json").read_text(encoding="utf-8")
+compare_artifact_text = Path("provider-compare-artifact.json").read_text(encoding="utf-8")
 snapshot = json.loads(snapshot_text)
 assert snapshot["kind"] == "provider-snapshot"
 assert snapshot["snapshot"]["provider_id"] == "installed-smoke"
 assert "Original private-like fixture text" not in snapshot_text
 assert comparison["kind"] == "provider-compare"
 assert comparison["summary"]["changed"] >= 1
+assert "Original private-like fixture text" not in snapshot_artifact_text
+assert "Original private-like fixture text" not in compare_artifact_text
+for name in ("snapshot", "compare"):
+    verification = json.loads(
+        Path(f"provider-{name}-verification.json").read_text(encoding="utf-8")
+    )
+    assert verification["kind"] == "provider-artifact-verification"
+    assert verification["valid"] is True
 PY
   )
 }

{documentation_engine-0.4.0 → documentation_engine-0.5.0}/src/docsystem/__init__.py

@@ -9,7 +9,7 @@ from docsystem.catalog import (
 from docsystem.metadata import DocumentMetadata, MetadataReference
 from docsystem.sections import MarkdownSection
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "CatalogMembership",

{documentation_engine-0.4.0 → documentation_engine-0.5.0}/src/docsystem/cli.py

@@ -196,6 +196,14 @@ from docsystem.provider import (
     encode_response,
     snapshot_response,
 )
+from docsystem.provider_artifact import (
+    ProviderArtifactError,
+    compare_artifact,
+    encode_artifact,
+    load_and_verify_artifact,
+    snapshot_artifact,
+    write_artifact,
+)
 from docsystem.readiness import evaluate_readiness
 from docsystem.sections import MarkdownSection, extract_navigation, extract_section
 from docsystem.shared_finish import SharedFinishError, load_shared_finish_record
@@ -4376,7 +4384,9 @@ def changes(project_root: Path, *, json_output: bool = False) -> int:
         return 1
 
 
-def _provider_error(error: PinnedGenerationError | ProviderContractError) -> int:
+def _provider_error(
+    error: PinnedGenerationError | ProviderContractError | ProviderArtifactError,
+) -> int:
     print(f"ERROR [{error.code}]: {error}", file=sys.stderr)
     return 1
 
@@ -4450,6 +4460,73 @@ def provider_compare(
         return 1
 
 
+def provider_export_snapshot(
+    project_root: Path, generation: str, *, output: Path
+) -> int:
+    """Write one complete immutable snapshot artifact from a pinned generation."""
+
+    try:
+        config = load_config(project_root)
+        if config.provider_id is None:
+            raise ProviderContractError(
+                "provider-not-configured",
+                "provider.id is required for provider artifact export",
+            )
+        snapshot = load_pinned_projection(config, generation)
+        write_artifact(output, snapshot_artifact(snapshot))
+        print(f"Provider snapshot artifact written: {output}")
+        return 0
+    except (OSError, ValueError) as error:
+        if isinstance(
+            error,
+            (PinnedGenerationError, ProviderContractError, ProviderArtifactError),
+        ):
+            return _provider_error(error)
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+
+
+def provider_export_compare(
+    project_root: Path,
+    before_generation: str,
+    after_generation: str,
+    *,
+    output: Path,
+) -> int:
+    """Write one complete immutable comparison artifact from pinned generations."""
+
+    try:
+        config = load_config(project_root)
+        if config.provider_id is None:
+            raise ProviderContractError(
+                "provider-not-configured",
+                "provider.id is required for provider artifact export",
+            )
+        before = load_pinned_projection(config, before_generation)
+        after = load_pinned_projection(config, after_generation)
+        write_artifact(output, compare_artifact(before, after))
+        print(f"Provider compare artifact written: {output}")
+        return 0
+    except (OSError, ValueError) as error:
+        if isinstance(
+            error,
+            (PinnedGenerationError, ProviderContractError, ProviderArtifactError),
+        ):
+            return _provider_error(error)
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+
+
+def provider_artifact_verify(path: Path) -> int:
+    """Verify one complete artifact without loading project or provider state."""
+
+    try:
+        sys.stdout.write(encode_artifact(load_and_verify_artifact(path)))
+        return 0
+    except ProviderArtifactError as error:
+        return _provider_error(error)
+
+
 def _validation_summary(issues: tuple[ValidationIssue, ...]) -> dict[str, int]:
     summary = {
         "errors": 0,
@@ -8773,6 +8850,52 @@ def build_parser() -> argparse.ArgumentParser:
     )
     add_provider_page(provider_compare_parser)
 
+    provider_export_parser = provider_subparsers.add_parser(
+        "export", help="Assemble one complete immutable provider artifact."
+    )
+    provider_export_subparsers = provider_export_parser.add_subparsers(
+        dest="provider_export_command", required=True
+    )
+    provider_export_snapshot_parser = provider_export_subparsers.add_parser(
+        "snapshot", help="Export one complete pinned snapshot artifact."
+    )
+    provider_export_snapshot_parser.add_argument("generation")
+    provider_export_snapshot_parser.add_argument(
+        "project", nargs="?", type=Path, default=Path.cwd()
+    )
+    provider_export_snapshot_parser.add_argument(
+        "--output", required=True, type=Path, metavar="FILE"
+    )
+    provider_export_compare_parser = provider_export_subparsers.add_parser(
+        "compare", help="Export one complete pinned comparison artifact."
+    )
+    provider_export_compare_parser.add_argument("before_generation")
+    provider_export_compare_parser.add_argument("after_generation")
+    provider_export_compare_parser.add_argument(
+        "project", nargs="?", type=Path, default=Path.cwd()
+    )
+    provider_export_compare_parser.add_argument(
+        "--output", required=True, type=Path, metavar="FILE"
+    )
+
+    provider_artifact_parser = provider_subparsers.add_parser(
+        "artifact", help="Inspect a transport-neutral provider artifact."
+    )
+    provider_artifact_subparsers = provider_artifact_parser.add_subparsers(
+        dest="provider_artifact_command", required=True
+    )
+    provider_artifact_verify_parser = provider_artifact_subparsers.add_parser(
+        "verify", help="Verify artifact integrity and compatibility."
+    )
+    provider_artifact_verify_parser.add_argument("file", type=Path)
+    provider_artifact_verify_parser.add_argument(
+        "--json",
+        action="store_true",
+        required=True,
+        dest="json_output",
+        help="Print a deterministic verification result.",
+    )
+
     finish_parser = subparsers.add_parser(
         "finish",
         help="Build a compact handoff packet for returning work to a parent context.",
@@ -9054,6 +9177,8 @@ def build_parser() -> argparse.ArgumentParser:
         changes_parser,
         provider_snapshot_parser,
         provider_compare_parser,
+        provider_export_snapshot_parser,
+        provider_export_compare_parser,
         finish_parser,
         agent_instructions_parser,
     ):
@@ -9147,6 +9272,13 @@ def main() -> int:
             f"unknown federation command: {args.federation_command}"
         )
 
+    if args.command == "provider" and args.provider_command == "artifact":
+        if args.provider_artifact_command == "verify":
+            return provider_artifact_verify(args.file)
+        raise AssertionError(
+            f"unknown provider artifact command: {args.provider_artifact_command}"
+        )
+
     selection = _resolve_selection(args)
     if selection is None:
         return 1
@@ -9337,6 +9469,21 @@ def main() -> int:
                 cursor=args.cursor,
                 page_size=args.page_size,
             )
+        if args.provider_command == "export":
+            if args.provider_export_command == "snapshot":
+                return provider_export_snapshot(
+                    project, args.generation, output=args.output
+                )
+            if args.provider_export_command == "compare":
+                return provider_export_compare(
+                    project,
+                    args.before_generation,
+                    args.after_generation,
+                    output=args.output,
+                )
+            raise AssertionError(
+                f"unknown provider export command: {args.provider_export_command}"
+            )
         raise AssertionError(f"unknown provider command: {args.provider_command}")
     if args.command == "finish":
         return finish(