Skip to main content
Documentation forms part of the engineering change contract. A reader must reach the responsible source, understand the mechanism, and see the limits of its evidence. The documentation practice owns the concrete repository procedure.

Establish coverage before prose

Start with the reader’s action or decision. Map functional areas to their entry points, owners, state, failures, direct consumers, and executable evidence. Use docs/coverage.json to connect those areas with the current guides and OKF explanations. Page counts and directory inventories do not establish mechanism coverage. Reuse docs/glossary.json and its generated reader view. The glossary already covers the wiki. Its definitions remain provisional because independent reader review remains absent. A rewrite in another repository creates a minimal source-backed glossary only when no owner exists. Assessment alone and ordinary code work do not authorize glossary creation.

Adopt the same practice in another project

Code Knowledge Base ships the portable runtime, its lock, a schema, and a complete example project. The adoption procedure explains configuration and consumer provenance. It does not need the Slopsentral checkout, its Node dependencies, or its project tooling. Schema version 2 selects source roots, document roots, entrypoints, auxiliary pages, areas, archives, and explicit fingerprint exceptions. It also selects OKF or OPENWIKI with the knowledge root. An ordinary OKF project needs no native Claim sidecars or completion checkpoint. An OpenWiki project keeps the native lifecycle and its stronger admission prerequisites. Slopsentral’s bin/slopsentral-docs uses that same runtime. Its project policy lives in docs/coverage.json, including the deliberate product-version exceptions. The runtime contains no implicit Slopsentral paths or release exceptions. The package assertions run shipped bytes in independent Git projects for all four providers. The review lock must use a separate output path outside every prepared input. It cannot replace a source, document, configuration, or native evidence file. An existing target needs the KNOWLEDGE_REVIEW kind and valid receipt structure. The writer consumes an admitted target and stages the receipt before replacement. The kind describes the format, without cryptographic authentication or hostile-writer guarantees. Review affected source and explanations before record. CI runs check without refreshing expected fingerprints or generating pages. A copied script and lock remain pinned consumer assets whose upstream revision and digests need a deliberate update.

Complete the native lifecycle

Resolve the exact Git top-level before the OpenWiki run. Start or resume an update run through the external integration. If planning is necessary, submit canonical page paths with source seeds and useful neighbors. Do not plan generated indexes as content pages. Consume one assigned page at a time. Examine current source, write valid OKF frontmatter, and reconcile its material Claims. Confirm stale Claims only after source review. Keep unchanged identities, revise the same proposition under its existing identity, and retract propositions the page no longer asserts. Continue the persisted queue until the integration returns complete. Then finish the run through OpenWiki. Native finalization owns indexes, sidecars, source versions, provenance, and completion metadata. Never repair those files by hand or substitute standalone OKF validation. After native finalization, use the repository gate:
A changed source or page invalidates the recorded byte agreement. The review record also binds native Claim sidecars and completion metadata. A later change needs another review. Review the affected explanations and rejected links before the explicit record operation. Keep the receipt diff with the reviewed source diff. The gate establishes coverage and byte agreement. It does not grade the meaning of a Claim. Assess changed technical prose with the pinned Vale procedure:
Keep the report and examine findings at their reported lines. An ASSESSED result does not mean that the report is clean. Readability measurements do not prove reader comprehension.

Recurring updates propose review

Update Repository Documentation runs on selected main pushes, manual dispatch on main, and daily at 09:17 UTC. It serializes runs, reads trusted main source, and does not persist checkout credentials. The runtime is OpenWiki 0.6.1 with model gpt-5.6-terra. The workflow needs separate OPENAI_API_KEY and OPENWIKI_PR_TOKEN repository secrets. The first authenticates generation. The second needs repository Contents and Pull requests write access for the documentation PR. Keep values in the private secret interface. The workflow rejects a noncomplete native checkpoint or an active run file. It checks the glossary and proposes only generated wiki changes. Checkpoint-only changes do not select a PR. When substantive changes select a PR, .last-update.json and .page-manifest.json remain eligible. The path allowlist excludes .run.json and authored INSTRUCTIONS.md. It neither auto-merges nor publishes executable source changes. A locally accepted workflow does not prove that its credentials exist or that an Actions run succeeded.

Project canonical explanations to the public site

site.json maps current guides and OKF concepts to Mintlify routes, navigation, and redirects. The site runtime projects those sources into docs/public. OpenWiki remains the knowledge owner. The public copy removes native producer metadata and keeps the canonical body. Repository links become public routes or GitHub source links. Code examples keep their literal content. After source review and native finalization, refresh the public projection:
The first command changes generated site input. The second rejects stale input before the native Mintlify build and link assessment. An absent docs/public tree cannot pass as an empty selection. The ordinary source gate also invokes this projection admission. Mintlify reads main/docs/public from amichne/slopsentral. The site workflow separately examines deployed content after a main build. It compares all mapped pages, including link destinations and code indentation, with the expected canonical content. Missing pages and stale bodies fail within its bounded retry interval. A matching response does not establish browser layout or Mintlify’s exact hosted build SHA. Use the site procedure for deployment status, browser evidence, and recovery. An authorized manual run on another branch compares its checker with main documents. This mode reads the site and does not publish pending prose. Normal main runs compare their own source. The receipt records the checker commit and expected document commit separately.