All procedures
runbookuai-explorerOperator truth

UAI Development Standards Runbook

Synced UAI Explorer runbook documentation from docs/runbooks/uai-development-standards.md.

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

UAI Development Standards Runbook

Created: 2026-06-21

Purpose

Give fresh AI agents and human contributors a practical development baseline before they touch UAI code, documentation, or lab services.

This runbook is intentionally small. Project-specific docs still win when they are cataloged in UAI Explorer and marked current.

Bootstrap Rule

When an agent is told to use UAI Explorer, it must:

  1. Verify /ready.
  2. Authenticate with a dedicated role=ai account.
  3. Call /api/ai/bootstrap.
  4. Fetch required primary_context entries marked accessible_to_session=true through /api/ai/context/{slug}.
  5. Follow the UAI rules, sandbox protocol, and project docs from those packets.

Do not make a fresh agent depend on a long prompt. The Explorer bootstrap packet is the contract. Use the bootstrap task_prompt_contract so a task prompt only needs product, task, authority, and done_when.

Language Lanes

Python

Use Python as the default UAI tooling lane for:

  • device surveys,
  • redaction workers,
  • catalog import and sync tools,
  • verification scripts,
  • data cleanup,
  • one-off operational probes,
  • tests around documentation and content pipelines.

Python tools should be explicit about dry-run versus apply behavior, write public-safe evidence, and fail closed when content looks secret-bearing.

Rust And Axum

Use Rust and Axum for service backends when project docs select that lane or when a new service needs a typed, compiled, low-footprint API.

Default expectations:

  • clear request and response types,
  • narrow handlers that delegate logic to testable modules,
  • structured errors without leaking private paths or credential values,
  • no secrets in logs,
  • integration tests for auth, authorization, and public-safe boundaries,
  • config through environment or secret stores, never committed files.

Do not infer a Rust/Axum architecture from memory. Read the project-specific Explorer docs first.

C++

Use C++ only where it is justified by performance, native integration, hardware-adjacent work, or an existing project standard.

Default expectations:

  • small ownership boundaries,
  • deterministic build instructions,
  • compiler warnings treated seriously,
  • tests or reproducible verification for unsafe or performance-sensitive code,
  • no secret values in fixtures, logs, or generated evidence.

If C++ is not clearly required, prefer the simpler project lane.

Sandbox First

Development work starts in the repo and the appropriate sandbox:

  • UAI Explorer staging: CT 126.
  • UAI Explorer production: CT 121, governed internal production only.
  • Other projects: use their own cataloged sandbox protocol or create one before risky work.

Do not use production containers for exploratory development. Do not change DNS, TLS, firewall, reverse proxy, NetBird, storage cleanup, node onboarding, or public exposure without a separate approved runbook.

Documentation Requirements

Every meaningful development change should leave enough context for the next agent:

  • update the relevant runbook when a workflow becomes repeatable,
  • update the diary for meaningful sessions,
  • catalog public-safe docs in UAI Explorer,
  • mark stale docs as superseded instead of deleting useful lineage,
  • keep raw and private docs out of Explorer until selected redaction and review.

AI Lane Requirements

AI workers must use the bounded AI lane:

  • uai_ready
  • uai_bootstrap
  • uai_list_ai_catalog
  • uai_get_ai_context
  • uai_submit_feedback with a product field when useful
  • optional local search over already returned catalog metadata

They must not expose generic shell, filesystem, admin, upload, database, raw download, or arbitrary HTTP proxy tools as part of the Explorer adapter.

Optional feedback is a UAI-wide product lane. Follow [REDACTED:high-entropy].md; feedback is append-only and no feedback means the current product lane works as-is.

Direct repo access is acceptable only for explicit local code, documentation, or verification assignments. Use Explorer for current UAI rules and lab context even during those local tasks.

Acceptance Check

A fresh agent is correctly synchronized when it can state:

  • the current production and sandbox boundaries,
  • the no-change exposure line,
  • which docs are required first reads,
  • which language lane applies to the requested project,
  • which catalog slugs it used,
  • audit IDs for fetched context,
  • which tests or readiness checks will prove the change.