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

{documentation_engine-0.2.0 → documentation_engine-0.3.0}/.github/ISSUE_TEMPLATE/adoption-finding.yml

@@ -30,7 +30,7 @@ body:
     id: version
     attributes:
       label: DocumentationEngine version or commit
-      placeholder: "0bf364673c55d76d216a3dfe982b0af746f1ab69"
+      placeholder: "X.Y.Z or a full commit SHA"
     validations:
       required: true
   - type: dropdown

{documentation_engine-0.2.0 → documentation_engine-0.3.0}/.github/ISSUE_TEMPLATE/core-bug.yml

@@ -31,7 +31,7 @@ body:
     id: version
     attributes:
       label: DocumentationEngine version or commit
-      placeholder: "0bf364673c55d76d216a3dfe982b0af746f1ab69"
+      placeholder: "X.Y.Z or a full commit SHA"
     validations:
       required: true
   - type: dropdown

{documentation_engine-0.2.0 → documentation_engine-0.3.0}/.github/ISSUE_TEMPLATE/docs-pattern-request.yml

@@ -30,7 +30,7 @@ body:
     id: version
     attributes:
       label: DocumentationEngine version or commit
-      placeholder: "0bf364673c55d76d216a3dfe982b0af746f1ab69"
+      placeholder: "X.Y.Z or a full commit SHA"
     validations:
       required: true
   - type: dropdown

{documentation_engine-0.2.0 → documentation_engine-0.3.0}/.github/ISSUE_TEMPLATE/runtime-report.yml

@@ -31,7 +31,7 @@ body:
     id: version
     attributes:
       label: DocumentationEngine version or commit
-      placeholder: "0bf364673c55d76d216a3dfe982b0af746f1ab69"
+      placeholder: "X.Y.Z or a full commit SHA"
     validations:
       required: true
   - type: dropdown

{documentation_engine-0.2.0 → documentation_engine-0.3.0}/.github/PULL_REQUEST_TEMPLATE.md

@@ -4,19 +4,29 @@
 
 ## Testing
 
-<!-- Commands run and their result. Use "N/A: <reason>" for anything skipped. -->
+<!--
+Verification level: structural | focused | full
+Risk reason:
+Commands run and results:
+Checks not run: N/A with a reason; do not mark an unrun check as passing.
+See AGENTS.md and CONTRIBUTING.md for the canonical policy.
+-->
 
 ```bash
-TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run pytest
-TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run ruff check .
+# Replace with the checks selected for this change.
+git diff --check
 ```
 
 ## Checklist
 
 - [ ] This change stays within a single described scope (no unrelated
       refactors bundled in).
-- [ ] `uv run pytest` passes, and configuration-behavior changes have tests.
-- [ ] `uv run ruff check .` passes.
+- [ ] The verification level and risk reason are recorded above.
+- [ ] Relevant structural checks, focused tests or the full gate pass; every
+      unrun check is marked N/A with a reason.
+- [ ] Configuration-behavior changes include and run configuration tests, or
+      this change does not affect configuration behavior.
+- [ ] `git diff --check` passes.
 - [ ] `uv lock --check` passes, or this change does not touch dependencies
       (N/A with reason otherwise).
 - [ ] `./scripts/installed_cli_smoke.sh` passes, or this change does not
@@ -25,7 +35,8 @@ TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run ruff check .
       public-contract impact (N/A with reason otherwise).
 - [ ] The core package (`src/docsystem/`) remains provider-neutral — no
       Claude-, Copilot- or other agent-specific behavior added there.
-- [ ] No private or local generated state is committed (`.docsystem.toml`,
-      `.docsystem/`, or other adopter-local artifacts).
+- [ ] No private or local generated state is committed (root-local
+      `.docsystem.toml`, `.docsystem/`, or other adopter-local artifacts;
+      intentional public example fixtures are reviewed separately).
 - [ ] Executable bits on any added/modified shell scripts are preserved
       (`git ls-files --stage <script>` shows `100755`).

{documentation_engine-0.2.0 → documentation_engine-0.3.0}/.github/workflows/ci.yml

@@ -55,11 +55,11 @@ jobs:
       - name: Example profile adoption walkthrough
         run: |
           profile="$(mktemp -d)/profile"
-          cp -r examples/paradigmarium-profile "$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 PDOC-002 "$profile" --depth 1
-          uv run python -m docsystem context PDOC-002 "$profile" --depth 1 --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

{documentation_engine-0.2.0 → documentation_engine-0.3.0}/.gitignore

@@ -9,6 +9,6 @@ __pycache__/
 /.docsystem/
 .docsystem/
 .docsystem.local.toml
+.docsystem.project.local.toml
 /.claude/
-/.paradigmarium/
 /.orchestrator/

documentation_engine-0.3.0/AGENTS.md

@@ -0,0 +1,116 @@
+# Agent instructions
+
+## Working rules
+
+- Keep product documentation and code comments in English.
+- Keep public product documentation, contracts, fixtures and examples
+  adopter-neutral by default. Use synthetic project names, IDs, paths and
+  scenarios. Do not publish private adopter prompts, logs, document bodies,
+  planning or roadmap material, local runtime state or credentials, and do not
+  present one adopter project's policy as a universal product rule. Real
+  project names and project-specific behavior are allowed only when the user
+  explicitly authorizes publication and the content is clearly labeled as an
+  integration guide, case study or compatibility profile; keep the generic
+  contract in a separate canonical document.
+- Treat Markdown as source of truth and generated data as disposable.
+- Do not add provider-specific behavior to the core package.
+- Prefer deterministic scripts for mechanical documentation maintenance.
+- Preserve existing project files during bootstrap and migration.
+- Every change to configuration behavior requires tests.
+- Do not modify, move, delete or replace the private `plan/` tree unless the
+  user explicitly authorizes that exact operation. Treat it as local source
+  material, not generated state.
+- Do not commit, push, merge, rebase or perform destructive Git operations
+  unless the user explicitly asks.
+- Run git stage/commit operations from inside WSL for this checkout. Do not
+  stage or commit from Windows Git over `\\wsl.localhost`; it can drop
+  executable bits such as `scripts/installed_cli_smoke.sh` from `100755` to
+  `100644` and break CI with `Permission denied`.
+
+## Risk-based verification
+
+Choose the narrowest verification level that covers the change:
+
+- **Structural only:** prose documentation, comments, badges or repository
+  metadata with no runtime, contract, packaging or generated-output effect.
+  Do not run a test suite. Run relevant structural checks such as validating
+  links or TOML/JSON when applicable and always run `git diff --check`.
+- **Focused:** an isolated implementation or test change with a clear owning
+  module. Run directly affected tests and lint touched code. Configuration
+  behavior changes must include and run focused configuration tests.
+- **Full:** shared contracts or schemas, CLI behavior, catalog/graph/section
+  semantics, projection or workspace safety, dependencies, build/packaging/CI,
+  cross-module behavior, release candidates, an explicit user request, or
+  uncertainty remaining after focused checks. During implementation use
+  focused checks; run the full gate once on the finished candidate:
+
+  ```bash
+  TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run pytest
+  TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run ruff check .
+  git diff --check
+  ```
+
+WSL sessions may inherit Windows temp directories; native `/tmp` keeps pytest
+capture deterministic. Packaging and release changes additionally require the
+lock, build, distribution and installed-consumer checks documented in
+`docs/releasing.md`. Do not repeat an already-passing full gate after a later
+structural-only edit unless it changes generated artifacts, packaging inputs
+or test expectations. Report checks deliberately not run as `not run`; never
+imply that an unrun check passed.
+
+Before committing, verify executable scripts that CI runs:
+
+```bash
+git ls-files --stage scripts/installed_cli_smoke.sh
+test -x scripts/installed_cli_smoke.sh
+```
+
+Expected git mode for `scripts/installed_cli_smoke.sh` is `100755`.
+
+## Orchestration with OrchestratorEngine
+
+- Delegate only concrete, bounded work where an AI worker adds value. Use a
+  deterministic script or check runner for mechanical work and test execution.
+- Before dispatch, confirm that the project binding targets the current host
+  chat, classify the task as structural, focused or full, select an appropriate
+  enabled worker profile, and write both the complete task contract and a
+  `WORKER_TASK_INTENT` JSON file below `.orchestrator/prompts/`.
+- Set `intent.verification` before dispatch and pass the intent with
+  `worker run --intent-file`. The declared verification level is authoritative:
+  generic or copied task prose must not broaden it. If scope changes enough to
+  require another level, stop and dispatch corrected intent rather than
+  silently changing the gate.
+- Dispatch once with a stable task id. Do not spend model turns polling worker
+  state and do not dispatch a duplicate merely because a wait timed out.
+- For a bounded wait that fits the active Codex turn, prefer one direct
+  deterministic wait:
+
+  ```bash
+  orchestrator-engine --project-root <project-root> \
+    worker wait --task-id TASK-ID --json
+  ```
+
+- If ending a Codex turn while work remains active, show the user this
+  terminal command before handing off:
+
+  ```bash
+  orchestrator-engine --project-root <project-root> \
+    worker wait --task-id TASK-ID
+  ```
+
+  It reads local durable state without invoking a model. For parallel workers,
+  repeat `--task-id` and use one `--mode all` or `--mode any` wait.
+- Use a low-cost relay subagent only when its native wait is materially more
+  reliable than the direct command wait. The parent must remain active in one
+  bounded native wait; a relay must not edit, test, review or poll repeatedly.
+- Codex Desktop completion delivery is durable history, not guaranteed live
+  refresh of an already-open chat. Use the terminal wait for unknown or long
+  work. Claude uses the stream delivery documented by OrchestratorEngine and
+  does not need the Codex manual fallback.
+- On completion, inspect compact `result.json` and `evidence.json` first. Open
+  only referenced failure logs when necessary. Worker output is evidence; the
+  host agent owns final review and acceptance.
+- Preserve `.orchestrator` events, signals, results and evidence as the audit
+  trail. For OrchestratorEngine runtime/core problems, start with compact
+  `status`, use targeted diagnostics, and create a sanitized structured report
+  instead of pasting private documents or unbounded logs.

documentation_engine-0.3.0/CHANGELOG.md

@@ -0,0 +1,189 @@
+# Changelog
+
+All notable changes to Documentation Engine are documented in this file.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-15
+
+### Highlights
+
+- Task-sized AI-agent workflows now combine section references, explainable
+  change planning, context-gap feedback and proportional evidence without
+  making advanced governance mandatory for routine work.
+- Project-authored profiles, delivery mappings, program plans and
+  workstream/execution contracts provide deterministic, fail-closed evidence
+  for genuinely governed, delegated or risk-bearing delivery.
+- Read-only federation and workspace-owned incremental projections let agents
+  inspect multiple independently owned documentation sources while preserving
+  source-qualified identities and default-deny write authority.
+- Guarded maintenance adds preview hashes, bounded writes, immutable journals
+  and recovery without replacing Markdown as the source of truth.
+
+### Added
+
+- Read-only knowledge-promotion planning combines explicit `authority_for`
+  ownership, project-authored history modes, exact evidence pins, conflict
+  detection and reverse impact without returning bodies or writing Markdown.
+
+- An ignored `.docsystem.project.local.toml` pointer can route ordinary
+  project commands to one validated external documentation root without
+  exposing its absolute path in generated agent instructions. The generated
+  contract limits trusted agents to that exact private scope and forbids
+  parent/sibling discovery unless separately authorized.
+
+- Read-only shared workstream finish packets verify caller-declared outcomes
+  across independent source journals, preserve partial/blocked states and
+  reject stale source/config/workspace authority without reading document
+  bodies or claiming cross-source atomicity.
+
+- Source-qualified bounded maintenance for local workspaces: sources default
+  to `write = "none"` and may opt into `managed-maintenance`; selected writes
+  require a deterministic reviewed preview hash, selected recovery requires
+  the immutable journal manifest hash, authority evidence is source-local,
+  and a non-blocking journal lock prevents concurrent transactions without
+  claiming cross-source atomicity.
+
+- Authored `program_plan` sequencing with fail-closed `roadmap status`,
+  `roadmap next` and `roadmap explain` CLI/MCP inspection. Recommendations
+  derive lifecycle state from bounded roadmap documents, prerequisites and
+  explicit priority without reading bodies or granting execution authority;
+  deferred ideas remain visible and never produce a false complete state.
+- Workspace-owned federated projection generations reuse unchanged per-source
+  objects, verify all registered source/config/Markdown inputs and accelerate
+  complete federation queries without writing source caches.
+
+- Read-only multi-catalog federation with qualified `source::ID[#anchor]`
+  identities, authored cross-source relations, complete catalog/dependency/
+  reference/context/impact CLI queries and matching thin MCP tools.
+- Projection schema 4 preserves qualified relation boundaries on the
+  single-source direct and projected paths; older generations fall back safely
+  and can be rebuilt from Markdown.
+
+- Versioned, project-authored workstream completion criteria.
+- Read-only `criteria` and `workstream` commands for deterministic lifecycle,
+  correction and bounded evidence validation.
+- Optional `finish --workstream-record` gate and matching read-only MCP tools.
+- Versioned idea-intake placement policy, bounded request validation and the
+  read-only `intake` CLI/MCP command with explainable blocked decisions.
+- Versioned A0–A2 execution-admission policy and read-only `admission` CLI/MCP
+  evaluation for bounded workstream targets, actions, risk and authorization
+  evidence.
+- Read-only `execution-handoff` CLI/MCP packet generation and verification with
+  mandate/target hashes, section ranges, graph impact, visible completeness and
+  no embedded authored bodies.
+- Generated agent instructions now present configured intake, admission,
+  immutable handoff verification and evidence-gated finish in execution order.
+- Optional admission source scopes bind local pre-edit paths/hashes, while the
+  read-only `execution-result` CLI/MCP contract validates structured returned
+  changed-file evidence without claiming to observe external writes.
+- Read-only `metadata-inventory` CLI/MCP inspection reports observed metadata
+  coverage, YAML types and body-free per-document graph facts while hiding
+  additional values unless one field is explicitly requested.
+- Optional project-authored document profiles and read-only `profile-check`
+  CLI/MCP validation cover metadata, semantic anchor roles, relation/status
+  allowlists and history-mode evidence without inferred policy or source writes.
+- Optional delivery traceability metadata and read-only `delivery-map` CLI/MCP
+  inspection connect exact source-section contracts to delivery ownership and
+  completion evidence without reading or returning authored bodies.
+- Repeatable targeted delivery-contract lookup reports bounded mappings and
+  explicit unowned contracts, with matching MCP and generated-agent guidance.
+- Opt-in delivery-aware change plans add owner and completion evidence as a
+  separate review-only layer, with default-output compatibility and MCP parity.
+- Read-only `lifecycle` CLI/MCP validation composes an admission request,
+  host-persisted execution packet, authoritative changed-file result and
+  completed workstream record into one fail-closed, body-free evidence lineage.
+
+### Changed
+
+- Generated agent instructions now keep routine corrections on a proportional
+  read/implement/verify path and scope optional intake, admission, immutable
+  handoff, result and lifecycle evidence to durable ideas or genuinely
+  governed, delegated and risk-bearing work.
+
+- `workspace list` rows and JSON now expose each source's body-free write
+  policy so operators can inspect the default-deny boundary.
+
+- Replaced the named adopter integration guide and CI profile with a synthetic
+  client-integration contract and generic adopter fixture.
+
+## [0.2.0] - 2026-07-13
+
+### Highlights
+
+- Local workspace source selection lets one checkout address an independent
+  public or private Documentation Engine profile by a stable source name,
+  without committing machine-specific absolute paths.
+- A strict `workspace.toml` registry and ignored `.docsystem.local.toml`
+  pointer provide deterministic discovery through explicit CLI options, an
+  environment variable or local project wiring.
+- New read-only `workspace list` and `workspace doctor` commands report source
+  visibility and availability without reading document bodies or exposing
+  local paths.
+- Existing project commands and MCP tools can select one registered source;
+  explicit selection fails closed and never falls back to the positional
+  project.
+- Source roots must be contained, unique and non-overlapping. Writable
+  documentation and projection paths cannot escape through symlinks, and
+  malformed or looping paths produce bounded diagnostics instead of stack
+  traces.
+- Existing single-project CLI and MCP behavior remains unchanged when no
+  source is selected. This release deliberately does not claim cross-source
+  graph federation, remote storage, synchronization or authorization.
+
+## [0.1.2] - 2026-07-13
+
+### Fixed
+
+- The release gate now removes the `.gitignore` marker generated by `uv build`
+  before asserting and uploading the exact wheel-and-sdist artifact set. The
+  `v0.1.1` candidate stopped at this gate before any artifact was uploaded to
+  TestPyPI or PyPI; version `0.1.2` is the replacement release candidate.
+
+## [0.1.1] - 2026-07-12
+
+### Highlights
+
+- Canonical PyPI distribution identity: the distribution to be published is
+  named `documentation-engine`. The import package (`docsystem`), console
+  commands (`docsystem`, `docsystem-mcp`) and project files
+  (`.docsystem.toml`, `.docsystem/`) are unchanged.
+- Single source of truth for the package version: `pyproject.toml` now
+  derives `version` dynamically from `src/docsystem/__init__.py` instead of
+  duplicating it.
+- Release automation prepared: a tag-triggered Trusted Publishing workflow
+  builds the distributions once, verifies that the tag matches the package
+  version, publishes to TestPyPI, checks the published SHA-256 digests against
+  the built artifact, installs the result, and only then offers the same bytes
+  to PyPI behind a manual approval gate. See
+  [the release guide](docs/releasing.md).
+- CI runs on Node 24-capable action majors, declares least-privilege
+  permissions, and checks the sdist as well as the wheel.
+
+This entry documents packaging identity and release automation. Documentation
+Engine has not been published to any package index yet; `pip install
+documentation-engine` starts working only after the first successful release.
+
+## [0.1.0] - 2026-07-11
+
+### Highlights
+
+- Structured Markdown catalogs with stable document IDs, revisions, typed
+  dependency graphs and deterministic section addressing.
+- Selective `read`, `context` and `impact` workflows that preserve verbatim
+  source text and expose omitted context instead of silently truncating it.
+- Deterministic sharded projections with integrity checks, change detection and
+  safe direct-Markdown fallback.
+- Adoption support for existing documentation trees, including catalog
+  membership policies, legacy relation diagnostics and migration reports.
+- Read-only MCP adapter and structured JSON output for AI-agent integrations.
+- Workstream branching, adopter reporting and project handoff patterns.
+- Measured context-reduction methodology and a reproducible consumer-install
+  smoke test.
+
+[Unreleased]: https://github.com/Jafa7/DocumentationEngine/compare/v0.3.0...HEAD
+[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
+[0.1.1]: https://github.com/Jafa7/DocumentationEngine/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/Jafa7/DocumentationEngine/releases/tag/v0.1.0

{documentation_engine-0.2.0 → documentation_engine-0.3.0}/CLAUDE.md

@@ -16,13 +16,10 @@ Work only in the assigned checkout or detached worktree. Do not commit, push,
 merge, rebase, or modify another checkout unless the task explicitly requires
 it. Do not add Claude-specific behavior to `src/docsystem/`.
 
-Before handing work off, run the checks required by the task contract. The
-default project checks are:
-
-```bash
-TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run pytest
-ruff check .
-```
+Before handing work off, use the risk level and checks required by `AGENTS.md`
+and the task contract. Do not default to the full suite for structural-only
+documentation changes, and do not broaden a focused gate without a stated
+risk reason.
 
 Report changed files, checks, assumptions and blockers. Your report is not
 acceptance evidence by itself: an independent reviewer verifies the actual

documentation_engine-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing
+
+Documentation Engine takes engineering rules from
+[`AGENTS.md`](AGENTS.md); it is the authoritative, provider-neutral source for
+how to work in this repository. This file explains the contributor workflow
+without redefining installation, product behavior or architecture.
+
+## Development workflow
+
+Choose the contributor checkout path from the README's
+[Installation](README.md#contributor-or-unreleased-checkout) section. That is
+the single source for consumer, MCP and contributor installation commands.
+
+From that checkout, run the CLI against the current sources through `uv`:
+
+```bash
+uv run python -m docsystem --help
+```
+
+Do not set an ad-hoc `PYTHONPATH` or depend on an unrelated globally installed
+`docsystem` executable while developing. The installed consumer path is
+exercised separately by `scripts/installed_cli_smoke.sh`. See
+[Development and release verification](README.md#development-and-release-verification)
+in the README for the full contract between the two.
+
+Keep a change narrowly scoped. Update tests and public documentation in the
+same change when behavior or a public contract changes.
+
+## Verification
+
+Select the narrowest verification level that covers the risk, as defined in
+[`AGENTS.md`](AGENTS.md):
+
+### Structural only
+
+For prose documentation, comments, badges or repository metadata with no
+runtime, contract, packaging or generated-output effect, do not run a test
+suite. Validate the changed structure and links when applicable, then run:
+
+```bash
+git diff --check
+```
+
+### Focused
+
+For an isolated implementation or test change, run the directly affected tests
+and lint the touched code. For example:
+
+```bash
+TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run pytest tests/test_workspace.py
+TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run ruff check src/docsystem/workspace.py
+git diff --check
+```
+
+Every configuration-behavior change must include and run focused configuration
+tests.
+
+### Full
+
+Run the full gate once on a finished candidate when changing shared contracts
+or schemas, CLI behavior, catalog/graph/section semantics, projection or
+workspace safety, dependencies, packaging/CI, cross-module behavior or a
+release candidate:
+
+```bash
+TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run pytest
+TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run ruff check .
+git diff --check
+```
+
+Native `/tmp` keeps pytest capture deterministic when WSL inherits Windows
+temporary directories. Do not repeat an already-passing full gate after a
+later structural-only edit unless it changes generated artifacts, packaging
+inputs or test expectations.
+
+### Additional packaging checks
+
+Run only the additional checks relevant to the changed surface:
+
+```bash
+uv lock --check
+./scripts/installed_cli_smoke.sh
+git ls-files --stage scripts/installed_cli_smoke.sh
+test -x scripts/installed_cli_smoke.sh
+```
+
+- `uv lock --check` verifies `uv.lock` still matches `pyproject.toml`; run it
+  whenever you touch dependencies.
+- `./scripts/installed_cli_smoke.sh` builds a wheel, installs it into an
+  isolated venv, and runs the installed `docsystem` entry point against a
+  fresh fixture from an unrelated directory; run it whenever packaging,
+  entry points or the CLI surface change.
+- `git diff --check` catches trailing whitespace and conflict markers before
+  they land.
+- The `git ls-files`/`test -x` pair confirms `scripts/installed_cli_smoke.sh`
+  kept its `100755` executable bit — Windows-side Git staging over
+  `\\wsl.localhost` can silently drop it and break CI with
+  `Permission denied`. Run this pair before committing, and apply the same
+  check to any other shell script you add or modify under `scripts/`.
+
+Record which verification level you selected, why it applies, which commands
+passed and which checks were deliberately not run. Never report an unrun check
+as passing.
+
+## What a change must satisfy
+
+- Public documentation and code comments are English.
+- Public product documentation, contracts, fixtures and examples are
+  adopter-neutral and use synthetic identities by default. Do not publish
+  private adopter prompts, logs, document bodies, planning or roadmap material,
+  local runtime state or credentials. Put an explicitly authorized real
+  adopter example in a clearly labeled integration guide, case study or
+  compatibility profile, separate from the canonical generic contract. Follow
+  the full rule in [`AGENTS.md`](AGENTS.md).
+- The core package (`src/docsystem/`) stays provider-neutral; do not add
+  Claude-, Copilot- or any other agent-specific behavior there. Provider
+  adapters live outside the core (see `docs/mcp-adapter.md` for the pattern).
+- Every change to configuration behavior needs tests.
+- Any change to a public contract — CLI flags, output format, `--json`
+  schemas, MCP tools — needs a `CHANGELOG.md` entry and the relevant doc
+  update in the same change.
+- Do not commit private or local generated state: `.docsystem.toml` and
+  `.docsystem/` belong to adopting projects, not this repository, and
+  generated projection/cache output is disposable. See
+  [local state safety](docs/local-state-safety.md).
+
+## External contributions
+
+Work on a branch and open a pull request; do not push directly to `main`.
+Fill in the pull request template's checklist, including which checks you ran
+and which are not applicable (with a reason). See
+[the adopter reporting guide](docs/adopter-reporting.md) if you are instead
+filing a problem found while adopting Documentation Engine in another
+project, and [`SECURITY.md`](SECURITY.md) if you found a vulnerability.