boring-ui: Instructions file for Codex

Working here

Read README.md, INVARIANTS.md, PI-COMPLEMENT.md, SPEC.md, PRODUCT-REQUIREMENTS.md, ROADMAP.md and REDACTION.md first. Hub work also reads HUB-M1.md; UI/workspace work reads LEGACY-UI.md.

• This repo has partial runtime implementation and build/typecheck tooling. Read docs/contracts/SCAFFOLD.md and docs/implementation/PARTIAL.md for implemented behavior and remaining qualifications. Interface/native-smoke tests alone are not runtime qualification. Import native types rather than copying them.
• Keep decisions in their owning document; link rather than restate. Product requirements and the three reference applications are delivery targets, not optional polish.
• Apply BORING-PI-1..6. Pi owns execution/recovery; borrow the native Harness and preserve direct native APIs. Compose optional native features, never replace the kernel/default lifecycle. The host owns policy/data/budgets/credentials. No generic multi-engine facade, mandatory composition container or second registry/scheduler.
• One place for files: every file lives in a workspace (Pi FileSystem, plus exec when there is a shell), and every access goes through that workspace's single provider instance. "Published" is a mode of writing, not a location: the provider's conditional write (stale revision refused, operation id with lookup, history). Hosts differ only in where bytes live (disk/EFS, remote sandbox, SQLite); no mirror or sync between places. Reuse Pi's public FileSystem/Shell/ExecutionEnv; native tools never run over a dummy shell. Only conditional writes get receipts, never every scratch byte. Plan and owner: FILES-GIT-EXEC.md.
• Pi extension points first (BORING-PI-4). Duplicates of Pi are deleted, not renamed. Review checklist: "Which Pi extension point does this use? If none, why doesn't Pi cover it?"
• Views and lifecycles follow BORING-PI-6 and BORING-PI-2: closing a viewer must not stop a task or dispose another consumer's resource.
• Current hub owns control/composition; Factory/app Artifacts repos own development claims, approvals and release. Read the current owner map above the historical Hub M1 text. Business dispatch is not Pi scheduling or a fixed native task graph. Report cancellation intent separately from confirmed termination; preserve private payloads at their data-owning runtime. Missing public seams block only the guarantee requiring them, not unrelated native capability.
• Virtual workspace composes one view, just-bash and optional isomorphic-git; no native fallback or second remote checkout. Code mode reuses upstream pi-codemode with normal native registration, no Boring interpreter/VM recovery. Default canvas is tldraw.
• Runtime/frontend features are trusted host code; agent-written or generated code is never imported into a host process; agents may run code they wrote only through their conversation's ExecutionEnv, as SELF-EVOLUTION.md specifies. Registration/viewing cannot manufacture permission, durable decisions or commit evidence. Viewer human actions and native tool adapters share resource semantics, with browser-only commands target-bound.
• Preserve concrete controller types; do not erase flush/custom capabilities. Handle async owner teardown separately from sync unsubscribe. Keep native shell-only providers valid and concurrent cwd facades distinct.
• Keep the headless UI root free of files/Pi/agent imports; select optional resource/Pi subpaths deliberately. Use native tool/factory/watch contracts, not a second HostOperation or subscription model. Compose writer/lookup and acquisition/recovery separately. Boring callback contracts use function properties to avoid unsafe method bivariance. Validate isolated consumers, not only the monorepo.
• Change ARCHITECTURE.json before new packages/edges/dependencies. Native environment/resource type reuse is permitted where declared; no kernel or server FS in browser UI bundles (an opt-in agent worker bundle may run the unchanged kernel, see BORING-PI-5). Allowed package edges do not require pure adapter entry points to load agent implementations. Laws have one owner/index entry. Keep global VERIFY.json deferrals until their actual guarantees are proven; runtime packages also need test/packages/.test.mjs importing and exercising public output; no placeholder proof, duplicate law, private Pi import/fork/patch or relabelled legacy evidence.
• npm run verify:repo is the repository layout/reachability front door and is included in npm run check (therefore CI). Its one config is scripts/verify-repo.config.json: allowed top-level directories, explicit additional source roots for dynamically referenced browser shims, and warning-only line budgets. It checks package source reachability from declared exports and test imports; reuses the Pi boundary, registry block/cycle and feature-map owners instead of duplicating their rules. Size warnings are prompts for review, not failures. Package exports and deprecated registry compatibility items are not removed without a fresh boring-factory consumer search.
• Run npm run check, npm test and npm run verify before and after spec/tooling changes. Build/typecheck, native smoke and package-export tests now exist. Full lint/browser/provider/integration gates still land with their implementations, never as no-op scripts. Erased declarations need no behavior test; runtime packages require their own executed test entry. Global VERIFY.json deferrals are backlog, not release blockers (NPM-RELEASE); they do not block incremental package implementation.
• One integrating owner per cross-package contract. Task packets name revision, allowed edges, owned files, consumer tests and non-goals; builders use isolated worktrees and reviewed candidates. Behavior lands with tests, driven controls, records and a feature map. Raw evidence stays under ignored .cache/evidence/; separate static review, fake-model journeys, hard crashes and real-model judgment.
• Use fictional fixtures only. Never read/copy patient evals, credentials or licensed corpus into this repository. Never test against production or automate a person's own browser.
• Do not edit/sync consumer source, vendor, data or deployments as part of specification work. Consumer migration is separate issue/branch/PR work under that repository's instructions. A v4 compatibility requirement is not a claim that the hub is already fixed.
• Pin dependencies/references. Port v2 lifecycle/files/chat behavior and v3 viewer/shadcn recipes deliberately; retain licenses and replace obsolete runtime coupling. tldraw licensing/assets/CSS and vendor/egress guarantees need separate qualification. Keep full requested P01–P14/A01–A47 scope and additive current-hub A48 visible; the first composed fixture is not full release completion.
• Fail-first tests: a test added with a fix must be shown to fail on the pre-fix code and must drive the real path (the public entry point or native tool), not a direct call to a library; reviews check this.
• Feature map: features/README.md lists what the kit does, one file per feature with sub-feature IDs, where it lives and how to drive it. A change that adds or changes a feature updates its file in the same change (a new block, prop or behaviour gets an ID and a driving step); npm run check runs scripts/check-features.mjs. Skills under skills/ point to the map and do not repeat it.