> ## Documentation Index
> Fetch the complete documentation index at: https://slopsentral.michne.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Adopt portable documentation checks

> Adopt the distributed documentation gate in a project with its own layout and OKF owner.

Use the [portable runtime](https://github.com/amichne/slopsentral/blob/main/source/skills/code-knowledge-base/scripts/documentation.py) for an authorized repository setup.
Its [adjacent lock](https://github.com/amichne/slopsentral/blob/main/source/skills/code-knowledge-base/scripts/documentation.py.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](https://github.com/amichne/slopsentral/blob/main/source/skills/code-knowledge-base/assets/portable-project/README.md) 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](https://github.com/amichne/slopsentral/blob/main/source/skills/code-knowledge-base/assets/portable-project/.knowledge/coverage.json) selects plain OKF.
It needs no native Claims sidecars or OpenWiki checkpoint.

Run the installed runtime directly:

```sh theme={null}
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](https://github.com/amichne/slopsentral/blob/main/source/skills/code-knowledge-base/references/documentation.schema.json) 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](https://github.com/amichne/slopsentral/blob/main/source/skills/code-knowledge-base/references/knowledge-page-contract.md) defines standalone OKF format and source-evidence procedures.
The [template concept](https://github.com/amichne/slopsentral/blob/main/source/skills/code-knowledge-base/assets/portable-project/knowledge/greeting.md) 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:

```sh theme={null}
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:

```json theme={null}
"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:

```json theme={null}
"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:

```yaml theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.