Adopt portable documentation checks

Use the portable runtime for an authorized repository setup. Its adjacent lock pins dependencies. The runtime needs Git, uv 0.12.9 or later, and Python 3.12 or 3.13. It needs no Slopsentral checkout, mise, npm, or installed plugin composition. Reuse the repository’s knowledge store and documentation commands when they already meet the task. A normal code task does not authorize knowledge generation or adoption of this gate.

Select the runtime and project

Resolve the runtime’s absolute path inside the installed skill. Use that script with its adjacent lock. Installed caches remain consumers. Copy the complete project template into an independent Git repository for a minimal example. Include its hidden .knowledge directory. The template uses app/, handbook/, and knowledge/ with no repository-specific assumptions. Its coverage configuration selects plain OKF. It needs no native Claims sidecars or OpenWiki checkpoint. Run the installed runtime directly:

uv run --locked --script /absolute/path/to/code-knowledge-base/scripts/documentation.py check --repo /absolute/path/to/project --config .knowledge/coverage.json --lock .knowledge/review.lock.json

The runtime emits JSON and a process status. CURRENT returns 0. STALE returns 1 with affected areas. Invalid configuration, missing evidence, broken links, or incomplete native state return REJECTED with status 2. A missing lock is rejected by check. It never establishes current documentation. The review lock must use a separate path outside every prepared input. It cannot replace a source, page, configuration, Claim sidecar, or completion record. record preserves existing targets without the KNOWLEDGE_REVIEW kind and valid receipt structure. It stages the admitted receipt beside its target before replacement. The kind marks the format, without cryptographic authentication or protection against a hostile concurrent writer.

Define the source-to-concept map

Adapt the template’s configuration to the actual source and document roots. The configuration schema describes version 2. Every declared field is necessary:

Field	Contract
`knowledge`	Select `OKF` or `OPENWIKI` and its repository-relative root.
`sourceRoots`	Select the files whose changes need explanation coverage.
`documentRoots`	Select all Markdown documentation that the gate owns.
`entrypoints`	Name the documentation roots from which readers can reach pages.
`auxiliary`	Name supporting Markdown files exempt from reachability and concept metadata.
`archives`	Name historical pages outside active link and freshness assessment.
`areas`	Map each stable area ID to source selections and explanation pages.
`fingerprintIgnores`	Declare deliberate JSON-field exceptions, or use an empty list.

Paths are repository-relative. A trailing slash selects a directory prefix. A path without that slash selects one exact file. Source selections and area selections must contain files. Each area needs an explanation beneath the selected knowledge root. Every declared page must belong to documentRoots. Each concept carries nonempty type, title, and description fields. Use source citations and concept links to explain mechanisms, consumers, invariants, and failures. The page contract defines standalone OKF format and source-evidence procedures. The template concept supplies a concrete source-linked example. The gate rejects uncovered source files and unowned active pages. It also rejects missing targets, missing Markdown anchors, and pages unreachable from entrypoints. These assertions establish the configured graph. They do not establish complete semantic coverage. An area named after a subsystem still needs a useful explanation of that subsystem.

Review before a snapshot

Run check before a source change when a lock exists. After a source change, use its affected areas to choose the explanations for review. Read the source diff, direct consumers, and executable evidence before a documentation decision. Refresh changed explanations, citations, indexes, and inbound links together. If the explanation remains accurate, record the source-backed no-change reason in the existing PR or task receipt. Keep historical results identified as historical. Do not rewrite an old measurement as a current result. Run the selected format, source-evidence, prose, and focused behavior procedures. Resolve missing evidence before this deliberate snapshot command:

uv run --locked --script /absolute/path/to/code-knowledge-base/scripts/documentation.py record --repo /absolute/path/to/project --config .knowledge/coverage.json --lock .knowledge/review.lock.json
uv run --locked --script /absolute/path/to/code-knowledge-base/scripts/documentation.py check --repo /absolute/path/to/project --config .knowledge/coverage.json --lock .knowledge/review.lock.json

Review the configuration and lock diff with the source and page diff. Commit them through the project’s existing delivery process. Never refresh a snapshot only to remove a stale result. record stores reviewed bytes. It does not inspect the quality of the review or prove factual accuracy. A new source file, renamed path, changed page, or changed configuration can invalidate the snapshot. An unchanged digest cannot prove runtime readiness, continued external validity, or reader comprehension. No wall-clock age policy is implicit.

Declare fingerprint exceptions

The runtime has no implicit version exclusions or Slopsentral paths. Use an empty fingerprintIgnores list unless source review justifies an exception. A declared exception selects exact JSON fields through JSON Pointers:

"fingerprintIgnores": [
  {
    "path": "product.json",
    "pointers": ["/version", "/plugins/0/plugin/version"]
  }
]

This fragment assumes that product.json and both fields exist in the selected source. The gate rejects an invalid pointer or a pointer that does not resolve. The listed fields no longer affect the source fingerprint. Other fields still affect it. Document why each excluded change cannot invalidate its explanation. Treat exceptions as reviewed policy rather than a general release workaround.

Preserve an OpenWiki owner

For an existing OpenWiki repository, select:

"knowledge": { "type": "OPENWIKI", "root": "openwiki" }

Use the external OpenWiki integration’s begin, plan, page, Claim, and finish lifecycle. Keep its run state, evidence versions, indexes, and provenance under that owner. The portable gate rejects an incomplete checkpoint or active run. It also needs material Claims for each managed concept. The gate does not recreate native Claim reconciliation or certify Claim semantics. Complete native finalization before record. For a plain OKF store, keep OKF selected and use the standalone page procedures instead. Do not create another knowledge store to satisfy the gate.

Keep a pinned consumer command

Direct installed-runtime use keeps one canonical implementation. A project can instead copy the exact script and lock as a pinned consumer tool. Record their upstream source revision and SHA-256 digests in the project’s existing dependency record. Keep the copied files byte-identical to that selected source. Review upstream changes before an update and refresh the recorded provenance deliberately. For a local command, copy the selected pair to bin/knowledge and bin/knowledge.lock. Keep the lock beside the executable with the matching base name. Do not edit the consumer copy to add project policy. Change the coverage configuration instead. The script remains runnable from outside the original checkout with explicit --repo, --config, and --lock.

Add a CI check when authorized

The example assumes an approved, committed copy at .knowledge/runtime/documentation.py with its matching lock. Pin that pair’s revision and digests before use. The existing CI environment must provide Git and Python 3.12 or 3.13. Pin uv to 0.12.9 through that environment’s tool owner. The following illustrative job uses GitHub Actions. Replace action placeholders with approved complete commit SHAs. It stages the pinned consumer pair and runs check only:

jobs:
  documentation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<approved-complete-commit-sha>
      - uses: astral-sh/setup-uv@<approved-complete-commit-sha>
        with:
          version: '0.12.9'
          python-version: '3.12'
      - name: Stage the reviewed runtime and examine documentation
        run: |
          python - <<'PY'
          import shutil
          from pathlib import Path
          target = Path('bin')
          target.mkdir(exist_ok=True)
          shutil.copyfile('.knowledge/runtime/documentation.py', target / 'knowledge')
          shutil.copyfile('.knowledge/runtime/documentation.py.lock', target / 'knowledge.lock')
          PY
          uv run --locked --script bin/knowledge check --repo "$GITHUB_WORKSPACE" --config .knowledge/coverage.json --lock .knowledge/review.lock.json

CI must not run record, generate pages, install plugins, or write remote configuration as a side effect of this check. The example supplies no remote setup or scheduling authority. Keep runtime files outside documentRoots and map them as source when their behavior forms part of project coverage.

Start here

Developer docs