mirror of https://github.com/mvschwarz/openrig.git synced 2026-10-02 08:35:15 +08:00

Files

T

Multi-host + Living Notes.

Multi-host foundation: shareable whole-topology staged spin-up brings
a rig topology up across multiple hosts in stages; VPS product-factory
multi-host hardening ships with rig host verbs (add / list / doctor,
capped at three; one built-in product-factory-vps posture, three-
valued per item); the transport posture is documented (ssh for pane
ops, http-bearer for daemon REST, no cross-transport fallback); the
For-You feed aggregates activity across every registered host; and
rig file moves files across the topology's registered hosts.

Living Notes: durable INTENT / PLAN / DELIVERED signal layer at
mission and slice altitude with agent authorship + timestamps; cheap
composer surfaces make it the first-class place agents record
decisions, plans, and delivered work; the one-structure review
contract reads left-to-right as a single vertical stack (INTENT above,
PLAN + mockup in the middle, DELIVERED with paired proof at the
bottom); a plan change deletes the old plan and writes a new one -
never demotes or stacks multiple competing plans.

Operationalize the SDLC control plane: conventions SSOT ships in
source at docs/reference/sdlc-conventions.md (Living Notes UI section
names, proof-contract format + plannedRef mockup pairing, staged-
approval locks, C1 proof header + closed sets, three role contracts,
curation rule, elastic-middle doctrine, advisory fail-open audit
posture); rig scope slice create scaffolds the convention sections +
proof + PROOF.md + an IMPLEMENTATION-PRD.md skeleton for every
template kind; rig scope audit + rig workspace doctor gain sdlc-
convention advisories (records-and-advises, gates on HIGH only); the
mission-slice-sop skill ships in canonical source with byte-parity
guard; rig proof / rig scope slice create / rig scope slice approve
help + cli-reference teach the SDLC flow.

BREAKING: rig ps default flips to consolidated all-active-rigs
compact projection (the v0.4.0 current-rig-only default is retired -
it hid running rigs from the operator's field of view). --json is
scope-not-shape (still a bare array with existing per-entry keys;
scope widens to all non-archived rigs including stopped ones; one-line
migration for the old fleet firehose: rig ps --nodes -A --full).
-A / --all-rigs keeps exactly ONE meaning (the --nodes fleet widener;
bare -A is a structured teaching error). --nodes names its scope
everywhere (session default local-only; --host <id> --nodes requires
--rig or -A; multi-host fan-out is rollup-only by default; the
explicit ladder --all-hosts --nodes -A --full fans out per-node with
hostId-stamped projected rows). --all-hosts / --hosts --json emits the
shared AggregatedPayload (items + hosts with closed-enum statuses:
ok | unreachable | unsupported-transport | auth-failed).

Operator UX: agent altitude coordination panel scopes multi-agent
state to the right altitude (workspace / mission / slice) so the
coordination surface reads without per-seat drowning; composes with
the workspace observability tabs from 0.4.1. Docs closeout catches
docs/as-built/architecture.md, docs/as-built/cli-reference.md, and
the codemaps up to shipped state.

Migrations: additive only. Existing v0.4.3 databases upgrade by
running rig daemon start.

Behavior change (rig ps default view): the compact all-active-rigs
projection replaces the current-rig-only default. If your call sites
relied on the v0.4.3 default shape, add --full for the rich per-node
projection or --rig <name> for the prior scope.

Public-safety scrub applied inline to packages/ui/twin/corrective/
fixtures-corrective.ts (one demo-fixture role identifier neutralized
to the demo-namespace baseline established at 0.4.1).

See CHANGELOG.md and docs/releases/v0.4.4.md.

2026-07-06 01:20:09 -07:00

7.8 KiB

Raw Permalink Blame History

kind, title, status, topics, domains, applies-when, siblings, prerequisite-reads, last-verified-against-source, last-updated

kind title status topics domains applies-when siblings prerequisite-reads last-verified-against-source last-updated

as-built

As-Built Docs — Map of Territory + Module Index

active

knowledge-and-context

observability

engineering-advisor

operating-advisor

product-advisor

Starting any technical task that needs the shipped OpenRig system as it actually is. Read this first to learn what the as-built tree contains and which module to open; then go to codemap.md for use-case navigation or straight to the named module.

codemap.md

cli-reference.md

frontmatter-schema.md

7eaf524c

2026-05-16

OpenRig As-Built Docs

OpenRig is a local control plane for multi-agent coding topologies — a multi-agent harness that manages your Claude Code and Codex sessions as a single system, with a daemon (@openrig/daemon), a CLI (@openrig/cli), a UI (@openrig/ui), and an MCP server all sitting on one SQLite-backed core. This tree is the source-verified description of that system as it actually ships — every load-bearing claim is grounded to packages/*/src at a named commit, not to memory, chat, or older docs.

Verified against source at HEAD 7eaf524c (git describe → v0.3.1-6-g7eaf524c). Package version is 0.3.1 across all three packages; HEAD carries 6 commits of unreleased 0.3.2 work, no v0.3.2 tag.

How this tree is organized

The as-built corpus was modularized (slice 08, context-architecture-v1) from two monolithic files into a folder of thematic modules, each independently loadable, each frontmatter-tagged for retrieval, each ≤300 lines (author-mode modules with no prior prose may run to ≤400 — see the slice-08 ACK).

docs/as-built/
├── README.md            ← you are here: map-of-territory + index
├── codemap.md           ← navigation index (use-case lookup, source-root pointers)
├── frontmatter-schema.md← the frontmatter convention these docs follow
├── cli-reference.md     ← full rig CLI surface (kept whole)
├── architecture/        ← 14 backend/runtime modules
└── ui/                  ← 4 operator-surface modules

docs/DESIGN.md (the canonical visual / brand / design-system spec) stays at the repo docs/ root by design — it is referenced by many existing docs/DESIGN.md paths and carries no source drift. This tree points at it (see ui/library-specs-and-design-system.md); it is not copied here.

Module index

`architecture/` — backend, daemon, runtime

Module	What it covers
daemon-core.md	How the daemon boots, `createDaemon` wiring, the SQLite schema/40-migration set, the route-mount surface.
adapters-and-runtimes.md	The five-method RuntimeAdapter contract, the Claude/Codex/Terminal adapters (launch/resume/fork in tmux), and the resume-honesty layer (honest resumed-vs-fresh assessment).
coordination-primitive.md	PL-004 Phase A stream/queue/inbox/outbox; the hot-potato closure contract; where queue closure is enforced.
workflow-runtime.md	PL-004 Phase D Workflow Runtime — spec cache, instance state, step trails, transactional-scribe projection, watchdog policies.
mission-control.md	PL-005 queue-observability surface — seven views, seven write verbs, action audit, bearer-token middleware.
agent-spec-and-startup.md	AgentSpec/RigSpec types, profile resolution, additive startup layering, StartupOrchestrator, whoami/materialize/bind/adopt identity.
lifecycle-snapshot-restore.md	Snapshot capture, honest restore (resume vs rebuild vs fresh), restore-honesty enforcement, restore-check / restore-packet probes.
transport-and-transcripts.md	rig send/capture/broadcast over tmux, pipe-pane transcript capture + search, durable SQLite chat, `rig ask`, MCP-name vs tmux-key distinction.
workspace-primitive.md	The PL-007 typed workspace declaration (root/repos/defaultRepo/knowledgeRoot), migrations 038/039, per-item repo-scope gating, file-backed missions/slices indexing.
content-surfaces.md	The operator-allowlisted file browser, atomic conflict-checked writes + JSONL edit audit, PROGRESS.md tree indexer, the one-screen Steering composer.
living-notes-review.md	v0.4.4 — the Living Notes review surface: the ONE `ComposedSliceReview` (intent→plan→delivered) projection, pure composer + gatherer, staged-approval locks, C1-bound `verified`, `/api/review/*` routes, freeze export, ranged media serving, and the SDLC on-disk convention it projects.
plugin-agent-image-context-pack.md	The filesystem-canonical content layer — plugin discovery, agent images, context packs, the Claude auto-compaction policy enforcer.
packaging-bootstrap-bundles.md	Bundle assembly (schema-v2 pod bundles + legacy v1), bundle create/inspect/install + `/api/up`, the staged BootstrapOrchestrator, legacy install seams.
architecture-rules-and-event-system.md	The cross-cutting invariants — the 25 architecture rules, the RigEvent union + SSE delivery, intentional compatibility limits.

`ui/` — operator surfaces

Module	What it covers
shell-and-routing.md	The UI shell (rail / Explorer / center workspace / drawer / preview stack), the actual route tree the shipped UI mounts, the shared detail drawer + event consumption.
topology.md	The topology surface — host hybrid graph, table/terminal views, activity-ring / hot-potato visual language, terminal-preview popovers, navigation/overlay contracts.
project-and-for-you.md	The operator destination surfaces — the For-You attention feed (5-card classifier + verb actions), the Project workspace/mission/slice scope pages, the Dashboard landing on the vellum brand system.
library-specs-and-design-system.md	The Library (`/specs`) UI — specs/skills/plugins/agent-images surfaces, the spec-review + spec-library + live-identity flows, the design-system pointer.

Root docs

Doc	What it covers
codemap.md	Navigation index — module map, structural relationship diagram, fast-lookup-by-use-case, source-root pointer table. Start here when you know what you need but not which module.
cli-reference.md	The full `rig` CLI surface — command groups, subcommands, flags, JSON output, cross-host, coordination primitives. Kept as one doc (slice-08 Q4).
frontmatter-schema.md	Which frontmatter convention governs every doc in this tree, plus the one as-built-unique field (`last-verified-against-source`).
`../DESIGN.md`	The canonical visual / brand / design-system spec (lives at `docs/` root by design; pointer only — not duplicated here).

Source-grounding contract

Every module declares last-verified-against-source: <commit-sha> — the commit its claims were checked against. Load-bearing corrections are recorded inline with an auditable annotation (> Drift-fix Dx — said X; corrected to Y; slice-00 §z; re-confirmed <file:line> @HEAD). OPEN items (counts that are definitional or runtime-only) are carried verbatim, never smoothed. The schema is defined in frontmatter-schema.md and the governing convention is openrig-work/conventions/frontmatter-for-context/.

7.8 KiB Raw Permalink Blame History