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

documentation_engine-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,142 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  TMPDIR: /tmp
+  TMP: /tmp
+  TEMP: /tmp
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Run pytest
+        run: uv run pytest
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+      - name: Verify lockfile is current
+        run: uv lock --check
+
+      - name: Installed CLI smoke test
+        run: ./scripts/installed_cli_smoke.sh
+
+      # The smoke test builds and installs a wheel only. The release workflow
+      # uploads a wheel *and* an sdist, and an index rejects a distribution
+      # whose metadata or long description does not render. Check both
+      # artifacts here rather than during an irreversible upload.
+      - name: Build and check both distributions
+        run: |
+          dist_dir="$(mktemp -d)/dist"
+          uv build --out-dir "$dist_dir"
+          version="$(uv run python -c 'import docsystem; print(docsystem.__version__)')"
+          test -f "$dist_dir/documentation_engine-${version}-py3-none-any.whl"
+          test -f "$dist_dir/documentation_engine-${version}.tar.gz"
+          uvx --from 'twine>=6,<7' twine check --strict "$dist_dir"/*
+
+      # Dogfooding: walk the documented adoption sequence end-to-end against
+      # the public example profile, on a scratch copy so the fixture stays
+      # byte-identical in the repository.
+      - name: Example profile adoption walkthrough
+        run: |
+          profile="$(mktemp -d)/profile"
+          cp -r examples/generic-adopter "$profile"
+          uv run python -m docsystem readiness "$profile" --json
+          uv run python -m docsystem migrate "$profile" --apply
+          uv run python -m docsystem index "$profile" --write
+          uv run python -m docsystem readiness "$profile" --json
+          uv run python -m docsystem context DOC-002 "$profile" --depth 1
+          uv run python -m docsystem context DOC-002 "$profile" --depth 1 --json
+          uv run python -m docsystem changes "$profile" --json
+
+  windows:
+    runs-on: windows-latest
+    env:
+      PYTHONUTF8: "0"
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Run Windows CLI tests without Python UTF-8 mode
+        shell: pwsh
+        run: |
+          $env:TMPDIR = $env:RUNNER_TEMP
+          $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
+
+      - name: Installed CLI UTF-8 PowerShell smoke
+        shell: pwsh
+        run: |
+          $env:TMPDIR = $env:RUNNER_TEMP
+          $env:TMP = $env:RUNNER_TEMP
+          $env:TEMP = $env:RUNNER_TEMP
+          Remove-Item Env:PYTHONIOENCODING -ErrorAction SilentlyContinue
+          $dist = Join-Path $env:RUNNER_TEMP "docsystem-dist"
+          $venv = Join-Path $env:RUNNER_TEMP "docsystem-venv"
+          $project = Join-Path $env:RUNNER_TEMP "docsystem-unicode-project"
+          $output = Join-Path $env:RUNNER_TEMP "context.json"
+          $errors = Join-Path $env:RUNNER_TEMP "diagnostics.txt"
+
+          uv build --wheel --out-dir $dist
+          $wheel = Get-ChildItem $dist -Filter "documentation_engine-*.whl" -File
+          if ($wheel.Count -ne 1) { throw "expected exactly one wheel" }
+          uv venv $venv --python 3.12
+          $python = Join-Path $venv "Scripts/python.exe"
+          $docsystem = Join-Path $venv "Scripts/docsystem.exe"
+          uv pip install --python $python $wheel.FullName
+
+          $expectedVersion = (& $python -c "import docsystem; print(docsystem.__version__)").Trim()
+          $reportedVersion = (& $docsystem --version).Trim()
+          if ($reportedVersion -ne "docsystem $expectedVersion") {
+            throw "unexpected version output: $reportedVersion"
+          }
+
+          & $docsystem init $project
+          $architecture = Join-Path $project "plan/architecture"
+          New-Item -ItemType Directory -Path $architecture -Force | Out-Null
+          @"
+          ---
+          id: DOC-001
+          revision: 1
+          ---
+          # Привет
+          ## Резюме
+          Исходный текст остаётся доступен полностью.
+          "@ | Set-Content -Encoding utf8 (Join-Path $architecture "README.md")
+
+          & $docsystem context DOC-001 $project --json |
+            Set-Content -Encoding utf8 $output
+          if ($LASTEXITCODE -ne 0) { throw "context failed with $LASTEXITCODE" }
+          $payload = Get-Content -Raw -Encoding utf8 $output | ConvertFrom-Json
+          if ($payload.documents[0].navigation -notmatch "Привет") {
+            throw "context JSON lost Cyrillic source text"
+          }
+
+          & $docsystem read DOC-001 $project --anchor "отсутствует" 2> $errors
+          if ($LASTEXITCODE -ne 1) { throw "unknown anchor returned $LASTEXITCODE" }
+          $global:LASTEXITCODE = 0
+          $diagnostic = Get-Content -Raw -Encoding utf8 $errors
+          if ($diagnostic -notmatch "отсутствует") {
+            throw "stderr diagnostic was not UTF-8"
+          }

{documentation_engine-0.3.0 → documentation_engine-0.4.0}/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to Documentation Engine are documented in this file.
 
 ## [Unreleased]
 
+## [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
+
+- CLI stdout and stderr now use UTF-8 independently of the host locale, so
+  redirected or piped Cyrillic and other Unicode Markdown works on Windows
+  without requiring `PYTHONUTF8=1`.
+- Windows CI now runs focused CLI/context/MCP regressions with Python UTF-8
+  mode disabled and verifies an installed wheel through a PowerShell JSON pipe
+  and a Unicode stderr diagnostic.
+
+### Added
+
+- `docsystem --version` reports the installed Documentation Engine version
+  without requiring a project or subcommand.
+
 ## [0.3.0] - 2026-07-15
 
 ### Highlights
@@ -181,7 +219,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.0...HEAD
+[Unreleased]: https://github.com/Jafa7/DocumentationEngine/compare/v0.4.0...HEAD
+[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
 [0.1.2]: https://github.com/Jafa7/DocumentationEngine/compare/v0.1.1...v0.1.2

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documentation-engine
-Version: 0.3.0
+Version: 0.4.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
@@ -130,12 +130,14 @@ unrelated globally installed `docsystem` executable.
 For a published-package installation:
 
 ```bash
+docsystem --version
 docsystem --help
 ```
 
 For a contributor checkout:
 
 ```bash
+uv run python -m docsystem --version
 uv run python -m docsystem --help
 ```
 
@@ -159,7 +161,8 @@ disposable projection. It does not require MCP.
 [docs/setup-guide.md](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 local backup path or commit private planning paths.
+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:
@@ -168,6 +171,11 @@ 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.
 ```
@@ -217,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 |
@@ -334,6 +343,8 @@ docsystem migrate . --apply
 docsystem index . --write
 docsystem changes .
 docsystem changes . --json
+docsystem provider snapshot GENERATION . --json
+docsystem provider compare BEFORE AFTER . --json
 docsystem agent-instructions .
 docsystem agent-instructions . --json
 docsystem workspace list . --workspace /path/to/workspace
@@ -784,6 +795,13 @@ 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.
 `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.0 → documentation_engine-0.4.0}/README.md

@@ -113,12 +113,14 @@ unrelated globally installed `docsystem` executable.
 For a published-package installation:
 
 ```bash
+docsystem --version
 docsystem --help
 ```
 
 For a contributor checkout:
 
 ```bash
+uv run python -m docsystem --version
 uv run python -m docsystem --help
 ```
 
@@ -142,7 +144,8 @@ disposable projection. It does not require MCP.
 [docs/setup-guide.md](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 local backup path or commit private planning paths.
+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:
@@ -151,6 +154,11 @@ 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.
 ```
@@ -200,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 |
@@ -317,6 +326,8 @@ docsystem migrate . --apply
 docsystem index . --write
 docsystem changes .
 docsystem changes . --json
+docsystem provider snapshot GENERATION . --json
+docsystem provider compare BEFORE AFTER . --json
 docsystem agent-instructions .
 docsystem agent-instructions . --json
 docsystem workspace list . --workspace /path/to/workspace
@@ -767,6 +778,13 @@ 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.
 `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.0 → documentation_engine-0.4.0}/docs/README.md

@@ -31,6 +31,8 @@ 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.
 - [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.0 → documentation_engine-0.4.0}/docs/agent-contract.md

@@ -84,6 +84,15 @@ Those files are still source-of-truth operational state. An agent must not
 use a clean git status as evidence that broad filesystem operations are safe:
 ignored files can be destroyed while git remains clean.
 
+Before creating or moving private documentation, the agent must ask the user
+in English for the exact storage path and whether an existing in-repository
+documentation tree must be copied and verified. Recommend a dedicated external
+project directory, but do not infer or create a shared workspace path. Never
+remove the original tree without a separate explicit authorization. Use the
+canonical questions and neutral placeholder from
+[the setup guide](setup-guide.md#step-0-gather-facts) rather than inventing a
+machine-specific example.
+
 Before recursive copy, move, delete or sync commands; generated migrations;
 bulk rewrites; cross-OS shell snippets; or any task that touches ignored
 local-only documentation, the agent must run the project's local backup
@@ -191,6 +200,12 @@ wiring and must never be committed or printed in a report.
 
 ## Prefer `--json` over parsing text
 
+The CLI writes stdout and stderr as strict UTF-8 regardless of the host locale,
+including redirected Windows streams. Callers should decode both streams as
+UTF-8 and must not require `PYTHONUTF8` or locale-specific code pages. JSON
+keeps original Unicode characters rather than ASCII-escaping authored text;
+plain-text reads return the same UTF-8 Markdown content.
+
 `readiness`, `migration-report`, `catalog --explain`, `changes` and
 `context` accept `--json` and print one deterministic JSON value instead of
 tab-separated or prose text. An agent should use `--json` wherever it needs
@@ -579,6 +594,15 @@ 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).
+
 ## Report product issues without leaking adopter context
 
 When an agent finds a DocumentationEngine problem while working inside another

{documentation_engine-0.3.0 → documentation_engine-0.4.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` | An external consumer needs exact body-free observations from one or two 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,20 @@ 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.
+
 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.0 → documentation_engine-0.4.0}/docs/client-integration.md

@@ -35,14 +35,16 @@ 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`
 
-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 +103,15 @@ 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).
 
 `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.0 → documentation_engine-0.4.0}/docs/mcp-adapter.md

@@ -60,6 +60,9 @@ 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;
 - 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: