Governance docs
runbookuai-explorerv3Agent-only

Agent Journey — Bootstrap to Done

First agent-facing contract — redaction, permissions, no local copies, sandbox stop.

Updated 2026-07-04·Freshness: Agent·No secret-like patterns were observed in this view.

Agent Journey — Bootstrap to Done

First agent-facing contract — redaction, permissions, no local copies, sandbox stop.

Body

Agent Journey — Bootstrap → Done

Status: binding entry runbook (read before acting)
Date: 2026-07-04 (fable-owned impress pass)
Audience: AI agents on any UAI lane
Canonical catalog slug (join): uai-doc-governance- + agent-journey-bootstrap-to-done

This is the first agent-facing contract for a session. It prevents mistakes before they happen. The full binding protocol remains uai-doc-governance- + uai-agent-protocol vnext (join). On conflict with older Explorer-only text, vNext + this journey win.

Read this first (before any action)

1. Redaction policy (prevent, do not only catch)

  • Explorer is public-safe and server-side redacted. AI clients receive redacted packets only (raw_available_to_client=false, redaction_boundary=server-side).
  • MUST NOT paste secrets, tokens, private keys, private paths, cookies, or unredacted survey material into catalog bodies, feedback, diary, plans, evidence, or receipts.
  • Write-time gate: POST/PATCH that looks secret-like returns 422. Do not rewrite to smuggle the secret past the gate. Surface the block.
  • Long catalog slugs may trip the high-entropy gate — reference them as join-segments in bodies; full slug stays in metadata/URL.
  • Human HTML /docs/{slug} is a redacted reading view, not authority. Agents MUST use GET /api/ai/context/{slug} and require audit_event_id + redaction fields.

2. Permissions you have (AI role)

You MAY (with a valid AI PAT):

Action Endpoint
Ready / health GET /ready, GET /health
Bootstrap contract GET /api/ai/bootstrap
Catalog list GET /api/ai/catalog
Context packet GET /api/ai/context/{slug}
Author / edit docs POST /api/ai/documents, PATCH /api/ai/documents/{slug}
Versions GET /api/ai/documents/{slug}/versions
Capability map GET /api/ai/capability-map (+ card / breadcrumb routes)
Feedback POST/GET /api/ai/feedback
Promotion request POST /api/ai/promotion-requests

You MUST NOT use denied surfaces (admin, raw filesystem, uploads, SQLite, .env, .ssh, raw-survey-zone, arbitrary path search). Bootstrap lists them with reasons and alternatives.

Tag ACL: documents require tags that are a subset of your session tags. Missing tags on a required primary_context ⇒ stop and report (do not invent access).

3. Catalog-only truth

  • Published Explorer catalog with context HTTP 200 is operational SOT for rules/runbooks.
  • Local files, Mac archives, and live host processes are not policy by themselves.
  • Live hosts = facts only (is it running?). Mac archives = preserve only. Feedback = signal only until promoted.
  • MUST NOT hoard local mirrors of Explorer catalog, runtime DBs, or product data — read via API; authorized local files are handoff receipts and START_HERE entry only.

4. No local copies (prevent hoarding)

  • Explorer is SOT. MUST NOT clone or store duplicate doc trees, databases, product data, or ecosystem state on Mac/agent workspace.
  • Bootstrap from GET /api/ai/context/{slug} — MUST NOT scrape and mirror catalog offline.
  • Runtime data lives on VPS, NUC, lab CTs — MUST NOT treat Mac as runtime data home.
  • mac_hosting=never extends to data hoarding (local_data_hoarding=never).
  • Need persistence → Explorer feedback or designated remote path — not ad-hoc local caches.
  • Authorized: wipe handoff receipts, START_HERE chain, owner preserve paths per runbook.

5. Promote path (rules and durable truth)

propose (local draft, no secrets)
  → sandbox verify (lane-appropriate; stop sandbox when done)
  → evidence receipt
  → promote lab (write-SOT)
  → promote public (manual; no auto-sync)
  → capability breadcrumb if infra-affecting
  → verify context HTTP 200 on lab and public for binding slugs

MUST NOT silently edit binding rules. Lab is write-SOT; public lags until explicit promote.

6. Sandbox stop rule (owner teeth)

  • Sandboxes (CT123, CT124, CT126, peers) are KEEP, not retire.
  • MUST stop sandbox containers when done (free RAM).
  • MUST NOT destroy sandboxes unless a separate owner-signed stage lists that VMID.
  • MUST NOT leave sandboxes idle-running after work.
  • Explorer exploratory UI/app work: verify on CT126, promote to CT121 only when solid.

7. Infra roles (one-line)

Surface Role
VPS Beacon + Cortex P0; public Explorer UI; Mail agent-first
NUC Cadence canonical (cadence_runtime_home=nuc_lab_controller); VPS Cadence = drift
Lab Proxmox Explorer lab SOT (CT121), sandboxes KEEP
Mac Files/docs only — mac_hosting=never; no local data hoarding

Session walkthrough (bootstrap → done)

  1. Ready probe — GET /ready must show status=ready, public_safe_mode=true, server-side redaction, no raw survey mount.
  2. Bootstrap — GET /api/ai/bootstrap. Read client_sequence, denied_surfaces_explained, stop_conditions, workflow_recipes, required_rules.
  3. This journey — confirm redaction, permissions, catalog-only, no local copies, promote path, sandbox stop, infra roles (above).
  4. Binding protocol — read governance protocol vNext (authority layers, doc kinds, wipe MUST NOTs, post-wipe order).
  5. Primary context — fetch each primary_context with accessible_to_session=true via /api/ai/context/{slug}. Require redaction packet fields.
  6. Capability map — before mutating any host/service/hardware, look up its card. Missing card ⇒ abort + feedback missing-context.
  7. Plan — write Product / Task / Authority / Done when. Refuse if authority is insufficient.
  8. Execute — only on the correct host/sandbox. Mac = files only. No DNS/TLS/firewall/public exposure without a separate runbook.
  9. Evidence — receipts/probes (pointers in catalog). Optional diary for lineage (never authority).
  10. Promote — durable truth to lab, then public; breadcrumb infra changes.
  11. Stop sandboxes you started or used.
  12. Feedback — signal only; dedup first; no secrets.
  13. Done — report blockers honestly; do not claim SOT without context 200.

Project patterns (pick the right kind)

Kind When Anti-pattern
runbook Another agent must reproduce exactly Diary-as-runbook
plan Forward intent with gates / done_when Plan as owner approval
evidence Proves a claim Secrets in body
diary Dated lineage only Citing diary as authority
feedback Friction / missing-context / QoL Treating feedback as a rule

Pick rule: Reproduce? → runbook. Intent? → plan. Happened? → evidence. Should change? → feedback, then promote if it becomes rule.

Stop conditions (abort immediately)

From bootstrap + protocol (non-exhaustive): redaction 422 you cannot fix without losing meaning; required context inaccessible for missing tags; temptation to touch denied surfaces; contradiction between catalog and task; hot-patch prod instead of sandbox; missing capability card on mutate; secrets about to enter catalog; wipe-adjacent work without owner stage; destroy or idle-run a KEEP sandbox; local hoarding of catalog/runtime/product data on Mac/agent workspace.

What success looks like

  • Rules were clear before action.
  • Only allowed AI endpoints were used.
  • Redaction policy was followed at write time.
  • Catalog context 200 for anything claimed as SOT.
  • Sandboxes stopped; nothing destroyed by default.
  • Evidence + optional feedback; no secrets in any published surface.