All procedures
runbookuai-explorerOperator truth

Documentation Source Of Truth Runbook

Synced UAI Explorer runbook documentation from docs/runbooks/documentation-source-of-truth.md.

Updated 2026-06-21·Freshness: Current·No secret-like patterns were observed in this view.

Documentation Source Of Truth Runbook

Created: 2026-06-21

Purpose

Make UAI Explorer the canonical home for UAI operational memory.

Local files can still exist while drafting, surveying, redacting, or working offline, but important runbooks, plans, surveys, standards, evidence, and start-here files must not remain local-only.

Rule

Explorer is the source of truth. Device-local documents are one of:

  • draft: useful but not reviewed.
  • review: ready for operator or domain review.
  • approved: reviewed and safe for catalog staging.
  • published: present in the Explorer catalog or approved catalog package.
  • superseded: retained for lineage but not current truth.
  • private: kept outside Explorer runtime until selected redaction and review.

Do not treat loose Desktop/Documents files, shell history, old project folders, or ad hoc notes as the long-term documentation system.

Canonical Flow

  1. Create or update a document in the repo, a project workspace, or a private raw survey lane.
  2. Classify it: project, owner/source, freshness, sensitivity, audience, and publish state.
  3. If it is private or raw, run selected redaction before public catalog use.
  4. Stage approved content into an Explorer catalog root.
  5. Import approved catalog rows with explicit --apply authority.
  6. Verify the item is visible only to the intended human and AI tags.
  7. Mark old local copies as caches or superseded references.

What Must Be Cataloged

  • Current runbooks.
  • Current start-here files.
  • Production/sandbox evidence.
  • Device survey summaries.
  • UX and documentation standards.
  • Operator decisions.
  • Public-safe content promotion packets.
  • Active project briefs and context notes.

What Must Stay Private

  • .env, .ssh, keychains, browser profiles, cookies, auth stores, session databases, private keys, credential values, and raw logs.
  • Raw survey inventories that expose file aliases, source hashes, or private filesystem structure.
  • Unredacted selected artifacts.
  • Device-local project folders before survey, redaction, and review.

Sync Pattern

Use the content-promotion workflow for reviewed artifacts:

python tools\prepare_catalog_import.py --export-dir <redacted-output> --approval <approval.json> --out <approved-import.json>
python tools\stage_approved_catalog.py --export-dir <redacted-output> --approved-import <approved-import.json> --catalog-root <catalog-data-root> --out <staged-import.json>
python tools\import_staged_catalog.py --staged-import <staged-import.json> --data-root <catalog-data-root> --db <uai-explorer.sqlite3> --out <import-result.json> --apply

For repo-native docs that are already public-safe, update the repo and promote through the production refresh path. Do not bypass the catalog with arbitrary raw filesystem browsing.

Device Start Files

Device-local START_HERE_UAI_LAB.md files are safe caches that point back to Explorer. They should stay short and operational.

They must not become hidden documentation stores. If a start file grows into a real runbook, move the runbook into Explorer and leave a pointer in the local start file.

Acceptance Check

A documentation pass is complete only when:

  • current docs are in Explorer or intentionally private,
  • stale docs are marked superseded or kept as historical evidence,
  • no secrets were copied into docs, prompts, tests, or evidence,
  • AI lanes can retrieve approved docs through /api/ai/bootstrap and /api/ai/context/{slug},
  • humans can retrieve approved docs through the catalog/reader,
  • local-only copies are documented as caches, drafts, or private material.