documentation-engine 0.1.2__tar.gz

documentation_engine-0.1.2/.github/ISSUE_TEMPLATE/adoption-finding.yml

@@ -0,0 +1,127 @@
+name: Adoption finding
+description: Report adopter compatibility, migration profile, or workflow gaps.
+title: "[Adoption Finding]: "
+labels: ["adoption-finding", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template when DocumentationEngine behaves deterministically but does not yet fit an adopter project's real documentation workflow.
+        Use `core-bug` instead for defects reproducible with a minimal public or synthetic fixture.
+  - type: input
+    id: project
+    attributes:
+      label: Project or adopter name
+      placeholder: "example-project"
+    validations:
+      required: true
+  - type: dropdown
+    id: source
+    attributes:
+      label: Source host or agent
+      options:
+        - codex
+        - claude
+        - vscode
+        - other
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: DocumentationEngine version or commit
+      placeholder: "0bf364673c55d76d216a3dfe982b0af746f1ab69"
+    validations:
+      required: true
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      options:
+        - catalog
+        - profiles
+        - relations
+        - graph
+        - navigation
+        - anchors
+        - projection
+        - context
+        - adoption
+        - readiness
+        - reporting
+        - privacy
+        - other
+    validations:
+      required: false
+  - type: textarea
+    id: commands
+    attributes:
+      label: Commands run and exit codes
+      description: Include the adoption or shadow-run commands that exposed the gap.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Compact diagnostics or counts
+      description: Include counts such as included/excluded/unmapped, resolved migrations, boundaries, stale pins, omitted sections, direct-vs-indexed equality, or byte sizes.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: config
+    attributes:
+      label: Sanitized profile/config excerpt
+      description: Include relevant areas, identifier prefixes, catalog exclusions, relation policy, navigation settings, snapshot types, or projection settings.
+      render: toml
+    validations:
+      required: true
+  - type: textarea
+    id: affected
+    attributes:
+      label: Affected IDs, anchors, or paths
+      description: Use stable IDs, anchors, or sanitized paths when safe. Do not paste private document bodies.
+      render: text
+    validations:
+      required: false
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected adopter workflow behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior or compatibility gap
+    validations:
+      required: true
+  - type: textarea
+    id: local_changes
+    attributes:
+      label: Runtime or local-state changes made
+      description: State "none" if the run was read-only or only wrote disposable generated projection state.
+      placeholder: "none"
+    validations:
+      required: true
+  - type: textarea
+    id: requested_action
+    attributes:
+      label: Requested DocumentationEngine action
+      placeholder: "Add profile option, clarify migration guidance, improve context diagnostics..."
+    validations:
+      required: true
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy and sanitization checklist
+      options:
+        - label: I omitted or sanitized private document bodies.
+          required: true
+        - label: I omitted private scratch, review, roadmap, or planning content.
+          required: true
+        - label: I sanitized config/profile excerpts and removed secrets or private paths where necessary.
+          required: true
+        - label: Any local artifact paths are pointers only; maintainers are not expected to access private files.
+          required: true

documentation_engine-0.1.2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Adopter reporting guide
+    url: https://github.com/Jafa7/DocumentationEngine/blob/main/docs/adopter-reporting.md
+    about: Read the privacy-safe reporting policy before filing adopter reports.

documentation_engine-0.1.2/.github/ISSUE_TEMPLATE/core-bug.yml

@@ -0,0 +1,126 @@
+name: Core bug
+description: Report deterministic DocumentationEngine defects reproducible outside a private adopter corpus.
+title: "[Core Bug]: "
+labels: ["core-bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for deterministic defects in the parser, metadata model, graph, projection, context, MCP adapter, or CLI.
+        Prefer a minimal public or synthetic fixture over private adopter content.
+  - type: input
+    id: project
+    attributes:
+      label: Project or adopter name
+      description: Use the adopter name if discovered during adoption, or "synthetic fixture".
+      placeholder: "synthetic fixture"
+    validations:
+      required: true
+  - type: dropdown
+    id: source
+    attributes:
+      label: Source host or agent
+      options:
+        - codex
+        - claude
+        - vscode
+        - other
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: DocumentationEngine version or commit
+      placeholder: "0bf364673c55d76d216a3dfe982b0af746f1ab69"
+    validations:
+      required: true
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      options:
+        - catalog
+        - metadata
+        - sections
+        - relations
+        - graph
+        - projection
+        - context
+        - mcp
+        - cli
+        - other
+    validations:
+      required: false
+  - type: textarea
+    id: fixture
+    attributes:
+      label: Minimal public or synthetic reproduction fixture
+      description: Paste only the smallest sanitized fixture or explain why it cannot be minimized yet.
+      render: markdown
+    validations:
+      required: true
+  - type: textarea
+    id: commands
+    attributes:
+      label: Commands run and exit codes
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Compact diagnostics
+      description: Include exact errors, warnings, JSON fields, or counts needed to reproduce the defect.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: config
+    attributes:
+      label: Sanitized config/profile excerpt
+      description: Include the smallest config needed for the bug. Use "not applicable" if none.
+      render: toml
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: local_changes
+    attributes:
+      label: Runtime or local-state changes made
+      description: State "none" if no generated state, cache, config, or local files were changed after the failure.
+      placeholder: "none"
+    validations:
+      required: true
+  - type: textarea
+    id: requested_action
+    attributes:
+      label: Requested DocumentationEngine action
+      placeholder: "Fix parser diagnostic, make projection fallback fail closed, add regression..."
+    validations:
+      required: true
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy and sanitization checklist
+      options:
+        - label: I omitted or sanitized private document bodies.
+          required: true
+        - label: I omitted private scratch, review, roadmap, or planning content.
+          required: true
+        - label: I sanitized config/profile excerpts and removed secrets or private paths where necessary.
+          required: true
+        - label: Any local artifact paths are pointers only; maintainers are not expected to access private files.
+          required: true
+        - label: I provided a minimal public/synthetic fixture or explained why not.
+          required: true

documentation_engine-0.1.2/.github/ISSUE_TEMPLATE/docs-pattern-request.yml

@@ -0,0 +1,91 @@
+name: Documentation pattern request
+description: Request a reusable documentation pattern, template, workflow, or privacy-safe reporting convention.
+title: "[Docs Pattern Request]: "
+labels: ["docs-pattern-request", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for reusable documentation patterns discovered during adopter work.
+        Use `runtime-report`, `adoption-finding`, or `core-bug` for defects.
+  - type: input
+    id: project
+    attributes:
+      label: Project or adopter name
+      placeholder: "example-project"
+    validations:
+      required: true
+  - type: dropdown
+    id: source
+    attributes:
+      label: Source host or agent
+      options:
+        - codex
+        - claude
+        - vscode
+        - other
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: DocumentationEngine version or commit
+      placeholder: "0bf364673c55d76d216a3dfe982b0af746f1ab69"
+    validations:
+      required: true
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      options:
+        - adoption
+        - reporting
+        - navigation
+        - context
+        - templates
+        - privacy
+        - other
+    validations:
+      required: false
+  - type: textarea
+    id: scenario
+    attributes:
+      label: Reusable scenario
+      description: Describe the pattern need without private project details.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Compact evidence or examples
+      description: Include sanitized counts, commands, or minimal examples that show why this should be reusable.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: proposed_pattern
+    attributes:
+      label: Proposed pattern or template shape
+      description: If known, describe sections, metadata fields, workflow gates, or examples.
+    validations:
+      required: false
+  - type: textarea
+    id: requested_action
+    attributes:
+      label: Requested DocumentationEngine action
+      placeholder: "Add guide, add template, clarify adoption docs..."
+    validations:
+      required: true
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy and sanitization checklist
+      options:
+        - label: I omitted or sanitized private document bodies.
+          required: true
+        - label: I omitted private scratch, review, roadmap, or planning content.
+          required: true
+        - label: I sanitized config/profile excerpts and removed secrets or private paths where necessary.
+          required: true
+        - label: Any local artifact paths are pointers only; maintainers are not expected to access private files.
+          required: true

documentation_engine-0.1.2/.github/ISSUE_TEMPLATE/runtime-report.yml

@@ -0,0 +1,119 @@
+name: Runtime report
+description: Report adopter-side setup, local state, or docsystem execution problems.
+title: "[Runtime Report]: "
+labels: ["runtime-report", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for local setup and execution issues in an adopter project.
+        Do not paste private document bodies, large logs, or full generated projections.
+  - type: input
+    id: project
+    attributes:
+      label: Project or adopter name
+      description: Use a short public-safe project name or slug.
+      placeholder: "example-project"
+    validations:
+      required: true
+  - type: dropdown
+    id: source
+    attributes:
+      label: Source host or agent
+      options:
+        - codex
+        - claude
+        - vscode
+        - other
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: DocumentationEngine version or commit
+      placeholder: "0bf364673c55d76d216a3dfe982b0af746f1ab69"
+    validations:
+      required: true
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      options:
+        - setup
+        - readiness
+        - local-state
+        - cli
+        - projection
+        - mcp
+        - other
+    validations:
+      required: false
+  - type: textarea
+    id: commands
+    attributes:
+      label: Commands run and exit codes
+      description: Include exact commands and exit codes. Redact private paths if needed.
+      render: shell
+      placeholder: |
+        docsystem readiness /path/to/project --json
+        exit: 1
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Compact diagnostics or counts
+      description: Prefer compact output from readiness, doctor, validate, index, changes, context, read, or impact. Summaries are better than unbounded logs.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: config
+    attributes:
+      label: Sanitized config or profile excerpt
+      description: Include only relevant areas, identifiers, catalog policy, relation policy, navigation settings, projection settings, or MCP setup.
+      render: toml
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should have happened?
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: local_changes
+    attributes:
+      label: Runtime or local-state changes made
+      description: State "none" if no generated state, cache, config, or local files were changed after the failure.
+      placeholder: "none"
+    validations:
+      required: true
+  - type: textarea
+    id: requested_action
+    attributes:
+      label: Requested DocumentationEngine action
+      placeholder: "Clarify setup guide, fix CLI runtime behavior, improve diagnostic..."
+    validations:
+      required: true
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy and sanitization checklist
+      options:
+        - label: I omitted or sanitized private document bodies.
+          required: true
+        - label: I omitted private scratch, review, roadmap, or planning content.
+          required: true
+        - label: I sanitized config/profile excerpts and removed secrets or private paths where necessary.
+          required: true
+        - label: Any local artifact paths are pointers only; maintainers are not expected to access private files.
+          required: true

documentation_engine-0.1.2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+## Summary
+
+<!-- What changed and why. Link related issues if any. -->
+
+## Testing
+
+<!-- Commands run and their result. Use "N/A: <reason>" for anything skipped. -->
+
+```bash
+TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run pytest
+TMPDIR=/tmp TMP=/tmp TEMP=/tmp uv run ruff 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.
+- [ ] `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
+      affect packaging/entry points/CLI surface (N/A with reason otherwise).
+- [ ] `CHANGELOG.md` and relevant docs are updated, or this change has no
+      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).
+- [ ] Executable bits on any added/modified shell scripts are preserved
+      (`git ls-files --stage <script>` shows `100755`).

documentation_engine-0.1.2/.github/copilot-instructions.md

@@ -0,0 +1,13 @@
+# GitHub Copilot instructions
+
+Follow the repository's [`AGENTS.md`](../AGENTS.md) as the primary,
+provider-neutral instruction source. This file is only a thin Copilot adapter;
+do not duplicate product architecture or private planning here.
+
+For orchestrated work, read the supplied task contract first. Work only in its
+assigned checkout or detached worktree and allowed paths. Run the required
+checks, report changed files and evidence, and do not commit, push or accept
+your own changes.
+
+Use [`README.md`](../README.md), [`docs/architecture.md`](../docs/architecture.md)
+and [`docs/adoption.md`](../docs/adoption.md) for public product behavior.

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

@@ -0,0 +1,65 @@
+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/paradigmarium-profile "$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 changes "$profile" --json