All runbooks
runbookuai-explorerredacted view

Device Documentation Survey Runbook

Synced UAI Explorer runbook documentation from docs/runbooks/device-documentation-survey.md.

Updated 2026-06-21·Freshness: Reference·Sensitive tokens or credentials were hidden before display.

Device Documentation Survey Runbook

Created: 2026-06-20

Purpose

Capture useful documentation, UI standards, and project memory from UAI devices without mounting raw device data into public UAI Explorer.

This runbook is the intake path for MacBook material, especially Devine and Cadence UI/UX standards that should become polished UAI Explorer catalog entries after review.

Targets

  • Primary workstation: NUC-IPEX
  • Forward development device: MacBook
  • Dormant future Proxmox node: survey before cluster join
  • Lab and Proxmox references: use existing sandbox protocol, do not mutate production CT 121
  • Public Explorer runtime: sanitized catalog output only

Track current coverage in [REDACTED:high-entropy].md. If a device is visible on the network but not confirmed as a documentation source, record it as needs-identification; do not assume it is the dormant future Proxmox node.

No-Change Boundaries

  • Do not mount MacBook, dormant-device, or raw survey folders into the public Explorer container.
  • Do not copy credentials, keychains, .env files, browser profiles, SSH folders, session stores, logs, caches, or auth databases into Explorer.
  • Do not mark out-of-sync material as current truth. Preserve it as lineage, parked ideas, or superseded context until reviewed.
  • Do not change production CT 121, public DNS, TLS, firewall, or reverse proxy routing from this workflow.

Survey Output Shape

Each surveyed source should produce a manifest, not a raw public mirror:

  • device name
  • source root alias, not secret-bearing absolute paths when avoidable
  • project or topic name
  • candidate version, such as Cadence v5, Cadence v6, or Devine
  • file type and modified time
  • hash of source artifact
  • sensitivity guess
  • suggested Explorer tags
  • suggested idea state: new, needs_review, parked, promoted, superseded, or archived
  • redaction status
  • recommended catalog destination

MacBook Devine/Cadence Intake

Survey candidates:

  • Devine UI/UX standards
  • Cadence design doctrine and version notes
  • reusable component conventions
  • copywriting standards
  • dashboard and reader UX notes
  • historical design ideas that should be parked, not deleted

Required handling:

  • classify Devine and Cadence material by project, version, and freshness,
  • extract standards into clean summaries,
  • preserve source lineage so old ideas can be traced later,
  • promote only reviewed standards into the active catalog,
  • keep raw MacBook documents in the raw survey zone until redacted.

Public-Safe Pipeline

  1. Survey explicit roots into raw-survey-zone:
python tools\survey_device_documents.py `
  --device <device-name> `
  --host <host-name> `
  --root "Desktop=C:\Users\<user>\Desktop" `
  --root "Documents=C:\Users\<user>\Documents" `
  --out raw-survey-zone\<device>\<date> `
  --summary docs\surveys\<device>-<date>-summary.md `
  --date <date> `
  --max-depth 5 `
  --max-entries 18000 `
  --max-entries-per-root 1500

Use explicit roots only. The worker records metadata, hashes only non-suppressed documentation candidates, excludes raw/cache/auth/dependency folders, suppresses secret-adjacent aliases before output, and writes manifest.json, inventory.csv, inventory-stats.json, and a public-safe summary. 2. Generate a metadata-only sanitized export for outside agents or catalog planning:

python tools\sanitize_survey_export.py `
  --manifest raw-survey-zone\<device>\<date>\manifest.json `
  --inventory raw-survey-zone\<device>\<date>\inventory.csv `
  --out sanitized-exports\<device>\<date>
  1. Regenerate the public-safe device coverage index from metadata manifests:
python tools\build_device_survey_index.py --date <date>

Use --state-override, --note-override, and --blocker for operator observations that cannot be derived from static manifests, such as a device that was surveyed earlier but is currently unreachable. 4. Build a public-safe content promotion packet from sanitized exports:

python tools\build_content_promotion_packet.py `
  --export-dir sanitized-exports\<device>\<date> `
  --out-md docs\review\content-promotion-packet-<date>.md `
  --out-json docs\review\content-promotion-packet-<date>.json

The packet is an operator selection aid only. It must not include raw file aliases, raw hashes, absolute paths, source paths, or raw content. 5. Run redaction and classification worker only on selected raw candidates in the private raw/redaction lane:

python tools\redact_selected_artifacts.py `
  --source-root <private-redaction-root> `
  --selection <selection.json> `
  --out <sanitized-output>

The selection file must name explicit source_path values relative to the private source root. The worker rejects path traversal, refuses binary input, redacts secret-shaped content, and writes manifest.json, redaction-report.json, catalog-import.json, and artifacts/*.md. These outputs are review-required and non-publishable until an operator approves them for a governed catalog lane. 6. Write sanitized summaries, approved excerpts, hashes, and lineage metadata. 7. Review and tag material as docs, design-standards, cadence, devine, uai, or project-specific tags. 8. Publish only sanitized artifacts into the public Explorer catalog.

The metadata-only export must not include raw file aliases, raw source hashes, or raw content. Use raw_inventory_row only as a private operator lookup reference back to the raw survey inventory.

Verification

Before catalog publication, confirm:

  • raw source folders are not mounted in the Explorer web container,
  • device survey summaries do not include raw file aliases or hashes,
  • metadata-only exports contain no raw file aliases, raw source hashes, or raw content,
  • selected redaction outputs contain no raw source paths, raw source hashes, or unredacted secret-shaped values,
  • redacted output has no secret-like tokens,
  • context notes are redacted before API delivery,
  • catalog items use required tags,
  • Devine/Cadence material has a freshness state,
  • source lineage points back to the survey manifest,
  • public-safe tests pass:
python tests\test_public_safe.py

Rollback

If bad material is published:

  • disable the affected catalog item,
  • remove the sanitized artifact from the public output directory,
  • keep the raw source untouched in the raw survey zone,
  • record the issue in the diary and review queue,
  • rerun redaction and tests before republishing.