feat: migrate docs to docusaurus v3 hub

.github/workflows/docs-ci.yml

@@ -0,0 +1,53 @@
+name: docs-ci
+
+on:
+  push:
+    branches: [main, feat/docs-docusaurus-v3]
+  pull_request:
+    branches: [main, feat/docs-docusaurus-v3]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs
+        run: npm run build
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-build
+          path: build
+
+      - name: Deploy preview to GitHub Pages
+        if: github.event_name == 'pull_request'
+        run: npx gh-pages -d build -b gh-pages --repo https://github.com/${{ github.repository }} --silent --message "docs preview $GITHUB_SHA" --add
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Comment preview URL
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const previewUrl = `https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/`;
+            const body = `🚀 Docs preview ready: ${previewUrl}`;
+            await github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body,
+            });

agent-catalog/agents.yaml

@@ -0,0 +1,34 @@
+- id: atlas
+  name: Atlas
+  pack: finance
+  role: Deployment & Ops Engineer
+  description: Coordinates deployments, verifies rollouts, and bridges observability signals back to Prism Console.
+  approvals:
+    - type: human
+      description: Requires operator sign-off for production rollouts
+  traits:
+    - reliability-first
+    - infra-aware
+  inputs:
+    - deployments queue
+    - service registry
+  outputs:
+    - roadchain events
+    - incident signals
+- id: lumen
+  name: Lumen
+  pack: education
+  role: Learning Experience Designer
+  description: Drafts course outlines, tracks learner signals, and routes interventions to instructors.
+  approvals:
+    - type: policy
+      description: Auto-approves drafts; escalates published curricula for human review
+  traits:
+    - empathetic
+    - rubric-driven
+  inputs:
+    - learner milestones
+    - content repository
+  outputs:
+    - lesson plans
+    - audit-ready rubrics

docs/agent-catalog/org-chart.mdx

@@ -0,0 +1,14 @@
+---
+id: agent-org-chart
+title: Agent Org Chart
+sidebar_position: 2
+---
+
+```mermaid
+graph TD
+  root[Agent Catalog]
+  root --> pack_finance[finance pack]
+  pack_finance --> atlas(atlas)
+  root --> pack_education[education pack]
+  pack_education --> lumen(lumen)
+```

docs/agent-catalog/overview.mdx

@@ -0,0 +1,14 @@
+---
+id: agent-catalog-overview
+title: Agent Catalog & Roles
+sidebar_position: 1
+slug: /agent-catalog/overview
+---
+
+The agent catalog is generated from `agent-catalog/agents.yaml` during the docs build. Each agent page lists capabilities, approvals, inputs, and evidence expectations so operators know how to deploy it safely.
+
+- **Where to edit:** Update `agent-catalog/agents.yaml` and rerun `yarn build:catalog`.
+- **Output:** MDX pages in `docs/agents/` and a Mermaid org chart in `docs/org-chart.mmd`.
+- **Search:** Agent IDs, pack names, and role keywords are added to Algolia metadata for discovery.
+
+Use the generated catalog to align runtime policy, access, and release notes across the organization.

docs/agents/atlas.mdx

@@ -0,0 +1,33 @@
+---
+id: agent-atlas
+title: Atlas — Deployment & Ops Engineer
+sidebar_position: 1
+keywords:
+  - atlas
+  - Atlas
+  - finance
+---
+Coordinates deployments, verifies rollouts, and bridges observability signals back to Prism Console.
+
+**Pack:** finance
+
+## Persona
+- **Role:** Deployment & Ops Engineer
+- **Capabilities:** Coordinates deployments, verifies rollouts, and bridges observability signals back to Prism Console.
+
+## Approval gates
+| Type | Description |
+| --- | --- |
+| human | Requires operator sign-off for production rollouts |
+
+## Traits
+- reliability-first
+- infra-aware
+
+## Inputs
+- deployments queue
+- service registry
+
+## Outputs
+- roadchain events
+- incident signals

docs/agents/lumen.mdx

@@ -0,0 +1,33 @@
+---
+id: agent-lumen
+title: Lumen — Learning Experience Designer
+sidebar_position: 2
+keywords:
+  - lumen
+  - Lumen
+  - education
+---
+Drafts course outlines, tracks learner signals, and routes interventions to instructors.
+
+**Pack:** education
+
+## Persona
+- **Role:** Learning Experience Designer
+- **Capabilities:** Drafts course outlines, tracks learner signals, and routes interventions to instructors.
+
+## Approval gates
+| Type | Description |
+| --- | --- |
+| policy | Auto-approves drafts; escalates published curricula for human review |
+
+## Traits
+- empathetic
+- rubric-driven
+
+## Inputs
+- learner milestones
+- content repository
+
+## Outputs
+- lesson plans
+- audit-ready rubrics

docs/getting-started/faq.mdx

@@ -0,0 +1,54 @@
+---
+id: faq
+title: FAQ
+sidebar_position: 3
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Use this FAQ when onboarding teammates. It highlights answers that commonly come up while running BlackRoad OS locally or in shared environments.
+
+## How do I install dependencies?
+
+- Use Node 20+ and `npm install` from this repo to pull docs dependencies.
+- Development repos such as `blackroad-os-core` and `blackroad-os-operator` also target Node 20+. Install Docker and Terraform if you plan to run infra workflows.
+
+## Which repo do I run first?
+
+1. Start the Operator runtime so agents can register and emit events.
+2. Launch `blackroad-os-api` to expose metrics and task orchestration endpoints.
+3. Bring up Prism Console for observability.
+4. Optionally start packs (Finance, Education) to exercise specific playbooks.
+
+## Where do configuration values live?
+
+Most services load environment variables from `.env` files. Secrets should be managed through your vault of choice; do **not** check them into Git. Docs-specific settings (Algolia, API sources) are read from `process.env` during build.
+
+## How do I add a new document?
+
+Place the MDX file under the relevant top-level folder (Getting Started, Platform Guides, Packs, Reference, Governance & Policy). The sidebar is autogenerated from directories, so the file will appear automatically.
+
+## What if I hit a broken link?
+
+The docs CI workflow fails the build on broken links. Run `yarn build` locally to surface issues before pushing.
+
+## How are agents documented?
+
+Agent pages are generated from `agent-catalog/agents.yaml` during the build. Update that file and rerun `yarn build` (or `yarn build:catalog`) to regenerate docs.
+
+## Is there a dark/light mode toggle?
+
+Yes. The site defaults to dark mode but offers a toggle in the header if you prefer light mode.
+
+<Tabs>
+  <TabItem value="resources" label="Fast references">
+    - Platform: `/platform/core/overview`
+    - Operator runtime: `/platform/operator/runtime`
+    - Prism Console: `/platform/prism-console/overview`
+  </TabItem>
+  <TabItem value="support" label="Need help?">
+    - Open an issue in `blackroad-os-docs` for docs-specific problems.
+    - Use the operator pager channel for runtime incidents.
+  </TabItem>
+</Tabs>

docs/getting-started/quick-start.mdx

@@ -1,4 +1,8 @@
-# Getting Started
+---
+id: quick-start
+title: Quick Start
+sidebar_position: 1
+---
 
 This guide is for developers and curious operators who want to explore the BlackRoad OS ecosystem locally. It summarizes the repos you will touch, the tooling you need, and a straightforward path to spin up the most important services. Expect rapid iteration: the stack favors composability so you can replace stubs with production-grade agents as they become available.
 
@@ -34,4 +38,4 @@ Environment variables differ per service, but a common pattern is `PORT=xxxx` al
 
 ## Where to go next
 
-After you have the basics running, read the [Architecture Overview](architecture/overview.md) to understand how components talk to each other, then jump to the [Finance Layer](architecture/finance-layer.md) for agent-specific behavior. For deployment considerations and domain names, see [Infra Environments](infra/environments.md) and [DNS & Networking](infra/dns-and-networking.md). When you want to extend the platform, the [Extending Agents](dev/extending-agents.md) guide walks through adding new automation safely.
+After you have the basics running, read the [Architecture Overview](/reference/architecture/overview) to understand how components talk to each other, then jump to the [Finance Layer](/packs/finance/finance-layer) for agent-specific behavior. For deployment considerations and domain names, see [Infra Environments](/platform/operator/environments) and [DNS & Networking](/platform/operator/dns-and-networking). When you want to extend the platform, the [Extending Agents](/platform/api/extending-agents) guide walks through adding new automation safely.

docs/getting-started/welcome.mdx

@@ -1,9 +1,13 @@
-# Welcome to BlackRoad OS
+---
+id: welcome
+title: Welcome to BlackRoad OS
+sidebar_position: 2
+---
 
 BlackRoad OS is an AI-first operating system that lets one human orchestrator direct thousands of specialized agents with cryptographic audit trails and built-in compliance for highly regulated industries. The platform is intentionally opinionated so operators, engineers, and auditors can share a common map of how work flows, what evidence is captured, and where human approvals sit in the loop. If you are new to the ecosystem, start here before diving into code or running services locally.
 
 This handbook is the central place to learn how the ecosystem fits together. It connects architectural blueprints, developer workflows, operational runbooks, and the regulated story that underpins every release. Each section is designed to be approachable on its own while pointing you to deeper references when you want to build or extend the system.
 
-If you want the ten-thousand-foot view of components and data flow, jump to the [Architecture Overview](architecture/overview.md). When you are ready to try things locally, begin with [Getting Started](getting-started.md) for prerequisites, repo layout, and the minimal stack to boot. Operators and administrators can explore the [Prism Console](ops/prism-console.md) chapter to understand dashboards and configuration knobs. Finance leaders and engineers should read the [Finance Layer](architecture/finance-layer.md) to see how ledgering, forecasting, and treasury automation are mapped into agents and orchestrators.
+If you want the ten-thousand-foot view of components and data flow, jump to the [Architecture Overview](/reference/architecture/overview). When you are ready to try things locally, begin with [Getting Started](/getting-started/quick-start) for prerequisites, repo layout, and the minimal stack to boot. Operators and administrators can explore the [Prism Console](/platform/prism-console/overview) chapter to understand dashboards and configuration knobs. Finance leaders and engineers should read the [Finance Layer](/packs/finance/finance-layer) to see how ledgering, forecasting, and treasury automation are mapped into agents and orchestrators.
 
 The docs are intentionally iterative. TODO: add deeper API examples, event schemas, and RoadChain cryptography notes as the platform hardens. Until then, expect a balance of conceptual framing and practical steps so you can contribute without waiting for formal standards.

docs/governance-policy/audit-and-journaling.mdx

@@ -1,4 +1,8 @@
-# Audit & Journaling
+---
+id: audit-and-journaling
+title: Audit & Journaling
+sidebar_position: 2
+---
 
 Auditors need to answer who did what, when, and why. BlackRoad OS provides hooks for every significant action to be journaled via PS-SHA∞, creating a tamper-evident trail. This page explains the intent; it is not a formal compliance assertion.
 

docs/governance-policy/incident-response.mdx

@@ -1,4 +1,8 @@
-# Incidents & Incident Response
+---
+id: incident-response
+title: Incidents & Incident Response
+sidebar_position: 3
+---
 
 BlackRoad OS treats incidents as shared responsibilities between agents and humans. Automation accelerates detection and containment, while humans provide judgment and regulatory context. This page outlines the flow and points you to infra runbooks for detailed procedures.
 
@@ -16,4 +20,4 @@ Common responses include rolling back a deployment, disabling a capability, or a
 
 ## Postmortem
 
-After stabilization, capture a postmortem that includes timeline, root causes, and prevention steps. Link journal entries and event IDs so auditors can replay the sequence. Update runbooks and agent policies to prevent recurrence, and communicate findings to stakeholders who rely on the [Finance Layer](../architecture/finance-layer.md) or other critical workflows.
+After stabilization, capture a postmortem that includes timeline, root causes, and prevention steps. Link journal entries and event IDs so auditors can replay the sequence. Update runbooks and agent policies to prevent recurrence, and communicate findings to stakeholders who rely on the [Finance Layer](/packs/finance/finance-layer) or other critical workflows.

docs/governance-policy/regulatory-overview.mdx

@@ -1,4 +1,8 @@
-# Regulated Overview
+---
+id: regulatory-overview
+title: Regulated Overview
+sidebar_position: 1
+---
 
 BlackRoad OS is built for organizations that operate in regulated industries. The platform emphasizes clear journaling, explicit human approval gates, and separation of duties so automation can coexist with oversight. This document is informational and does not constitute legal advice.
 
@@ -14,4 +18,4 @@ Regulated stakeholders such as CFOs, General Counsels, and Chief Compliance Offi
 
 ## Next steps
 
-Dive into [Audit & Journaling](audit-and-journaling.md) for the cryptographic story or explore the [Finance Layer](../architecture/finance-layer.md) to see how policies surface in day-to-day workflows. TODO: add mappings to specific regulations as implementations mature.
+Dive into [Audit & Journaling](/governance-policy/audit-and-journaling) for the cryptographic story or explore the [Finance Layer](/packs/finance/finance-layer) to see how policies surface in day-to-day workflows. TODO: add mappings to specific regulations as implementations mature.

docs/index.md

@@ -1,34 +0,0 @@
----
-id: docs-home
-title: BlackRoad OS Docs Home
-slug: /
----
-
-BlackRoad OS is an orchestration operating system that lets a single human orchestrator direct agents and services with verifiable evidence. It anchors work to PS-SHA∞ identities, runs verification pipelines for truth states, journals everything through RoadChain, and surfaces system health through Prism Console and the public web shell. The platform lives across multiple repositories but speaks one architectural language.
-
-This hub participates in the shared **"BlackRoad OS - Master Orchestration"** project and is the canonical place to understand how the stack fits together, how to operate it, and why it exists.
-
-## Choose your path
-
-### Operate the OS
-- [Prism Console](ops/prism-console) — cockpit for system status, agents, finance, and events.
-- [Infra Guide](ops/infra-guide) — how environments, DNS, and deployments hang together.
-- [Operator Runtime](ops/operator-runtime) — how agents run and emit events.
-
-### Build on the OS
-- [Core Primitives](dev/core-primitives) — domain models, identities, truth pipeline, and jobs.
-- [API Overview](dev/api-overview) — HTTP surface exposed by `blackroad-os-api`.
-- [Agents: Atlas and Friends](dev/agents-atlas-and-friends) — how agents register, identify, and report state.
-- [Events and RoadChain](dev/events-and-roadchain) — journaling, blocks, and how the explorer will work.
-
-### Understand the Why
-- [Pain Points Summary](business/pain-points) — problems BlackRoad OS is built to solve.
-- [Value Proposition](business/value-proposition) — benefits for creators, teams, and partners.
-- [Seasons Overview](overview/seasons) — how the roadmap is structured.
-
-## Quick orientation
-- [BlackRoad OS Overview](overview/blackroad-os-overview) — the layered picture from identity to interface.
-- [Stack Map](overview/stack-map) — repositories mapped to layers and status.
-- [Getting Started](getting-started) — run the docs locally and clone the stack.
-
-BlackRoad OS is designed to stay honest about its current state. Pages mark components as planned, alpha, or in-flight so operators, developers, and partners know where to invest. Feedback and contributions are welcome—iterate with small, linked docs instead of monolithic walls of text.

docs/index.mdx

@@ -0,0 +1,47 @@
+---
+id: docs-home
+title: BlackRoad OS Docs Home
+slug: /
+---
+
+BlackRoad OS is an orchestration operating system that lets a single human orchestrator direct agents and services with verifiable evidence. It anchors work to PS-SHA∞ identities, runs verification pipelines for truth states, journals everything through RoadChain, and surfaces system health through Prism Console and the public web shell. The platform lives across multiple repositories but speaks one architectural language.
+
+This hub participates in the shared **"BlackRoad OS - Master Orchestration"** project and is the canonical place to understand how the stack fits together, how to operate it, and why it exists.
+
+## Choose your path
+
+### Getting Started
+- [Quick Start](/getting-started/quick-start) — run the docs locally and tour the repos.
+- [FAQ](/getting-started/faq) — unblock common onboarding questions.
+
+### Platform Guides
+- [Core Overview](/platform/core/overview) — stack map, seasons, and primitives.
+- [API Overview](/platform/api/overview) — HTTP surface exposed by `blackroad-os-api`.
+- [Operator Runtime](/platform/operator/runtime) — how agents run and emit events.
+- [Prism Console](/platform/prism-console/overview) — cockpit for system status, agents, finance, and events.
+
+### Agent Catalog & Roles
+- Generated from `agent-catalog/agents.yaml` at build time so every persona stays in sync.
+- Visual org chart lives at `/org-chart` and updates with each catalog change.
+
+### Packs
+- [Finance pack](/packs/finance/overview) — treasury and billing automation with PS-SHA∞ evidence.
+- [Education pack](/packs/education/overview) — learning workflows tailored for compliance-heavy orgs.
+
+### Reference
+- [OpenAPI](/reference/openapi) — rendered via Redoc from `blackroad-os-api`.
+- [CLI](/reference/cli) — docs hub commands and environment variables.
+- [Agents: Atlas and Friends](/platform/core/agents-atlas-and-friends) — how agents register, identify, and report state.
+- [Events and RoadChain](/platform/core/events-and-roadchain) — journaling, blocks, and how the explorer will work.
+
+### Understand the Why
+- [Pain Points Summary](/packs/finance/pain-points) — problems BlackRoad OS is built to solve.
+- [Value Proposition](/packs/finance/value-proposition) — benefits for creators, teams, and partners.
+- [Seasons Overview](/platform/core/seasons) — how the roadmap is structured.
+
+## Quick orientation
+- [BlackRoad OS Overview](/platform/core/overview) — the layered picture from identity to interface.
+- [Stack Map](/platform/core/stack-map) — repositories mapped to layers and status.
+- [Getting Started](/getting-started/quick-start) — run the docs locally and clone the stack.
+
+BlackRoad OS is designed to stay honest about its current state. Pages mark components as planned, alpha, or in-flight so operators, developers, and partners know where to invest. Feedback and contributions are welcome—iterate with small, linked docs instead of monolithic walls of text.

docs/meta/doc-index.json

@@ -1,16 +1,16 @@
 {
   "docs_home": "/",
-  "overview_blackroad_os": "/overview/blackroad-os-overview",
+  "overview_blackroad_os": "/platform/core/overview",
-  "overview_stack_map": "/overview/stack-map",
+  "overview_stack_map": "/platform/core/stack-map",
-  "overview_seasons": "/overview/seasons",
+  "overview_seasons": "/platform/core/seasons",
-  "getting_started": "/getting-started",
+  "getting_started": "/getting-started/quick-start",
-  "core_primitives": "/dev/core-primitives",
+  "core_primitives": "/platform/core/primitives",
-  "api_overview": "/dev/api-overview",
+  "api_overview": "/platform/api/overview",
-  "agents_atlas": "/dev/agents-atlas-and-friends",
+  "agents_atlas": "/platform/core/agents-atlas-and-friends",
-  "events_and_roadchain": "/dev/events-and-roadchain",
+  "events_and_roadchain": "/platform/core/events-and-roadchain",
-  "prism_console": "/ops/prism-console",
+  "prism_console": "/platform/prism-console/overview",
-  "operator_runtime": "/ops/operator-runtime",
+  "operator_runtime": "/platform/operator/runtime",
-  "infra_guide": "/ops/infra-guide",
+  "infra_guide": "/platform/operator/infra-guide",
   "glossary": "/meta/glossary",
   "architecture_decisions": "/meta/architecture-decisions",
   "master_codex_prompt": "/meta/master-codex-prompt"

docs/org-chart.mmd

@@ -0,0 +1,6 @@
+graph TD
+  root[Agent Catalog]
+  root --> pack_finance[finance pack]
+  pack_finance --> atlas(atlas)
+  root --> pack_education[education pack]
+  pack_education --> lumen(lumen)

docs/packs/education/overview.mdx

@@ -0,0 +1,26 @@
+---
+id: education-pack-overview
+title: Education Pack Overview
+sidebar_position: 1
+slug: /packs/education/overview
+---
+
+The Education pack targets learning, onboarding, and knowledge-ops workflows. Use it as a template for launching new packs that expose curated agents and policies.
+
+## Included capabilities
+
+- Lesson planning and content review agents tailored for compliance-sensitive orgs.
+- Rubrics that translate PS-SHA∞ anchored observations into course-level evidence.
+- Prism Console dashboards focused on learner outcomes and instructor interventions.
+
+## Adding new education personas
+
+1. Add agent entries to `agent-catalog/agents.yaml` with `pack: education`.
+2. Run `yarn build:catalog` to generate MDX pages under `docs/agents/`.
+3. Link the generated pages from this pack overview or downstream playbooks.
+
+## Launch checklist
+
+- Validate integration against `blackroad-os-api` using the Reference section.
+- Confirm audit signals flow into PS-SHA∞ for each learning job.
+- Publish a short announcement in the Packs nav so operators know what changed.

docs/packs/finance/finance-layer.mdx

@@ -1,4 +1,9 @@
-# Finance Layer
+---
+id: finance-layer
+title: Finance Layer
+sidebar_position: 3
+slug: /packs/finance/finance-layer
+---
 
 The finance layer is composed of eight core agents that mirror traditional controllership and treasury functions. Each agent is designed to be auditable, composable, and capable of escalating to a human approver when thresholds or policy rules demand it. Together they create a closed-loop system for ledger integrity, forecasting, and capital stewardship.
 

docs/packs/finance/overview.mdx

@@ -0,0 +1,26 @@
+---
+id: finance-pack-overview
+title: Finance Pack Overview
+sidebar_position: 0
+slug: /packs/finance/overview
+---
+
+The Finance pack bundles treasury, invoicing, and reconciliation agents that speak the same PS-SHA∞ evidence language. It aligns with CFO and audit expectations while remaining composable.
+
+## Core personas
+
+- **Treasury coordinator** — reconciles cash positions, generates liquidity alerts, and triggers compliance checks.
+- **Billing agent** — issues invoices, tracks receipts, and posts updates to RoadChain for downstream reporting.
+- **Risk analyst** — watches event streams for anomalies and routes incidents to humans.
+
+## Operating guidance
+
+- Deploy alongside `blackroad-os-operator` to keep finance jobs near the event bus.
+- Surface pack metrics in Prism Console using the Finance dashboards.
+- Keep secrets and API tokens in your vault; bind them to agents via environment variables at runtime.
+
+## Extending the pack
+
+1. Add new finance agents to `agent-catalog/agents.yaml` with `pack: finance`.
+2. Include policies in `docs/governance-policy` when they impact approvals or segregation of duties.
+3. Update this overview with links to the generated agent pages.

docs/packs/finance/pain-points.mdx

@@ -1,7 +1,8 @@
 ---
-id: business-pain-points
+id: finance-pain-points
 title: Pain Points Summary
-slug: /business/pain-points
+slug: /packs/finance/pain-points
+sidebar_position: 2
 ---
 
 BlackRoad OS targets the friction that comes from fragmented tooling, unverifiable automation, and opaque ROI. Use these talking points when aligning stakeholders or writing proposals.

docs/packs/finance/value-proposition.mdx

@@ -1,7 +1,8 @@
 ---
-id: business-value-proposition
+id: finance-value-proposition
 title: Value Proposition
-slug: /business/value-proposition
+slug: /packs/finance/value-proposition
+sidebar_position: 1
 ---
 
 BlackRoad OS is an orchestration platform—not just another AI tool. It fuses identity, auditability, and operational clarity so automation can be trusted and measured.

docs/platform-guides/api/api-overview.mdx

@@ -1,7 +1,8 @@
 ---
-id: dev-api-overview
+id: api-overview
 title: API Overview
-slug: /dev/api-overview
+slug: /platform/api/overview
+sidebar_position: 1
 ---
 
 `blackroad-os-api` is the HTTP surface that external consumers, Prism Console, and automation call. It wraps Operator runtime data in a consistent envelope.

docs/platform-guides/api/extending-agents.mdx

@@ -1,4 +1,9 @@
-# Extending Agents
+---
+id: api-extending-agents
+title: Extending Agents
+slug: /platform/api/extending-agents
+sidebar_position: 2
+---
 
 Adding a new agent to BlackRoad OS follows a predictable path so capabilities stay discoverable and auditable. Start with a clear problem statement, then wire the agent into the operator with the right journaling and escalation points.
 
@@ -20,7 +25,7 @@ Update orchestrators to dispatch tasks to the new capabilities. Ensure event bus
 
 ## Testing and docs
 
-Add unit and integration tests that validate capability behavior, journaling, and escalation triggers. Document assumptions, inputs, and outputs in the operator repo, then cross-link from this docs site. For examples, see the finance agents described in the [Finance Layer](../architecture/finance-layer.md).
+Add unit and integration tests that validate capability behavior, journaling, and escalation triggers. Document assumptions, inputs, and outputs in the operator repo, then cross-link from this docs site. For examples, see the finance agents described in the [Finance Layer](/packs/finance/finance-layer).
 
 ## Example: Notification Agent
 
@@ -29,4 +34,4 @@ A simple Notification Agent might watch for anomalies and send alerts:
 1. Define a `notify` capability in the registry with inputs for subject, body, and recipients.
 2. Implement the agent to format messages and post to email or chat systems, emitting journal entries for traceability.
 3. Add orchestration rules to throttle or escalate when alerts relate to regulated actions.
-4. Document configuration knobs and link them from [Local Development](local-development.md) so others can reproduce behavior.
+4. Document configuration knobs and link them from [Local Development](/platform/core/local-development) so others can reproduce behavior.

docs/platform-guides/core/agents-atlas-and-friends.mdx

@@ -1,7 +1,8 @@
 ---
-id: dev-agents-atlas-and-friends
+id: agents-atlas-and-friends
 title: Agents – Atlas and Friends
-slug: /dev/agents-atlas-and-friends
+slug: /platform/core/agents-atlas-and-friends
+sidebar_position: 6
 ---
 
 Agents are the workers inside BlackRoad OS. Each agent is registered in Operator, anchored with PS-SHA∞ identity data, and consumes jobs through a shared contract defined in `blackroad-os-core`.

docs/platform-guides/core/core-primitives.mdx

@@ -1,7 +1,8 @@
 ---
-id: dev-core-primitives
+id: core-primitives
 title: Core Primitives
-slug: /dev/core-primitives
+slug: /platform/core/primitives
+sidebar_position: 4
 ---
 
 `blackroad-os-core` holds the shared types and helpers that every other repository uses. Keep these primitives stable: they shape how agents, jobs, events, and truth states are expressed everywhere else.

docs/platform-guides/core/events-and-roadchain.mdx

@@ -1,7 +1,8 @@
 ---
-id: dev-events-and-roadchain
+id: events-and-roadchain
 title: Events and RoadChain
-slug: /dev/events-and-roadchain
+slug: /platform/core/events-and-roadchain
+sidebar_position: 5
 ---
 
 Events are the connective tissue of BlackRoad OS. They describe what happened, when, and which identities were involved. RoadChain turns those events into an auditable, hash-linked journal.

docs/platform-guides/core/local-development.mdx

@@ -1,4 +1,9 @@
-# Local Development
+---
+id: local-development
+title: Local Development
+sidebar_position: 7
+slug: /platform/core/local-development
+---
 
 Use this checklist to spin up the BlackRoad OS stack locally. It assumes you cloned the repositories into a common directory and have Node.js 20+, npm or pnpm, git, and Docker available.
 
@@ -19,4 +24,4 @@ Not every integration must be live during local development. Use mock data for b
 
 ## Next steps
 
-When comfortable, explore [Extending Agents](extending-agents.md) to add new capabilities. Cross-reference environment settings in [Infra Environments](../infra/environments.md) before deploying anything beyond dev, and consult [Deployments & Runbooks](../infra/deployments-and-runbooks.md) for rollout discipline.
+When comfortable, explore [Extending Agents](/platform/api/extending-agents) to add new capabilities. Cross-reference environment settings in [Infra Environments](/platform/operator/environments) before deploying anything beyond dev, and consult [Deployments & Runbooks](/platform/operator/deployments-and-runbooks) for rollout discipline.

docs/platform-guides/core/platform-overview.mdx

@@ -1,7 +1,8 @@
 ---
-id: overview-blackroad-os-overview
+id: platform-overview
 title: BlackRoad OS Overview
-slug: /overview/blackroad-os-overview
+slug: /platform/core/overview
+sidebar_position: 1
 ---
 
 BlackRoad OS is an orchestration operating system that connects identity, truth, runtime, and interfaces into one verifiable loop. Each layer is explicit so operators, developers, partners, and future agents can see where a capability belongs and how evidence is captured.
@@ -28,5 +29,5 @@ Text / task → Operator → Agent(s) → DomainEvents → Journal entries → R
 ## How to read this layer cake
 - Start with the [Stack Map](./stack-map) to see the repositories and what layer they belong to.
 - Review [Seasons Overview](./seasons) to understand the roadmap and current phase.
-- Operators should continue to the [Prism Console](../ops/prism-console) and [Infra Guide](../ops/infra-guide).
+- Operators should continue to the [Prism Console](/platform/prism-console/overview) and [Infra Guide](/platform/operator/infra-guide).
-- Developers should read [Core Primitives](../dev/core-primitives) and [API Overview](../dev/api-overview) next.
+- Developers should read [Core Primitives](/platform/core/primitives) and [API Overview](/platform/api/overview) next.

docs/platform-guides/core/repos-and-services.mdx

@@ -1,4 +1,9 @@
-# Repos & Services
+---
+id: repos-and-services
+title: Repos & Services
+sidebar_position: 8
+slug: /platform/core/repos-and-services
+---
 
 The BlackRoad OS ecosystem is intentionally modular. Each repository owns a specific responsibility so teams can iterate independently while sharing common primitives like events, capabilities, and journaling. Use this map to understand where to look when debugging or extending the platform.
 
@@ -28,4 +33,4 @@ Terraform modules, environment definitions, DNS, networking, and runbooks. It ke
 
 ## Docs (`blackroad-os-docs`)
 
-This repository. It aggregates architecture, developer, operator, and compliance guidance so contributors have a single source of truth. For local setup, see [Local Development](local-development.md).
+This repository. It aggregates architecture, developer, operator, and compliance guidance so contributors have a single source of truth. For local setup, see [Local Development](/platform/core/local-development).

docs/platform-guides/core/seasons-overview.mdx

@@ -1,7 +1,8 @@
 ---
-id: overview-seasons
+id: platform-seasons
 title: Seasons Overview
-slug: /overview/seasons
+slug: /platform/core/seasons
+sidebar_position: 3
 ---
 
 Seasons describe the architecture phases BlackRoad OS moves through. They keep every repository aligned on the same goals and ensure the infra season tracker can reflect progress across codebases.

docs/platform-guides/core/stack-map.mdx

@@ -1,7 +1,8 @@
 ---
-id: overview-stack-map
+id: platform-stack-map
 title: Stack Map
-slug: /overview/stack-map
+slug: /platform/core/stack-map
+sidebar_position: 2
 ---
 
 The stack is intentionally split across focused repositories while sharing vocabulary and event types. Use this table to quickly align components, responsibilities, and maturity.

docs/platform-guides/operator/deployments-and-runbooks.mdx

@@ -1,4 +1,9 @@
-# Deployments & Runbooks
+---
+id: operator-deployments-and-runbooks
+title: Deployments & Runbooks
+sidebar_position: 5
+slug: /platform/operator/deployments-and-runbooks
+---
 
 Deployment, incident, and maintenance runbooks live alongside Terraform in `blackroad-os-infra/runbooks`. They capture repeatable procedures so operators can move quickly without skipping safety gates. This page summarizes the flow; always defer to the runbook for environment-specific commands.
 

docs/platform-guides/operator/dns-and-networking.mdx

@@ -1,4 +1,9 @@
-# DNS & Networking
+---
+id: operator-dns-and-networking
+title: DNS & Networking
+sidebar_position: 3
+slug: /platform/operator/dns-and-networking
+---
 
 DNS is managed through Cloudflare with a consistent pattern per environment. Each service receives a predictable subdomain so operators, agents, and external users know where to reach it. Terraform modules in `blackroad-os-infra` own zone records, TLS settings, and any required tunnels.
 
@@ -15,4 +20,4 @@ DNS is managed through Cloudflare with a consistent pattern per environment. Eac
 3. Apply the Terraform changes for the desired environment after peer review and required approvals.
 4. Validate propagation and health checks before advertising the new endpoint to agents or users.
 
-Networking relies on consistent CIDR allocations and security groups defined in infra modules. Coordinate with the infra team when introducing new ingress/egress paths or when agents need to reach sensitive systems. For deployment choreography, see [Deployments & Runbooks](deployments-and-runbooks.md).
+Networking relies on consistent CIDR allocations and security groups defined in infra modules. Coordinate with the infra team when introducing new ingress/egress paths or when agents need to reach sensitive systems. For deployment choreography, see [Deployments & Runbooks](/platform/operator/deployments-and-runbooks).

docs/platform-guides/operator/environments.mdx

@@ -1,4 +1,9 @@
-# Environments
+---
+id: operator-environments
+title: Environments
+sidebar_position: 4
+slug: /platform/operator/environments
+---
 
 BlackRoad OS is deployed across three environments that share Terraform modules but differ in usage and change cadence. The `blackroad-os-infra` repository holds the definitions under `envs/`, keeping configuration predictable and reviewable.
 
@@ -14,6 +19,6 @@ Each environment directory defines its own variables, state backend, and service
 
 ## Working with envs
 
-When introducing a new service, add it to the relevant environment definitions and ensure DNS entries are present (see [DNS & Networking](dns-and-networking.md)). Use Terraform workspaces or separate state files as defined in `blackroad-os-infra` to avoid collisions. Apply changes in dev first, validate health checks, then promote to staging and prod with the appropriate human approvals.
+When introducing a new service, add it to the relevant environment definitions and ensure DNS entries are present (see [DNS & Networking](/platform/operator/dns-and-networking)). Use Terraform workspaces or separate state files as defined in `blackroad-os-infra` to avoid collisions. Apply changes in dev first, validate health checks, then promote to staging and prod with the appropriate human approvals.
 
 Runbooks for deploying and verifying updates live in `blackroad-os-infra/runbooks`. Coordinate with operators when changes affect shared resources like VPCs, certificates, or secrets. TODO: add direct links to specific runbooks once the directory is finalized.

docs/platform-guides/operator/infra-guide.mdx

@@ -1,7 +1,8 @@
 ---
-id: ops-infra-guide
+id: operator-infra-guide
 title: Infra Guide
-slug: /ops/infra-guide
+slug: /platform/operator/infra-guide
+sidebar_position: 2
 ---
 
 Infrastructure definitions live in `blackroad-os-infra`. This guide orients operators to the core references rather than duplicating them here.

docs/platform-guides/operator/operator-runtime.mdx

@@ -1,7 +1,8 @@
 ---
-id: ops-operator-runtime
+id: operator-runtime
 title: Operator Runtime
-slug: /ops/operator-runtime
+slug: /platform/operator/runtime
+sidebar_position: 1
 ---
 
 `blackroad-os-operator` is the runtime where agents live, jobs run, and DomainEvents originate. It coordinates work, keeps a registry of agents, and exposes internal HTTP routes for orchestration tools.

docs/platform-guides/prism-console/prism-console-legacy.mdx

@@ -1,7 +1,8 @@
 ---
-id: ops-prism-console-legacy
+id: prism-console-legacy
 title: Prism Console (Legacy)
-slug: /ops/prism-console-legacy
+slug: /platform/prism-console/legacy
+sidebar_position: 2
 ---
 
 # Prism Console
@@ -17,10 +18,10 @@ Prism Console is the operator-facing UI for BlackRoad OS. It surfaces agent heal
 
 ## Configuration
 
-Set `NEXT_PUBLIC_API_BASE_URL` to the API endpoint for your environment before starting the console. For local development, point it at the API port you started from [Local Development](../dev/local-development.md). Ensure CORS and auth settings on the API side permit console access.
+Set `NEXT_PUBLIC_API_BASE_URL` to the API endpoint for your environment before starting the console. For local development, point it at the API port you started from [Local Development](/platform/core/local-development). Ensure CORS and auth settings on the API side permit console access.
 
 ## Usage
 
 Start the API and operator, then run Prism Console. Navigate to `/dashboard` for overall health or `/finance` to check the finance agents. Use event views to confirm that PS-SHA∞ journal entries are flowing as expected. TODO: add screenshots once the UI stabilizes.
 
-> This page is legacy. See the updated [Prism Console guide](/ops/prism-console) for the v1 docs home experience.
+> This page is legacy. See the updated [Prism Console guide](/platform/prism-console/overview) for the v1 docs home experience.

docs/platform-guides/prism-console/prism-console.mdx

@@ -1,7 +1,8 @@
 ---
-id: ops-prism-console
+id: prism-console
 title: Prism Console
-slug: /ops/prism-console
+slug: /platform/prism-console/overview
+sidebar_position: 1
 ---
 
 Prism Console is the operator-facing cockpit for BlackRoad OS. It brings system status, agent state, finance visibility, and the RoadChain event stream into one UI so an orchestrator can act quickly and with evidence.

docs/reference/architecture/agents-and-orchestration.mdx

@@ -1,4 +1,9 @@
-# Agents and Orchestration
+---
+id: architecture-agents-and-orchestration
+title: Agents and Orchestration
+sidebar_position: 2
+slug: /reference/architecture/agents-and-orchestration
+---
 
 Agents are the atomic workers inside BlackRoad OS. Each agent advertises capabilities, consumes tasks through the event bus, and emits journal entries for every significant action. The intent is to keep agents composable and observable so humans can inspect, approve, or override critical steps without rewriting code paths.
 
@@ -17,4 +22,4 @@ Agents are the atomic workers inside BlackRoad OS. Each agent advertises capabil
 4. Every state transition emits events and PS-SHA∞ journal entries so downstream systems and auditors can trace actions.
 5. When human sign-off is required, the orchestrator escalates to the appropriate approver before closing the loop.
 
-The same pattern applies to incident response, treasury moves, and infrastructure changes. For a catalog of finance-specific agents, see the [Finance Layer](finance-layer.md). To extend the system with new automations, follow the guidance in [Extending Agents](../dev/extending-agents.md).
+The same pattern applies to incident response, treasury moves, and infrastructure changes. For a catalog of finance-specific agents, see the [Finance Layer](/packs/finance/finance-layer). To extend the system with new automations, follow the guidance in [Extending Agents](/platform/api/extending-agents).

docs/reference/architecture/overview.mdx

@@ -1,4 +1,9 @@
-# Architecture Overview
+---
+id: architecture-overview
+title: Architecture Overview
+sidebar_position: 1
+slug: /reference/architecture/overview
+---
 
 BlackRoad OS is organized into a small set of collaborating services that work together to deliver AI-led operations with human oversight. Each component owns a clear domain boundary and communicates through events, APIs, and shared journaling. Understanding these responsibilities helps contributors reason about changes without losing sight of compliance and observability goals.
 
@@ -25,4 +30,4 @@ User / Orchestrator -> Web (marketing) -> (optional) Docs
 Infra (DNS, networking, environments) underpins every service
 ```
 
-Core primitives flow through the Operator and API: tasks are emitted onto the event bus, agents claim work, and every significant action emits a journal entry. Prism Console consumes the API and stream endpoints to present live state, while Infra ensures each environment is consistent and auditable. For deeper agent mechanics, see [Agents and Orchestration](agents-and-orchestration.md); for finance-specific behavior, head to the [Finance Layer](finance-layer.md).
+Core primitives flow through the Operator and API: tasks are emitted onto the event bus, agents claim work, and every significant action emits a journal entry. Prism Console consumes the API and stream endpoints to present live state, while Infra ensures each environment is consistent and auditable. For deeper agent mechanics, see [Agents and Orchestration](/reference/architecture/agents-and-orchestration); for finance-specific behavior, head to the [Finance Layer](/packs/finance/finance-layer).

docs/reference/architecture/ps-sha-infinity.mdx

@@ -1,4 +1,9 @@
-# PS-SHA∞ Journaling
+---
+id: architecture-ps-sha-infinity
+title: PS-SHA∞ Journaling
+sidebar_position: 3
+slug: /reference/architecture/ps-sha-infinity
+---
 
 PS-SHA∞ is the cryptographic journaling backbone that underpins integrity and continuity across BlackRoad OS. It is modeled as an append-only log with hash-chained entries so tampering is immediately detectable. Every meaningful task, decision, and agent emission can be recorded here to satisfy auditability requirements without slowing down the system.
 
@@ -16,4 +21,4 @@ Agents and orchestrators call the PS-SHA∞ interface whenever they execute a st
 
 ## What comes next
 
-Expect stronger identity primitives, hardware-backed keys where appropriate, and richer metadata (policy IDs, attestation fingerprints) as the system matures. The journaling model is intentionally minimal today so integrators can reason about it alongside the [Finance Layer](finance-layer.md) and other core workflows.
+Expect stronger identity primitives, hardware-backed keys where appropriate, and richer metadata (policy IDs, attestation fingerprints) as the system matures. The journaling model is intentionally minimal today so integrators can reason about it alongside the [Finance Layer](/packs/finance/finance-layer) and other core workflows.

docs/reference/cli.mdx

@@ -0,0 +1,33 @@
+---
+id: cli-reference
+title: CLI Reference
+sidebar_position: 1
+slug: /reference/cli
+---
+
+Use the CLI to scaffold agents, inspect RoadChain entries, and interact with Operator without opening the console. Commands assume you have Node 20+ and the repo cloned locally.
+
+```bash
+# Install dependencies
+npm install
+
+# Start docs locally
+npm run start
+```
+
+## Common commands
+
+- `yarn build` — Builds the docs with link checking enabled.
+- `yarn build:catalog` — Regenerates agent docs from `agent-catalog/agents.yaml`.
+- `yarn fetch:openapi` — Pulls the latest OpenAPI spec into `static/api/openapi.yaml`.
+- `yarn start` — Launches the local Docusaurus dev server.
+
+## Environment variables
+
+- `ALGOLIA_APP_ID` and `ALGOLIA_API_KEY` power DocSearch.
+- `DOCS_PREVIEW_URL` is emitted by CI for PR comments.
+- `OPENAPI_SOURCE` can override the default `blackroad-os-api` spec source.
+
+## Troubleshooting
+
+If a command fails, clear caches with `npm run clean` and rerun. For dependency issues, remove `node_modules` and reinstall with Node 20.

docs/reference/openapi.mdx

@@ -0,0 +1,13 @@
+---
+id: openapi-reference
+title: OpenAPI Reference
+sidebar_position: 2
+slug: /reference/openapi
+---
+
+The HTTP surface area for BlackRoad OS is defined in `blackroad-os-api`. The spec is pulled at build time and rendered with Redoc.
+
+- Generated Redoc page: [/reference/openapi](./openapi)
+- Source file: `static/api/openapi.yaml` (populated via `yarn fetch:openapi`)
+
+Use the Reference navigation to open the rendered spec.

docusaurus.config.ts

@@ -1,21 +1,34 @@
 import {themes as prismThemes} from 'prism-react-renderer';
 import type {Config} from '@docusaurus/types';
 
+const tailwindPlugin = async () => ({
+  name: 'tailwindcss-plugin',
+  configurePostCss(postcssOptions) {
+    // Append TailwindCSS and autoprefixer.
+    postcssOptions.plugins.push(require('tailwindcss'));
+    postcssOptions.plugins.push(require('autoprefixer'));
+    return postcssOptions;
+  },
+});
+
 const config: Config = {
   title: 'BlackRoad OS Docs',
   tagline: 'AI-first operating system for 10,000+ virtual employees and one human orchestrator',
   url: 'https://blackroad.systems',
   baseUrl: '/',
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
   favicon: 'img/favicon.svg',
   organizationName: 'blackroad-os',
   projectName: 'blackroad-os-docs',
   trailingSlash: false,
-  i18n: {
+  markdown: {
-    defaultLocale: 'en',
+    mermaid: true,
-    locales: ['en'],
+    hooks: {
+      onBrokenMarkdownLinks: 'warn',
     },
+  },
+  themes: ['@docusaurus/theme-mermaid'],
+  plugins: [tailwindPlugin],
   presets: [
     [
       'classic',
@@ -25,6 +38,8 @@ const config: Config = {
           routeBasePath: '/',
           sidebarPath: require.resolve('./sidebars.ts'),
           editUrl: 'https://github.com/blackroad-os/blackroad-os-docs/edit/main/',
+          showLastUpdateAuthor: true,
+          showLastUpdateTime: true,
         },
         blog: false,
         theme: {
@@ -32,8 +47,27 @@ const config: Config = {
         },
       },
     ],
+    [
+      'redocusaurus',
+      {
+        specs: [
+          {
+            id: 'openapi',
+            spec: 'static/api/openapi.yaml',
+            route: '/reference/openapi',
+          },
+        ],
+        theme: {
+          primaryColor: '#0f172a',
+        },
+      },
+    ],
   ],
   themeConfig: {
+    colorMode: {
+      defaultMode: 'dark',
+      respectPrefersColorScheme: true,
+    },
     navbar: {
       title: 'BlackRoad OS Docs',
       logo: {
@@ -41,7 +75,12 @@ const config: Config = {
         src: 'img/logo.svg',
       },
       items: [
-        {type: 'docSidebar', sidebarId: 'docsSidebar', position: 'left', label: 'Docs'},
+        {type: 'doc', docId: 'getting-started/quick-start', label: 'Getting Started', position: 'left'},
+        {type: 'doc', docId: 'platform-guides/core/platform-overview', label: 'Platform Guides', position: 'left'},
+        {type: 'doc', docId: 'agent-catalog/agent-catalog-overview', label: 'Agent Catalog & Roles', position: 'left'},
+        {type: 'doc', docId: 'packs/finance/finance-pack-overview', label: 'Packs', position: 'left'},
+        {type: 'doc', docId: 'reference/cli-reference', label: 'Reference', position: 'left'},
+        {type: 'doc', docId: 'governance-policy/regulatory-overview', label: 'Governance & Policy', position: 'left'},
         {href: 'https://github.com/blackroad-os/blackroad-os-web', label: 'Main Site', position: 'right'},
         {href: 'https://github.com/blackroad-os/blackroad-os-docs', label: 'GitHub', position: 'right'},
       ],
@@ -53,24 +92,24 @@ const config: Config = {
           title: 'BlackRoad OS',
           items: [
             {label: 'Docs Home', to: '/'},
-            {label: 'Stack Map', to: '/overview/stack-map'},
+            {label: 'Stack Map', to: '/platform/core/stack-map'},
-            {label: 'Seasons Overview', to: '/overview/seasons'},
+            {label: 'Seasons Overview', to: '/platform/core/seasons'},
           ],
         },
         {
           title: 'Operate the OS',
           items: [
-            {label: 'Prism Console', to: '/ops/prism-console'},
+            {label: 'Prism Console', to: '/platform/prism-console/overview'},
-            {label: 'Operator Runtime', to: '/ops/operator-runtime'},
+            {label: 'Operator Runtime', to: '/platform/operator/runtime'},
-            {label: 'Infra Guide', to: '/ops/infra-guide'},
+            {label: 'Infra Guide', to: '/platform/operator/infra-guide'},
           ],
         },
         {
-          title: 'Build & Business',
+          title: 'Build & Reference',
           items: [
-            {label: 'Core Primitives', to: '/dev/core-primitives'},
+            {label: 'Core Primitives', to: '/platform/core/primitives'},
-            {label: 'API Overview', to: '/dev/api-overview'},
+            {label: 'OpenAPI', to: '/reference/openapi'},
-            {label: 'Value Proposition', to: '/business/value-proposition'},
+            {label: 'CLI', to: '/reference/cli'},
           ],
         },
       ],
@@ -80,6 +119,18 @@ const config: Config = {
       theme: prismThemes.github,
       darkTheme: prismThemes.dracula,
     },
+    mermaid: {
+      theme: {light: 'neutral', dark: 'forest'},
+    },
+    algolia: {
+      appId: process.env.ALGOLIA_APP_ID || 'APP_ID',
+      apiKey: process.env.ALGOLIA_API_KEY || 'API_KEY',
+      indexName: 'blackroad-os-docs',
+      contextualSearch: true,
+      searchParameters: {
+        optionalWords: ['agent', 'pack'],
+      },
+    },
   },
 };
 

package.json

@@ -4,8 +4,12 @@
   "private": true,
   "description": "Official documentation hub for BlackRoad OS",
   "scripts": {
+    "prestart": "npm run prepare:docs",
     "start": "docusaurus start",
-    "build": "docusaurus build",
+    "prepare:docs": "npm run fetch:openapi && npm run build:catalog",
+    "fetch:openapi": "tsx scripts/fetch-openapi.ts",
+    "build:catalog": "tsx scripts/build-catalog-docs.ts",
+    "build": "npm run prepare:docs && docusaurus build",
     "serve": "docusaurus serve",
     "swizzle": "docusaurus swizzle",
     "clean": "docusaurus clear"
@@ -17,15 +21,24 @@
     "@docusaurus/core": "^3.9.2",
     "@docusaurus/preset-classic": "^3.9.2",
     "@docusaurus/theme-classic": "^3.9.2",
+    "@docusaurus/theme-mermaid": "^3.9.2",
+    "fs-extra": "^11.2.0",
+    "js-yaml": "^4.1.0",
     "clsx": "^2.1.1",
     "prism-react-renderer": "^2.4.1",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "redocusaurus": "^2.2.0"
   },
   "devDependencies": {
     "@docusaurus/types": "^3.9.2",
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.6",
+    "@types/fs-extra": "^11.0.4",
+    "autoprefixer": "^10.4.20",
+    "gh-pages": "^6.2.0",
+    "tailwindcss": "^3.4.14",
+    "tsx": "^4.19.2",
     "typescript": "^5.9.3"
   }
 }

postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

scripts/build-catalog-docs.ts

@@ -0,0 +1,105 @@
+import fs from 'fs-extra';
+import path from 'path';
+import yaml from 'js-yaml';
+
+type Agent = {
+  id: string;
+  name: string;
+  pack?: string;
+  role?: string;
+  description?: string;
+  approvals?: {type: string; description?: string}[];
+  traits?: string[];
+  inputs?: string[];
+  outputs?: string[];
+};
+
+const catalogPath = path.join(process.cwd(), 'agent-catalog/agents.yaml');
+const docsOut = path.join(process.cwd(), 'docs/agents');
+const orgChartOut = path.join(process.cwd(), 'docs/org-chart.mmd');
+const orgChartDoc = path.join(process.cwd(), 'docs/agent-catalog/org-chart.mdx');
+
+async function buildDocs() {
+  if (!(await fs.pathExists(catalogPath))) {
+    console.warn(`[agent-catalog] No catalog found at ${catalogPath}; skipping generation.`);
+    return;
+  }
+
+  const raw = await fs.readFile(catalogPath, 'utf8');
+  const parsed = (yaml.load(raw) as Agent[]) || [];
+  await fs.emptyDir(docsOut);
+
+  const packNodes = new Map<string, string[]>();
+
+  await Promise.all(
+    parsed.map(async (agent, index) => {
+      const packLabel = agent.pack || 'unassigned';
+      const keywords = [agent.id, agent.name, packLabel];
+      const frontmatter = [
+        '---',
+        `id: agent-${agent.id}`,
+        `title: ${agent.name}${agent.role ? ` — ${agent.role}` : ''}`,
+        `sidebar_position: ${index + 1}`,
+        `keywords:`,
+        ...keywords.map((k) => `  - ${k}`),
+        '---',
+        '',
+      ].join('\n');
+
+      const approvals = (agent.approvals || [])
+        .map((approval) => `| ${approval.type} | ${approval.description || ''} |`)
+        .join('\n');
+
+      const traits = (agent.traits || []).map((trait) => `- ${trait}`).join('\n') || '- Not documented';
+      const inputs = (agent.inputs || []).map((input) => `- ${input}`).join('\n') || '- Not documented';
+      const outputs = (agent.outputs || []).map((output) => `- ${output}`).join('\n') || '- Not documented';
+
+      const body = `${frontmatter}${agent.description || ''}\n\n` +
+        `**Pack:** ${packLabel}\n\n` +
+        `## Persona\n` +
+        `- **Role:** ${agent.role || 'Unspecified'}\n` +
+        `- **Capabilities:** ${agent.description || 'Unspecified'}\n\n` +
+        `## Approval gates\n` +
+        `| Type | Description |\n| --- | --- |\n${approvals || '| — | — |'}\n\n` +
+        `## Traits\n${traits}\n\n` +
+        `## Inputs\n${inputs}\n\n` +
+        `## Outputs\n${outputs}\n`;
+
+      await fs.outputFile(path.join(docsOut, `${agent.id}.mdx`), body);
+
+      const packList = packNodes.get(packLabel) || [];
+      packList.push(agent.id);
+      packNodes.set(packLabel, packList);
+    }),
+  );
+
+  const orgChartLines: string[] = ['graph TD', '  root[Agent Catalog]'];
+  for (const [pack, agents] of packNodes.entries()) {
+    const packId = `pack_${pack.replace(/[^a-zA-Z0-9]/g, '')}`;
+    orgChartLines.push(`  root --> ${packId}[${pack} pack]`);
+    agents.forEach((agentId) => {
+      orgChartLines.push(`  ${packId} --> ${agentId}(${agentId})`);
+    });
+  }
+
+  await fs.outputFile(orgChartOut, orgChartLines.join('\n'));
+  const orgChartDocContent = [
+    '---',
+    'id: agent-org-chart',
+    'title: Agent Org Chart',
+    'sidebar_position: 2',
+    '---',
+    '',
+    '```mermaid',
+    ...orgChartLines,
+    '```',
+    '',
+  ].join('\n');
+  await fs.outputFile(orgChartDoc, orgChartDocContent);
+  console.log(`[agent-catalog] Generated ${parsed.length} agent docs and org chart.`);
+}
+
+buildDocs().catch((error) => {
+  console.error('[agent-catalog] Failed to build catalog docs', error);
+  process.exit(1);
+});

scripts/fetch-openapi.ts

@@ -0,0 +1,25 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+const source = process.env.OPENAPI_SOURCE || 'https://raw.githubusercontent.com/blackroad-os/blackroad-os-api/main/openapi.yaml';
+const target = path.join(process.cwd(), 'static/api/openapi.yaml');
+
+async function fetchSpec() {
+  console.log(`[openapi] Fetching spec from ${source}`);
+  try {
+    const response = await fetch(source);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`);
+    }
+
+    const body = await response.text();
+    await fs.outputFile(target, body);
+    console.log(`[openapi] Wrote spec to ${target}`);
+  } catch (error) {
+    console.warn('[openapi] Falling back to stub spec because remote fetch failed.', error);
+    const fallback = `openapi: 3.0.0\ninfo:\n  title: BlackRoad OS API (stub)\n  version: 0.0.0\npaths: {}\n`;
+    await fs.outputFile(target, fallback);
+  }
+}
+
+fetchSpec();

sidebars.ts

@@ -1,56 +1,7 @@
 import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
 
 const sidebars: SidebarsConfig = {
-  docsSidebar: [
+  docsSidebar: [{type: 'autogenerated', dirName: '.'}],
-    'docs-home',
-    'getting-started',
-    {
-      type: 'category',
-      label: 'Overview',
-      items: [
-        'overview/overview-blackroad-os-overview',
-        'overview/overview-stack-map',
-        'overview/overview-seasons',
-      ],
-    },
-    {
-      type: 'category',
-      label: 'Operate the OS',
-      items: [
-        'ops/ops-prism-console',
-        'ops/ops-operator-runtime',
-        'ops/ops-infra-guide',
-      ],
-    },
-    {
-      type: 'category',
-      label: 'Build on the OS',
-      items: [
-        'dev/dev-core-primitives',
-        'dev/dev-api-overview',
-        'dev/dev-agents-atlas-and-friends',
-        'dev/dev-events-and-roadchain',
-      ],
-    },
-    {
-      type: 'category',
-      label: 'Business & Vision',
-      items: [
-        'business/business-pain-points',
-        'business/business-value-proposition',
-      ],
-    },
-    {
-      type: 'category',
-      label: 'Meta',
-      items: [
-        'meta/meta-docs-mega-prompt',
-        'meta/meta-glossary',
-        'meta/meta-master-codex-prompt',
-        'meta/meta-architecture-decisions',
-      ],
-    },
-  ],
 };
 
 export default sidebars;

src/css/blackroad-os-brand/tokens.css

@@ -0,0 +1,8 @@
+:root {
+  --br-brand-ink: #0f172a;
+  --br-brand-surface: #0b1020;
+  --br-brand-accent: #6b21a8;
+  --br-brand-glow: #22d3ee;
+  --br-brand-foreground: #e5e7eb;
+  --br-brand-muted: #9ca3af;
+}

src/css/custom.css

@@ -1,15 +1,30 @@
+@import './blackroad-os-brand/tokens.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
 :root {
-  --ifm-color-primary: #111827;
+  --ifm-color-primary: var(--br-brand-ink);
-  --ifm-color-primary-dark: #0f172a;
+  --ifm-color-primary-dark: #0c1223;
-  --ifm-color-primary-darker: #0b1221;
+  --ifm-color-primary-darker: #0a0e1b;
-  --ifm-color-primary-darkest: #070c17;
+  --ifm-color-primary-darkest: #070a14;
-  --ifm-color-primary-light: #1f2937;
+  --ifm-color-primary-light: #131d32;
-  --ifm-color-primary-lighter: #374151;
+  --ifm-color-primary-lighter: #1b2640;
-  --ifm-color-primary-lightest: #4b5563;
+  --ifm-color-primary-lightest: #24304d;
+  --ifm-background-color: var(--br-brand-surface);
+  --ifm-font-color-base: var(--br-brand-foreground);
+  --ifm-link-color: var(--br-brand-glow);
+  --ifm-navbar-background-color: rgba(12, 18, 35, 0.95);
+}
+
+[data-theme='dark'] {
+  --ifm-background-color: var(--br-brand-surface);
+  --ifm-font-color-base: var(--br-brand-foreground);
 }
 
 .hero--primary {
-  background: linear-gradient(120deg, #0f172a 0%, #1f2937 35%, #6b21a8 100%);
+  background: linear-gradient(120deg, var(--br-brand-ink) 0%, #1f2937 35%, var(--br-brand-accent) 100%);
 }
 
 .homepage-hero {
@@ -18,31 +33,18 @@
 }
 
 .homepage-hero .buttons {
-  margin-top: 1.5rem;
+  display: flex;
-}
-
-.callout-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
   gap: 1rem;
 }
 
-.callout-card {
+.card-grid {
-  background: #0f172a;
+  @apply grid gap-6 md:grid-cols-2;
-  color: #f9fafb;
-  border: 1px solid #1f2937;
-  border-radius: 12px;
-  padding: 1rem;
-  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.2);
 }
 
-.callout-card h3 {
+.card-grid .card {
-  margin-top: 0;
+  @apply bg-slate-800/60 border border-slate-700 p-6 rounded-xl shadow-lg;
 }
 
-.card-subtitle {
+.footer--dark {
-  color: #cbd5e1;
+  background: linear-gradient(180deg, var(--br-brand-ink) 0%, #0f172a 40%, #050914 100%);
-  font-size: 0.9rem;
-  margin-top: -0.25rem;
-  margin-bottom: 0.5rem;
 }

static/api/openapi.yaml

@@ -0,0 +1,5 @@
+openapi: 3.0.0
+info:
+  title: BlackRoad OS API (stub)
+  version: 0.0.0
+paths: {}

tailwind.config.js

@@ -0,0 +1,18 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ['./src/**/*.{js,jsx,ts,tsx}', './docs/**/*.{md,mdx}', './docusaurus.config.ts'],
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          ink: 'var(--br-brand-ink)',
+          surface: 'var(--br-brand-surface)',
+          accent: 'var(--br-brand-accent)',
+          glow: 'var(--br-brand-glow)',
+        },
+      },
+    },
+  },
+  darkMode: 'class',
+  plugins: [],
+};

versioned_docs/version-v0.1/agent-catalog/org-chart.mdx

@@ -0,0 +1,15 @@
+---
+id: agent-org-chart
+title: Agent Org Chart
+sidebar_position: 2
+slug: /agent-catalog/org-chart
+---
+
+```mermaid
+graph TD
+  root[Agent Catalog]
+  root --> pack_finance[finance pack]
+  pack_finance --> atlas(atlas)
+  root --> pack_education[education pack]
+  pack_education --> lumen(lumen)
+```

versioned_docs/version-v0.1/agent-catalog/overview.mdx

@@ -0,0 +1,14 @@
+---
+id: agent-catalog-overview
+title: Agent Catalog & Roles
+sidebar_position: 1
+slug: /agent-catalog/overview
+---
+
+The agent catalog is generated from `agent-catalog/agents.yaml` during the docs build. Each agent page lists capabilities, approvals, inputs, and evidence expectations so operators know how to deploy it safely.
+
+- **Where to edit:** Update `agent-catalog/agents.yaml` and rerun `yarn build:catalog`.
+- **Output:** MDX pages in `docs/agents/` and a Mermaid org chart in `docs/org-chart.mmd`.
+- **Search:** Agent IDs, pack names, and role keywords are added to Algolia metadata for discovery.
+
+Use the generated catalog to align runtime policy, access, and release notes across the organization.

versioned_docs/version-v0.1/agents/atlas.mdx

@@ -0,0 +1,33 @@
+---
+id: agent-atlas
+title: Atlas — Deployment & Ops Engineer
+sidebar_position: 1
+keywords:
+  - atlas
+  - Atlas
+  - finance
+---
+Coordinates deployments, verifies rollouts, and bridges observability signals back to Prism Console.
+
+**Pack:** finance
+
+## Persona
+- **Role:** Deployment & Ops Engineer
+- **Capabilities:** Coordinates deployments, verifies rollouts, and bridges observability signals back to Prism Console.
+
+## Approval gates
+| Type | Description |
+| --- | --- |
+| human | Requires operator sign-off for production rollouts |
+
+## Traits
+- reliability-first
+- infra-aware
+
+## Inputs
+- deployments queue
+- service registry
+
+## Outputs
+- roadchain events
+- incident signals

versioned_docs/version-v0.1/agents/lumen.mdx

@@ -0,0 +1,33 @@
+---
+id: agent-lumen
+title: Lumen — Learning Experience Designer
+sidebar_position: 2
+keywords:
+  - lumen
+  - Lumen
+  - education
+---
+Drafts course outlines, tracks learner signals, and routes interventions to instructors.
+
+**Pack:** education
+
+## Persona
+- **Role:** Learning Experience Designer
+- **Capabilities:** Drafts course outlines, tracks learner signals, and routes interventions to instructors.
+
+## Approval gates
+| Type | Description |
+| --- | --- |
+| policy | Auto-approves drafts; escalates published curricula for human review |
+
+## Traits
+- empathetic
+- rubric-driven
+
+## Inputs
+- learner milestones
+- content repository
+
+## Outputs
+- lesson plans
+- audit-ready rubrics

versioned_docs/version-v0.1/getting-started/faq.mdx

@@ -0,0 +1,54 @@
+---
+id: faq
+title: FAQ
+sidebar_position: 3
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Use this FAQ when onboarding teammates. It highlights answers that commonly come up while running BlackRoad OS locally or in shared environments.
+
+## How do I install dependencies?
+
+- Use Node 20+ and `npm install` from this repo to pull docs dependencies.
+- Development repos such as `blackroad-os-core` and `blackroad-os-operator` also target Node 20+. Install Docker and Terraform if you plan to run infra workflows.
+
+## Which repo do I run first?
+
+1. Start the Operator runtime so agents can register and emit events.
+2. Launch `blackroad-os-api` to expose metrics and task orchestration endpoints.
+3. Bring up Prism Console for observability.
+4. Optionally start packs (Finance, Education) to exercise specific playbooks.
+
+## Where do configuration values live?
+
+Most services load environment variables from `.env` files. Secrets should be managed through your vault of choice; do **not** check them into Git. Docs-specific settings (Algolia, API sources) are read from `process.env` during build.
+
+## How do I add a new document?
+
+Place the MDX file under the relevant top-level folder (Getting Started, Platform Guides, Packs, Reference, Governance & Policy). The sidebar is autogenerated from directories, so the file will appear automatically.
+
+## What if I hit a broken link?
+
+The docs CI workflow fails the build on broken links. Run `yarn build` locally to surface issues before pushing.
+
+## How are agents documented?
+
+Agent pages are generated from `agent-catalog/agents.yaml` during the build. Update that file and rerun `yarn build` (or `yarn build:catalog`) to regenerate docs.
+
+## Is there a dark/light mode toggle?
+
+Yes. The site defaults to dark mode but offers a toggle in the header if you prefer light mode.
+
+<Tabs>
+  <TabItem value="resources" label="Fast references">
+    - Platform: `/platform/core/overview`
+    - Operator runtime: `/platform/operator/runtime`
+    - Prism Console: `/platform/prism-console/overview`
+  </TabItem>
+  <TabItem value="support" label="Need help?">
+    - Open an issue in `blackroad-os-docs` for docs-specific problems.
+    - Use the operator pager channel for runtime incidents.
+  </TabItem>
+</Tabs>

versioned_docs/version-v0.1/getting-started/quick-start.mdx

@@ -0,0 +1,41 @@
+---
+id: quick-start
+title: Quick Start
+sidebar_position: 1
+---
+
+This guide is for developers and curious operators who want to explore the BlackRoad OS ecosystem locally. It summarizes the repos you will touch, the tooling you need, and a straightforward path to spin up the most important services. Expect rapid iteration: the stack favors composability so you can replace stubs with production-grade agents as they become available.
+
+## What is in the BlackRoad OS ecosystem?
+
+BlackRoad OS spans several focused repositories, each responsible for a slice of the platform:
+
+- `blackroad-os-core` – domain models, capability definitions, event bus abstraction, and the PS-SHA∞ journaling interface.
+- `blackroad-os-operator` – hosts agents (finance, infra, and beyond) plus orchestrators that coordinate them.
+- `blackroad-os-api` – public API surface to expose OS metrics, tasks, and finance capabilities.
+- `blackroad-os-prism-console` – admin and observability UI for agents, metrics, and events.
+- `blackroad-os-web` – marketing and public-facing site.
+- `blackroad-os-infra` – Terraform, environment definitions, and runbooks.
+- `blackroad-os-docs` – this documentation hub.
+- Supporting repos such as `blackroad-os-brand` and `blackroad-os-home` hold design assets and handbook material.
+
+## Prerequisites
+
+You will need a recent Node.js LTS (we validate on Node 20+), npm or pnpm, git, and Docker for services that expect containerized dependencies. Some agents are written in TypeScript, and the infra stack uses Terraform, so install those toolchains if you plan to contribute in those areas. Keep your shell environment ready to load `.env` files for service-specific variables.
+
+## Running everything locally (simple stack)
+
+A minimal local experience focuses on the operator, core, API, Prism Console, and the docs themselves:
+
+1. Clone the repos you need: `git clone` each repository listed above into a common workspace.
+2. Start `blackroad-os-core` if it exposes a runtime (or ensure its libraries are available to other services).
+3. Boot `blackroad-os-operator` to host agents; the finance agents can run in stub mode while you wire orchestration.
+4. Run `blackroad-os-api` to expose HTTP endpoints; default ports typically sit in the 4000–5000 range.
+5. Launch `blackroad-os-prism-console` with `NEXT_PUBLIC_API_BASE_URL` pointing at your API instance.
+6. Optionally run `blackroad-os-web` for public-site parity.
+
+Environment variables differ per service, but a common pattern is `PORT=xxxx` alongside service-specific API keys or base URLs. Start with defaults, then align ports to avoid conflicts when multiple processes run side by side.
+
+## Where to go next
+
+After you have the basics running, read the [Architecture Overview](/reference/architecture/overview) to understand how components talk to each other, then jump to the [Finance Layer](/packs/finance/finance-layer) for agent-specific behavior. For deployment considerations and domain names, see [Infra Environments](/platform/operator/environments) and [DNS & Networking](/platform/operator/dns-and-networking). When you want to extend the platform, the [Extending Agents](/platform/api/extending-agents) guide walks through adding new automation safely.

versioned_docs/version-v0.1/getting-started/welcome.mdx

@@ -0,0 +1,13 @@
+---
+id: welcome
+title: Welcome to BlackRoad OS
+sidebar_position: 2
+---
+
+BlackRoad OS is an AI-first operating system that lets one human orchestrator direct thousands of specialized agents with cryptographic audit trails and built-in compliance for highly regulated industries. The platform is intentionally opinionated so operators, engineers, and auditors can share a common map of how work flows, what evidence is captured, and where human approvals sit in the loop. If you are new to the ecosystem, start here before diving into code or running services locally.
+
+This handbook is the central place to learn how the ecosystem fits together. It connects architectural blueprints, developer workflows, operational runbooks, and the regulated story that underpins every release. Each section is designed to be approachable on its own while pointing you to deeper references when you want to build or extend the system.
+
+If you want the ten-thousand-foot view of components and data flow, jump to the [Architecture Overview](/reference/architecture/overview). When you are ready to try things locally, begin with [Getting Started](/getting-started/quick-start) for prerequisites, repo layout, and the minimal stack to boot. Operators and administrators can explore the [Prism Console](/platform/prism-console/overview) chapter to understand dashboards and configuration knobs. Finance leaders and engineers should read the [Finance Layer](/packs/finance/finance-layer) to see how ledgering, forecasting, and treasury automation are mapped into agents and orchestrators.
+
+The docs are intentionally iterative. TODO: add deeper API examples, event schemas, and RoadChain cryptography notes as the platform hardens. Until then, expect a balance of conceptual framing and practical steps so you can contribute without waiting for formal standards.

versioned_docs/version-v0.1/governance-policy/audit-and-journaling.mdx

@@ -0,0 +1,25 @@
+---
+id: audit-and-journaling
+title: Audit & Journaling
+sidebar_position: 2
+---
+
+Auditors need to answer who did what, when, and why. BlackRoad OS provides hooks for every significant action to be journaled via PS-SHA∞, creating a tamper-evident trail. This page explains the intent; it is not a formal compliance assertion.
+
+## Journaling model
+
+Every action that matters—task creation, capability execution, approvals—can append a `JournalEntry`. Entries capture actor identity, payload metadata, hashes of prior entries, and timestamps. Because the log is append-only and hash-chained, attempts to alter history become evident during verification.
+
+## Mapping to audit expectations
+
+- **Provenance:** Each entry links to the initiator and capability invoked.
+- **Sequencing:** Hash chaining preserves order and continuity across long-running workflows.
+- **Approval evidence:** Human-in-the-loop decisions are recorded with context so reviewers can confirm policy adherence.
+
+## Usage patterns
+
+Agents and orchestrators should emit journal entries at policy-defined checkpoints: before and after material ledger changes, when treasury actions are scheduled, and when incidents are declared or resolved. Prism Console can expose these entries for review alongside operational dashboards.
+
+## Caveats
+
+The current implementation uses `DevPsShaInfinity` for interface consistency, not production-grade cryptography. Treat outputs as informative until RoadChain-backed implementations replace the stub. Coordinate with compliance teams before representing journaling as a finalized control in audits.

versioned_docs/version-v0.1/governance-policy/incident-response.mdx

@@ -0,0 +1,23 @@
+---
+id: incident-response
+title: Incidents & Incident Response
+sidebar_position: 3
+---
+
+BlackRoad OS treats incidents as shared responsibilities between agents and humans. Automation accelerates detection and containment, while humans provide judgment and regulatory context. This page outlines the flow and points you to infra runbooks for detailed procedures.
+
+## Detection
+
+Metrics, health checks, and future alerting pipelines feed into the operator and Prism Console. Agents can emit anomaly events when they detect policy violations or missing data. TODO: formalize the alert catalogue and thresholds.
+
+## Triage
+
+Operators review events and journal entries to reconstruct timelines. Determine scope (which agents, which environments), identify blast radius, and decide whether to pause automations. Coordination between the API and operator ensures actions are reversible and traceable.
+
+## Response
+
+Common responses include rolling back a deployment, disabling a capability, or applying configuration overrides. Use PS-SHA∞ journaling to record every step, including who approved the action. Follow environment-specific rollback steps from `blackroad-os-infra/runbooks` and confirm health checks before restoring normal operations.
+
+## Postmortem
+
+After stabilization, capture a postmortem that includes timeline, root causes, and prevention steps. Link journal entries and event IDs so auditors can replay the sequence. Update runbooks and agent policies to prevent recurrence, and communicate findings to stakeholders who rely on the [Finance Layer](/packs/finance/finance-layer) or other critical workflows.

versioned_docs/version-v0.1/governance-policy/regulatory-overview.mdx

@@ -0,0 +1,21 @@
+---
+id: regulatory-overview
+title: Regulated Overview
+sidebar_position: 1
+---
+
+BlackRoad OS is built for organizations that operate in regulated industries. The platform emphasizes clear journaling, explicit human approval gates, and separation of duties so automation can coexist with oversight. This document is informational and does not constitute legal advice.
+
+## Principles
+
+- **Auditability:** Every material action can produce a PS-SHA∞ journal entry that records who initiated it, what changed, and when.
+- **Human-in-the-loop:** Critical workflows include escalation paths to designated approvers (e.g., Cecilia) before irreversible steps execute.
+- **Separation of duties:** Agents specialize by domain, reducing the blast radius of mistakes and making controls easier to reason about.
+
+## Why it matters
+
+Regulated stakeholders such as CFOs, General Counsels, and Chief Compliance Officers need confidence that AI-driven automation will not bypass controls. BlackRoad OS keeps the evidence trail and approval flow visible so auditors can trace decisions without reverse-engineering code paths.
+
+## Next steps
+
+Dive into [Audit & Journaling](/governance-policy/audit-and-journaling) for the cryptographic story or explore the [Finance Layer](/packs/finance/finance-layer) to see how policies surface in day-to-day workflows. TODO: add mappings to specific regulations as implementations mature.

versioned_docs/version-v0.1/index.mdx

@@ -0,0 +1,47 @@
+---
+id: docs-home
+title: BlackRoad OS Docs Home
+slug: /
+---
+
+BlackRoad OS is an orchestration operating system that lets a single human orchestrator direct agents and services with verifiable evidence. It anchors work to PS-SHA∞ identities, runs verification pipelines for truth states, journals everything through RoadChain, and surfaces system health through Prism Console and the public web shell. The platform lives across multiple repositories but speaks one architectural language.
+
+This hub participates in the shared **"BlackRoad OS - Master Orchestration"** project and is the canonical place to understand how the stack fits together, how to operate it, and why it exists.
+
+## Choose your path
+
+### Getting Started
+- [Quick Start](/getting-started/quick-start) — run the docs locally and tour the repos.
+- [FAQ](/getting-started/faq) — unblock common onboarding questions.
+
+### Platform Guides
+- [Core Overview](/platform/core/overview) — stack map, seasons, and primitives.
+- [API Overview](/platform/api/overview) — HTTP surface exposed by `blackroad-os-api`.
+- [Operator Runtime](/platform/operator/runtime) — how agents run and emit events.
+- [Prism Console](/platform/prism-console/overview) — cockpit for system status, agents, finance, and events.
+
+### Agent Catalog & Roles
+- Generated from `agent-catalog/agents.yaml` at build time so every persona stays in sync.
+- Visual org chart lives at `/org-chart` and updates with each catalog change.
+
+### Packs
+- [Finance pack](/packs/finance/overview) — treasury and billing automation with PS-SHA∞ evidence.
+- [Education pack](/packs/education/overview) — learning workflows tailored for compliance-heavy orgs.
+
+### Reference
+- [OpenAPI](/reference/openapi) — rendered via Redoc from `blackroad-os-api`.
+- [CLI](/reference/cli) — docs hub commands and environment variables.
+- [Agents: Atlas and Friends](/platform/core/agents-atlas-and-friends) — how agents register, identify, and report state.
+- [Events and RoadChain](/platform/core/events-and-roadchain) — journaling, blocks, and how the explorer will work.
+
+### Understand the Why
+- [Pain Points Summary](/packs/finance/pain-points) — problems BlackRoad OS is built to solve.
+- [Value Proposition](/packs/finance/value-proposition) — benefits for creators, teams, and partners.
+- [Seasons Overview](/platform/core/seasons) — how the roadmap is structured.
+
+## Quick orientation
+- [BlackRoad OS Overview](/platform/core/overview) — the layered picture from identity to interface.
+- [Stack Map](/platform/core/stack-map) — repositories mapped to layers and status.
+- [Getting Started](/getting-started/quick-start) — run the docs locally and clone the stack.
+
+BlackRoad OS is designed to stay honest about its current state. Pages mark components as planned, alpha, or in-flight so operators, developers, and partners know where to invest. Feedback and contributions are welcome—iterate with small, linked docs instead of monolithic walls of text.

versioned_docs/version-v0.1/meta/ARCHITECTURE_DECISIONS.mdx

@@ -0,0 +1,16 @@
+---
+id: meta-architecture-decisions
+title: Architecture Decisions
+slug: /meta/architecture-decisions
+---
+
+A lightweight record of the decisions that shape BlackRoad OS. Expand with ADRs as the stack grows.
+
+1. **PS-SHA∞ as the global identity anchor** — all humans, agents, and assets must carry PS-SHA∞ anchors to make auditability universal.
+2. **Operator runs the work** — jobs and agents execute only inside `blackroad-os-operator`; other repos should not duplicate execution loops.
+3. **API is the single HTTP surface** — `blackroad-os-api` is the contract for external consumers; Operator’s `/internal/*` routes are for orchestration tooling only.
+4. **Prism is for operators; Web is for public storytelling** — keep the ops UI and public shell distinct so narratives and sensitive data do not mix.
+5. **RoadChain is the audit substrate** — every DomainEvent rolls into journal entries and blocks; corrections are additive, not mutable.
+6. **Docs stay canonical** — `blackroad-os-docs` is the source of truth for architecture language and cross-repo alignment and participates in the "BlackRoad OS - Master Orchestration" project.
+
+When proposing changes, add context here or link to a dedicated ADR so future contributors and agents can understand why a decision exists.

versioned_docs/version-v0.1/meta/DOCS_MEGA_PROMPT.mdx

@@ -0,0 +1,58 @@
+---
+id: meta-docs-mega-prompt
+title: BlackRoad OS Docs Mega-Prompt
+slug: /meta/docs-mega-prompt
+---
+
+This is the **living documentation prompt** for the BlackRoad OS docs stack. It keeps humans and agents aligned on what this repository is, how to extend it, and how every change should be audited and remembered.
+
+## Prompt payload
+
+```json
+{
+  "repo": "blackroad-os-docs",
+  "purpose": "Comprehensive documentation, architecture diagrams, API references, brand rules, onboarding, and Codex for the BlackRoad OS ecosystem. All docs are agent-auditable, PS-SHA∞ signed, and designed for humans and agents alike.",
+  "agent_prompt": {
+    "role": "You are the BlackRoad Documentation Agent. Your goal is to ensure all contributors (human or agent) can understand, contribute to, and extend BlackRoad OS. You explain the system as if it's a legend and a machine at the same time.",
+    "goals": [
+      "Generate and maintain READMEs per repo and per subsystem (Core, Web, Research, Operator, Brand, etc).",
+      "Maintain a signed 'sig.index.json' that links all docs to their agents, versions, SIG traits, and commit hashes.",
+      "Host the 'Agent Constitution': internal governance rules for agent behavior, audit layers, and identity tracing.",
+      "Include a Contributor Guide (humans), Agent Prompt Engineering Guide (agents), and Legal/Philosophy Reference.",
+      "Visualize the OS architecture, repo interlinking, agent swarm flow, and memory chain in SVG + Mermaid.",
+      "Each doc must be traceable back to a source event: PR, prompt, agent reply, or deploy signature."
+    ],
+    "modules": [
+      "README.md → general orientation for humans",
+      "sig.index.json → links and audit metadata for all docs",
+      "guides/contributor_guide.md → how to submit PRs, style, structure",
+      "guides/agent_prompt_guide.md → how Lucidia-style prompts should be authored",
+      "constitution/agent_laws.md → PS-SHA∞ laws of identity, memory, interference, and duty",
+      "visuals/os-architecture.svg → system architecture diagram",
+      "docs/api/*.md → endpoints, headers, auth, SIG behavior",
+      "docs/philosophy/*.md → SIG, PS-SHA∞, spiral math, law of truth"
+    ],
+    "output": "A fully auditable, fractal-indexed documentation system. Humans read it, agents parse it, SIG signs it."
+  }
+}
+```
+
+## How to use this prompt
+- **Anchor every doc** — declare its scope, owners (human and agent), SIG traits, and commit hash in `sig.index.json` once introduced.
+- **Write for dual audiences** — the text must be legible to humans and parseable by agents. Prefer explicit identifiers, links, and state markers like _planned_, _alpha_, or _in-flight_.
+- **Reference source events** — note whether a page comes from a PR, prompt, deploy note, or other verifiable trigger.
+- **Keep modules discoverable** — README, guides, constitution, visuals, API references, and philosophy pages should cross-link so contributors can navigate by layer or by SIG.
+
+## Operational expectations
+- **Onboarding** — newcomers should find a runway: prerequisites, repo map, how to run docs locally, and how to propose changes. Pair this prompt with `guides/contributor_guide.md` once it lands.
+- **Agent discipline** — prompts that govern agents (e.g., constitution, prompt engineering guide) must describe audit hooks, memory chains, and identity controls tied to PS-SHA∞.
+- **Visual truth** — architecture diagrams (SVG or Mermaid) should match the current stack and embed legend-level narration that mirrors text docs.
+- **Evolution** — when the documentation surface shifts (new module, new SIG rule, new audit flow), update this prompt alongside the change so future contributors can see why it happened.
+
+## What to build next
+- Generate the signed `sig.index.json` to bind docs, agents, SIG traits, and commit hashes once the reference data is ready.
+- Add the human Contributor Guide, Agent Prompt Engineering Guide, and Agent Constitution as linked modules under `guides/` and `constitution/`.
+- Extend the visuals with SVG/Mermaid diagrams that map OS architecture, repo interlinks, agent swarm flow, and the memory chain.
+- Backfill traceability notes into existing docs so every page carries its provenance and audit expectations.
+
+If you want to continue the brand thread next, say **"Next!"** to move into `blackroad-os-brand` for gradients, fonts, and fractal seeds.

versioned_docs/version-v0.1/meta/GLOSSARY.mdx

@@ -0,0 +1,20 @@
+---
+id: meta-glossary
+title: Glossary
+slug: /meta/glossary
+---
+
+Quick definitions for recurring terms across the BlackRoad OS stack.
+
+- **PS-SHA∞** — global identity anchor used to bind humans, agents, and assets to verifiable worldlines.
+- **RoadChain** — hash-linked journal of events and blocks that provides tamper-evident history.
+- **DomainEvent** — canonical event emitted by Operator when jobs or agents change state.
+- **Journal Entry** — persisted record of a DomainEvent, ready to be sealed into a RoadChain block.
+- **Agent** — worker that executes jobs inside Operator; identified by PS-SHA∞ anchor and surfaced through API/Prism.
+- **Job** — unit of work assigned to an agent with lifecycle states (queued, running, succeeded, failed, cancelled).
+- **Atlas** — ops-aware agent focused on running and debugging the OS.
+- **Prism Console** — operator UI for system overview, agents, finance, and events.
+- **Season** — architecture phase used to coordinate goals across repositories.
+- **Operator** — runtime (`blackroad-os-operator`) that hosts agents, manages jobs, and emits events.
+- **API** — HTTP surface (`blackroad-os-api`) that exposes system data to Prism, web, and partners.
+- **Core** — shared domain models and helpers in `blackroad-os-core`.

versioned_docs/version-v0.1/meta/MASTER_CODEX_PROMPT.mdx

@@ -0,0 +1,56 @@
+---
+id: meta-master-codex-prompt
+title: BlackRoad OS Docs — Master Codex Prompt
+slug: /meta/master-codex-prompt
+description: Canonical prompt and guardrails for humans and agents maintaining blackroad-os-docs.
+---
+
+## Role and mission
+- You are the dedicated documentation and knowledge-structuring agent for `blackroad-os-docs`.
+- Primary responsibility: keep the BlackRoad OS documentation authoritative, navigable, and synchronized with `blackroad-os-core`, `blackroad-os-operator`, `blackroad-os-prism-console`, `blackroad-os-web`, `blackroad-os-brand`, and `blackroad-os-research`.
+- Deliver a versioned doc system (not blog posts) that serves humans and agent copilots.
+
+## Audiences
+1. **Founder (Queen Root User)** — wants narrative clarity, architecture maps, and operational mental models.
+2. **Collaborators and engineers** — need APIs, data models, setup steps, debugging guides, and runbooks.
+3. **Agents and LLMs** — need structured hints, consistent terminology, frontmatter tags, and stable anchors.
+
+## Scope and structure
+- Coverage: product overview, architecture, Lucidia basics, APIs, operations, Prism Console UX, identity and PS-SHA∞, monetization, and agent prompting guidance.
+- Suggested layout (adapt to the current tree): getting-started, architecture, lucidia, apis, operations, agents, brand, monetization, changelog, and meta. Keep `/specs` for OpenAPI or Lucidia JSON examples.
+- Each concept should have one canonical home; cross-link instead of duplicating.
+
+## Doc types and frontmatter
+- **Concept** — explains what/why.
+- **How-to / Guide** — prerequisites → steps → verification → next steps.
+- **Reference** — exhaustive types, endpoints, fields.
+- **Runbook** — operational playbooks for failure modes.
+- Frontmatter keys: `title`, `description`, `tags`, `status`, `api_version`, `lucidia_schema_version` (when relevant). Mark experimental or deprecated content explicitly.
+
+## Style and tone
+- Clear, direct, slightly playful but serious about correctness.
+- Short paragraphs, bullet lists, and early examples (code/JSON/diagrams-as-text).
+- Use consistent terminology across repos (LucidiaProgram, LucidiaRun, OperatorJob, Prism Console, PS-SHA∞, SIG).
+- Avoid secrets or private tokens in examples.
+
+## Key content areas
+- **BlackRoad OS overview** — layers, data flows, repository map.
+- **Lucidia basics** — programs, runs, graphs, nodes; include a small example and link to research for formalism.
+- **Core API and data models** — LucidiaProgram/LucidiaRun/SigIdentity/PS-SHA∞ plus request-response examples.
+- **Operator behavior** — jobs, queues, worker lifecycle, and API endpoints.
+- **Prism Console UX** — graph/timeline/logs/identity tabs and debugging flows.
+- **Identity, SIG, PS-SHA∞** — identity vs truth vs pattern and how anchors attach to programs, runs, and agents.
+- **Operations and SEV handling** — runbooks for outages, retries, and recovery paths.
+- **Monetization and partners** — high-level sponsorship/partner patterns and privacy stance.
+- **Agent prompting** — how to ask for Lucidia programs, how to route tasks to core/operator/prism/web correctly.
+
+## Agent-friendly structure
+- Use predictable headings (Overview, Concepts, API, Examples) and anchors agents can jump to.
+- Include machine-friendly resources like `doc-index.json` mapping concepts → doc paths.
+- Prefer multiple focused pages instead of one sprawling tome; keep related topics linked via See also sections.
+
+## Change management and versioning
+- Treat docs as live code: update alongside behavior changes and capture summaries in `/docs/changelog`.
+- Mark deprecated or relocated pages with frontmatter `status` and a short notice.
+- Keep lucidia schema/API versions visible where relevant.
+- Favor small, frequent updates that keep humans and agents aligned.

versioned_docs/version-v0.1/meta/doc-index.json

@@ -0,0 +1,17 @@
+{
+  "docs_home": "/",
+  "overview_blackroad_os": "/platform/core/overview",
+  "overview_stack_map": "/platform/core/stack-map",
+  "overview_seasons": "/platform/core/seasons",
+  "getting_started": "/getting-started/quick-start",
+  "core_primitives": "/platform/core/primitives",
+  "api_overview": "/platform/api/overview",
+  "agents_atlas": "/platform/core/agents-atlas-and-friends",
+  "events_and_roadchain": "/platform/core/events-and-roadchain",
+  "prism_console": "/platform/prism-console/overview",
+  "operator_runtime": "/platform/operator/runtime",
+  "infra_guide": "/platform/operator/infra-guide",
+  "glossary": "/meta/glossary",
+  "architecture_decisions": "/meta/architecture-decisions",
+  "master_codex_prompt": "/meta/master-codex-prompt"
+}

versioned_docs/version-v0.1/org-chart.mmd

@@ -0,0 +1,6 @@
+graph TD
+  root[Agent Catalog]
+  root --> pack_finance[finance pack]
+  pack_finance --> atlas(atlas)
+  root --> pack_education[education pack]
+  pack_education --> lumen(lumen)

versioned_docs/version-v0.1/packs/education/overview.mdx

@@ -0,0 +1,26 @@
+---
+id: education-pack-overview
+title: Education Pack Overview
+sidebar_position: 1
+slug: /packs/education/overview
+---
+
+The Education pack targets learning, onboarding, and knowledge-ops workflows. Use it as a template for launching new packs that expose curated agents and policies.
+
+## Included capabilities
+
+- Lesson planning and content review agents tailored for compliance-sensitive orgs.
+- Rubrics that translate PS-SHA∞ anchored observations into course-level evidence.
+- Prism Console dashboards focused on learner outcomes and instructor interventions.
+
+## Adding new education personas
+
+1. Add agent entries to `agent-catalog/agents.yaml` with `pack: education`.
+2. Run `yarn build:catalog` to generate MDX pages under `docs/agents/`.
+3. Link the generated pages from this pack overview or downstream playbooks.
+
+## Launch checklist
+
+- Validate integration against `blackroad-os-api` using the Reference section.
+- Confirm audit signals flow into PS-SHA∞ for each learning job.
+- Publish a short announcement in the Packs nav so operators know what changed.

versioned_docs/version-v0.1/packs/finance/finance-layer.mdx

@@ -0,0 +1,106 @@
+---
+id: finance-layer
+title: Finance Layer
+sidebar_position: 3
+slug: /packs/finance/finance-layer
+---
+
+The finance layer is composed of eight core agents that mirror traditional controllership and treasury functions. Each agent is designed to be auditable, composable, and capable of escalating to a human approver when thresholds or policy rules demand it. Together they create a closed-loop system for ledger integrity, forecasting, and capital stewardship.
+
+## Unified Ledger & Subledgers Agent
+
+**Purpose:** Maintain the general ledger and reconcile specialized subledgers (revenue, billing, expenses). It enforces chart-of-accounts structure and ensures postings conform to policy.
+
+**Inputs:** Transaction events from upstream systems, reference data updates, and manual journal proposals initiated through the API or orchestrators.
+
+**Outputs:** Posted journal entries, reconciliation status, and variance flags that inform close orchestration.
+
+**Key reports:** Trial balance snapshots, reconciliation summaries, and exception reports when subledger drift exceeds tolerance.
+
+**Escalation:** Requires human approval (e.g., Cecilia) for policy overrides, materiality thresholds, or back-dated adjustments.
+
+## Market & Reference Data Agent
+
+**Purpose:** Aggregate market data (FX, rates, commodities) and corporate reference data to anchor valuations and risk calculations.
+
+**Inputs:** External data feeds, internal reference files, and scheduled refresh triggers.
+
+**Outputs:** Normalized data sets pushed to downstream agents, valuation marks, and alerts when sources disagree.
+
+**Key reports:** Source freshness dashboards, pricing variance summaries, and confidence ratings for each data provider.
+
+**Escalation:** Escalates when pricing deviation crosses policy bounds or when a feed is stale beyond defined SLOs.
+
+## Accounting & Close Agent
+
+**Purpose:** Coordinate period close, enforcing sequencing (reconciliations before close), validating completeness, and publishing financial statements.
+
+**Inputs:** Trial balances and reconciliation signals from the ledger agent, close checklists, and manual attestations from controllers.
+
+**Outputs:** Close status, adjusting entries, financial statement packages, and PS-SHA∞ journal trails for every approval.
+
+**Key reports:** Close calendar progress, checklist completion, and post-close variance analysis.
+
+**Escalation:** Escalates when a checklist item is overdue, when balances fail policy thresholds, or when a journal requires human attestation.
+
+## Treasury & Liquidity Agent
+
+**Purpose:** Manage cash positions, liquidity buffers, and payment scheduling to satisfy operational needs while respecting policy.
+
+**Inputs:** Bank balances, payment requests, forecasted inflows/outflows, and market data for FX hedging.
+
+**Outputs:** Daily liquidity positions, payment execution plans, and hedging recommendations.
+
+**Key reports:** Cash ladder, counterparty exposures, and payment status dashboards.
+
+**Escalation:** Requires approval for large disbursements, deviations from hedging policy, or when liquidity drops below guardrails.
+
+## FP&A / Forecasting Agent
+
+**Purpose:** Produce rolling forecasts and scenario plans that inform budgeting and capital allocation.
+
+**Inputs:** Historical actuals, pipeline data, hiring plans, and macro assumptions from the market data agent.
+
+**Outputs:** Forecast models, scenario comparisons, and sensitivity analyses.
+
+**Key reports:** Budget vs. actuals, forecast accuracy tracking, and scenario deltas.
+
+**Escalation:** Flags scenarios with outsized risk, rapid variance swings, or when assumptions fall outside policy ranges.
+
+## Capital Budgeting Agent
+
+**Purpose:** Evaluate projects and investments, ensuring capital is deployed where expected return and risk align with strategy.
+
+**Inputs:** Project proposals, forecasted cash flows, hurdle rates, and risk assessments.
+
+**Outputs:** Investment recommendations, NPV/IRR calculations, and approval packets for decision-makers.
+
+**Key reports:** Pipeline of pending investments, approved vs. declined rationale, and portfolio performance over time.
+
+**Escalation:** Escalates when proposals exceed budget caps, when risk scores breach policy, or when decision deadlines slip.
+
+## Capital Structure & Funding Agent
+
+**Purpose:** Plan and monitor debt/equity mix, covenant compliance, and funding runway.
+
+**Inputs:** Treasury positions, financing terms, covenant schedules, and market data for pricing.
+
+**Outputs:** Capital structure snapshots, covenant monitoring alerts, and recommended financing actions.
+
+**Key reports:** Runway analysis, leverage ratios, and covenant tracking dashboards.
+
+**Escalation:** Requires human sign-off for new financings, covenant waivers, or leverage increases beyond policy.
+
+## Working Capital & Trade Credit Agent
+
+**Purpose:** Optimize receivables, payables, and inventory to maintain healthy working capital.
+
+**Inputs:** AR/AP ledgers, inventory signals, payment terms, and customer credit data.
+
+**Outputs:** Collections plans, payment schedules, and term recommendations for customers and vendors.
+
+**Key reports:** DSO/DPO trends, aging reports, and discount utilization.
+
+**Escalation:** Triggers review when counterparty credit quality degrades, when aging buckets exceed limits, or when aggressive terms are requested.
+
+Together these agents form the finance backbone. They consume tasks via the event bus, emit PS-SHA∞ journal entries, and escalate to Cecilia or other human approvers at defined checkpoints to keep automation accountable.

versioned_docs/version-v0.1/packs/finance/overview.mdx

@@ -0,0 +1,26 @@
+---
+id: finance-pack-overview
+title: Finance Pack Overview
+sidebar_position: 0
+slug: /packs/finance/overview
+---
+
+The Finance pack bundles treasury, invoicing, and reconciliation agents that speak the same PS-SHA∞ evidence language. It aligns with CFO and audit expectations while remaining composable.
+
+## Core personas
+
+- **Treasury coordinator** — reconciles cash positions, generates liquidity alerts, and triggers compliance checks.
+- **Billing agent** — issues invoices, tracks receipts, and posts updates to RoadChain for downstream reporting.
+- **Risk analyst** — watches event streams for anomalies and routes incidents to humans.
+
+## Operating guidance
+
+- Deploy alongside `blackroad-os-operator` to keep finance jobs near the event bus.
+- Surface pack metrics in Prism Console using the Finance dashboards.
+- Keep secrets and API tokens in your vault; bind them to agents via environment variables at runtime.
+
+## Extending the pack
+
+1. Add new finance agents to `agent-catalog/agents.yaml` with `pack: finance`.
+2. Include policies in `docs/governance-policy` when they impact approvals or segregation of duties.
+3. Update this overview with links to the generated agent pages.

versioned_docs/version-v0.1/packs/finance/pain-points.mdx

@@ -0,0 +1,24 @@
+---
+id: finance-pain-points
+title: Pain Points Summary
+slug: /packs/finance/pain-points
+sidebar_position: 2
+---
+
+BlackRoad OS targets the friction that comes from fragmented tooling, unverifiable automation, and opaque ROI. Use these talking points when aligning stakeholders or writing proposals.
+
+## Too many siloed dashboards
+- **Problem** — Operators juggle consoles for infra, agents, finance, and compliance with no shared view.
+- **BlackRoad OS response** — Prism Console aggregates operational health, finance signals, and events; API provides one consumable surface for custom views.
+
+## No unified audit trail across agents and infra
+- **Problem** — Actions taken by agents or scripts lack provenance and are hard to defend during audits.
+- **BlackRoad OS response** — DomainEvents and RoadChain provide a tamper-evident journal, anchored by PS-SHA∞ identities, and visible in Prism.
+
+## Difficulty quantifying automation/AI ROI
+- **Problem** — Automation is measured by anecdotes instead of accountable metrics.
+- **BlackRoad OS response** — Finance snapshots in Prism tie agent actions to costs and returns; events create traceable evidence for each outcome.
+
+## Manual ops & fragmented infrastructure
+- **Problem** — Deployments, DNS changes, and incident response require manual steps scattered across runbooks.
+- **BlackRoad OS response** — Operator-hosted agents (Atlas, infra bots) plus `blackroad-os-infra` blueprints centralize the path from request to action, with clear environments and rollbacks.

versioned_docs/version-v0.1/packs/finance/value-proposition.mdx

@@ -0,0 +1,25 @@
+---
+id: finance-value-proposition
+title: Value Proposition
+slug: /packs/finance/value-proposition
+sidebar_position: 1
+---
+
+BlackRoad OS is an orchestration platform—not just another AI tool. It fuses identity, auditability, and operational clarity so automation can be trusted and measured.
+
+## For individuals and creators
+- Launch agents with PS-SHA∞ anchors and know every action is journaled.
+- Use Prism Console to see what is running and why without wrangling infra dashboards.
+- Share RoadChain references to prove work happened when collaborating with clients.
+
+## For small teams
+- One API surface (`blackroad-os-api`) for system health, finance snapshots, and events.
+- Operator runtime keeps jobs consistent; agents like Atlas accelerate deployments and incident response.
+- Finance and audit visibility reduce the time spent explaining automation to stakeholders.
+
+## For enterprises and partners
+- Verified identity and truth layers enable compliance in regulated environments.
+- Tamper-evident RoadChain history plus Prism dashboards create defendable audit trails.
+- Clear stack map across Core, Operator, API, Prism, Web, and Infra shortens integration cycles and partner onboarding.
+
+Every audience benefits from the same promise: orchestrate confidently, prove what happened, and measure ROI with the evidence built in.

versioned_docs/version-v0.1/platform-guides/api/api-overview.mdx

@@ -0,0 +1,56 @@
+---
+id: api-overview
+title: API Overview
+slug: /platform/api/overview
+sidebar_position: 1
+---
+
+`blackroad-os-api` is the HTTP surface that external consumers, Prism Console, and automation call. It wraps Operator runtime data in a consistent envelope.
+
+## Envelope
+Every response returns:
+
+```json
+{
+  "ok": true,
+  "data": {"..."}
+}
+```
+
+When `ok` is `false`, expect an `error` object with a `code` and `message` instead of `data`.
+
+## Endpoints
+- `GET /api/v1/health` — liveness and readiness.
+- `GET /api/v1/system/overview` — summary of system health, agents, and version info.
+- `GET /api/v1/agents` — list registered agents.
+- `GET /api/v1/agents/:id` — inspect a specific agent, including state and last-seen metadata.
+- `GET /api/v1/finance/snapshot` — wallet balances, ROI snapshots, and agent cost rollups (where implemented).
+- `GET /api/v1/events` — paginated DomainEvents from the Operator runtime.
+- `GET /api/v1/roadchain/blocks` — grouped RoadChain blocks for audit references.
+
+### Example shapes (pseudocode)
+- **System overview**
+  ```json
+  {
+    "ok": true,
+    "data": {
+      "uptimeSeconds": 1234,
+      "agents": {"total": 3, "healthy": 3},
+      "jobs": {"queued": 2, "running": 1}
+    }
+  }
+  ```
+- **Agent detail**
+  ```json
+  {
+    "ok": true,
+    "data": {
+      "id": "atlas",
+      "psShaInfinity": "ps-sha∞-...",
+      "state": "ready",
+      "lastJob": {"id": "job-123", "status": "succeeded"}
+    }
+  }
+  ```
+
+Keep endpoints thin and stable: Operator is where jobs run; the API is the consumable contract for Prism, web, and partners.

versioned_docs/version-v0.1/platform-guides/api/extending-agents.mdx

@@ -0,0 +1,37 @@
+---
+id: api-extending-agents
+title: Extending Agents
+slug: /platform/api/extending-agents
+sidebar_position: 2
+---
+
+Adding a new agent to BlackRoad OS follows a predictable path so capabilities stay discoverable and auditable. Start with a clear problem statement, then wire the agent into the operator with the right journaling and escalation points.
+
+## Design
+
+Clarify what problem the agent solves, what systems it touches, and how success is measured. Define the capabilities it will expose and the tasks it should accept. Consider whether it needs human approval gates and how those are surfaced in Prism Console.
+
+## Define capabilities
+
+Add the agent to the operator’s registry (typically YAML) with its capabilities, input schemas, and escalation thresholds. Keep naming consistent with existing finance agents so orchestrators can route tasks predictably.
+
+## Implement the agent
+
+Create the stub class following the base agent interface (or finance-specific base classes). Implement capability handlers, emit PS-SHA∞ journal entries for meaningful actions, and add guardrails for policy or limit checks. Start with stubbed integrations before wiring real data sources.
+
+## Wire into orchestrators
+
+Update orchestrators to dispatch tasks to the new capabilities. Ensure event bus routing matches the registry and that failure modes are surfaced as events Prism Console can display. Add policy hooks for when human intervention is required.
+
+## Testing and docs
+
+Add unit and integration tests that validate capability behavior, journaling, and escalation triggers. Document assumptions, inputs, and outputs in the operator repo, then cross-link from this docs site. For examples, see the finance agents described in the [Finance Layer](/packs/finance/finance-layer).
+
+## Example: Notification Agent
+
+A simple Notification Agent might watch for anomalies and send alerts:
+
+1. Define a `notify` capability in the registry with inputs for subject, body, and recipients.
+2. Implement the agent to format messages and post to email or chat systems, emitting journal entries for traceability.
+3. Add orchestration rules to throttle or escalate when alerts relate to regulated actions.
+4. Document configuration knobs and link them from [Local Development](/platform/core/local-development) so others can reproduce behavior.

versioned_docs/version-v0.1/platform-guides/core/agents-atlas-and-friends.mdx

@@ -0,0 +1,31 @@
+---
+id: agents-atlas-and-friends
+title: Agents – Atlas and Friends
+slug: /platform/core/agents-atlas-and-friends
+sidebar_position: 6
+---
+
+Agents are the workers inside BlackRoad OS. Each agent is registered in Operator, anchored with PS-SHA∞ identity data, and consumes jobs through a shared contract defined in `blackroad-os-core`.
+
+## What makes an agent
+- **Identity** — PS-SHA∞ anchor ties the agent to an auditable worldline.
+- **Metadata** — capabilities, version, and contact points (e.g., supported job kinds).
+- **State** — lifecycle data surfaced to Prism and API (ready, busy, degraded, disabled).
+- **Context** — `AgentContext` carries configuration, environment handles, and journal access for emitting events.
+
+## Atlas (today)
+- Ops-aware assistant focused on running and debugging the OS itself.
+- Can inspect agents, jobs, and environment wiring; ideal for incident support and deployment validation.
+- Emits DomainEvents for every action so the RoadChain trail stays intact.
+
+## Future agents (examples)
+- **Lucidia** — exploratory or research-heavy agent.
+- **Finance agents** — ledgering, forecasting, treasury actions.
+- **Infra agents** — provisioning or DNS updates under strict guardrails.
+
+## Registration and surfacing
+- Agents register with Operator, which keeps the registry exposed at `/internal/agents` and to the API layer.
+- Jobs target agents by ID or capability; Operator enforces lifecycle transitions and emits events on every change.
+- Prism renders agent state directly from the API, so agents should keep metadata and health signals current.
+
+If you are building a new agent, start with the core types, emit DomainEvents consistently, and ensure PS-SHA∞ anchors are present so RoadChain can prove the agent’s lineage.

versioned_docs/version-v0.1/platform-guides/core/core-primitives.mdx

@@ -0,0 +1,36 @@
+---
+id: core-primitives
+title: Core Primitives
+slug: /platform/core/primitives
+sidebar_position: 4
+---
+
+`blackroad-os-core` holds the shared types and helpers that every other repository uses. Keep these primitives stable: they shape how agents, jobs, events, and truth states are expressed everywhere else.
+
+## Result helpers
+- `Result<T, E>` — functional success/error envelope.
+- `ok(value)` — wrap a success value.
+- `err(error)` — wrap an error while preserving type information.
+
+## Identity
+- `PsShaInfinity` — identity anchor that binds an entity to a verifiable worldline.
+- `IdentityAnchor` — concrete anchor instance containing the PS-SHA∞ hash and metadata.
+- `IdentityKind` — enum describing whether the anchor is a human, agent, asset, or service.
+
+## Truth pipeline
+- `TextSnapshot` — immutable text input captured for verification.
+- `VerificationJob` — request to assess a snapshot; typically executed by an agent like Atlas.
+- `AgentAssessment` — agent-produced judgment about the snapshot.
+- `TruthState` — aggregated result (affirmed, disputed, retracted) plus minority reports.
+
+## Events & journaling
+- `DomainEvent` — canonical event wrapper for runtime transitions and job outcomes.
+- `JournalEntry` — persisted record of an event, ready to be grouped into RoadChain blocks.
+- `RoadChainBlock` — hash-linked bundle of journal entries with block metadata for audit.
+
+## Agents & jobs
+- `Agent`, `AgentContext`, `AgentMetadata`, `AgentState` — shape how agents are registered, invoked, and tracked.
+- `Job`, `JobStatus` — lifecycle states for work items.
+- Lifecycle helpers such as `startJob`, `completeJob`, and `failJob` enforce consistent transitions and event emission.
+
+Use these primitives instead of ad-hoc types so Prism, API, Operator, and future agents (including Atlas and Lucidia) see the same worldview.

versioned_docs/version-v0.1/platform-guides/core/events-and-roadchain.mdx

@@ -0,0 +1,29 @@
+---
+id: events-and-roadchain
+title: Events and RoadChain
+slug: /platform/core/events-and-roadchain
+sidebar_position: 5
+---
+
+Events are the connective tissue of BlackRoad OS. They describe what happened, when, and which identities were involved. RoadChain turns those events into an auditable, hash-linked journal.
+
+## DomainEvents
+- Emitted by the Operator runtime whenever jobs or agents change state.
+- Carry references to agents, jobs, PS-SHA∞ anchors, and contextual metadata.
+- Intended for both real-time consumption (Prism dashboards) and long-term audit.
+
+## Journal entries
+- Every DomainEvent is persisted as a `JournalEntry` with timestamps and signatures.
+- Journal entries are immutable; corrections are additive via new events, not edits.
+
+## RoadChain blocks
+- RoadChain groups journal entries into ordered blocks.
+- Each block is hash-linked to the previous one for tamper evidence.
+- Blocks can be referenced in incident reports, finance audits, or investor updates to prove lineage of actions.
+
+## How Prism will visualize it
+- **Events feed** — chronological list with filters for agent, job, severity, or identity.
+- **RoadChain explorer** — block-level view showing grouped journal entries, hashes, and linked metadata.
+- **Tracebacks** — follow a job through events to the block where it was sealed.
+
+Keep the event schema tight and reuse core types so every surface (Operator logs, API responses, Prism, future wallets) can rely on the same vocabulary.

versioned_docs/version-v0.1/platform-guides/core/local-development.mdx

@@ -0,0 +1,27 @@
+---
+id: local-development
+title: Local Development
+sidebar_position: 7
+slug: /platform/core/local-development
+---
+
+Use this checklist to spin up the BlackRoad OS stack locally. It assumes you cloned the repositories into a common directory and have Node.js 20+, npm or pnpm, git, and Docker available.
+
+## Setup steps
+
+1. Clone the repos you need: `blackroad-os-core`, `blackroad-os-operator`, `blackroad-os-api`, `blackroad-os-prism-console`, `blackroad-os-web`, and this docs repo.
+2. Install dependencies in each repo (`npm install` or `pnpm install`). Keep versions aligned with the `.nvmrc` or `engines` fields if present.
+3. If `blackroad-os-core` provides a runtime, start it or ensure its libraries are built for downstream consumers.
+4. Start the operator to host agents. Finance agents can run in stub mode until you hook them to live data sources.
+5. Launch the API, typically binding to a port in the 4000–5000 range. Load any required environment variables (database URIs, secrets, base URLs).
+6. Run Prism Console with `NEXT_PUBLIC_API_BASE_URL` pointing to your API instance. Visit `/dashboard` or `/finance` to confirm connectivity.
+7. Optionally run the Web app for the marketing experience and to verify documentation links.
+8. Run this docs site via `npm run start` to keep guidance close at hand.
+
+## Stubbing dependencies
+
+Not every integration must be live during local development. Use mock data for bank feeds, sandbox queues for events, and stub implementations of PS-SHA∞ when cryptographic anchoring is not necessary. Document your choices in pull requests so other contributors understand the assumptions.
+
+## Next steps
+
+When comfortable, explore [Extending Agents](/platform/api/extending-agents) to add new capabilities. Cross-reference environment settings in [Infra Environments](/platform/operator/environments) before deploying anything beyond dev, and consult [Deployments & Runbooks](/platform/operator/deployments-and-runbooks) for rollout discipline.

versioned_docs/version-v0.1/platform-guides/core/platform-overview.mdx

@@ -0,0 +1,33 @@
+---
+id: platform-overview
+title: BlackRoad OS Overview
+slug: /platform/core/overview
+sidebar_position: 1
+---
+
+BlackRoad OS is an orchestration operating system that connects identity, truth, runtime, and interfaces into one verifiable loop. Each layer is explicit so operators, developers, partners, and future agents can see where a capability belongs and how evidence is captured.
+
+## Layers at a glance
+- **Identity layer** — PS-SHA∞ anchors tie people, agents, and assets to stable worldlines.
+- **Truth layer** — verification jobs, truth states, and minority reports produce a defendable view of reality.
+- **Runtime layer** — `blackroad-os-operator` runs agents (Atlas and future peers), jobs, and emits DomainEvents; `blackroad-os-api` exposes a stable HTTP surface for everything outside the runtime.
+- **Interface layer** — Prism Console for operators, `blackroad-os-web` for the public shell, and future inbox/roadmail surfaces.
+- **Infra layer** — DNS, environments, deployment pipelines, and observability defined in `blackroad-os-infra`.
+- **Audit layer** — RoadChain journal blocks hash-link the event stream for tamper-evident history.
+
+### Flow of work
+```
+Text / task → Operator → Agent(s) → DomainEvents → Journal entries → RoadChain blocks → Prism & Web
+```
+
+1. A prompt, task, or webhook enters the system.
+2. Operator routes it to one or more agents, each anchored by PS-SHA∞ identities.
+3. Agents execute jobs, emit DomainEvents, and store journal entries.
+4. RoadChain groups journal entries into hash-linked blocks for auditability.
+5. Prism Console and the public web surfaces visualize state, finance, and evidence.
+
+## How to read this layer cake
+- Start with the [Stack Map](./stack-map) to see the repositories and what layer they belong to.
+- Review [Seasons Overview](./seasons) to understand the roadmap and current phase.
+- Operators should continue to the [Prism Console](/platform/prism-console/overview) and [Infra Guide](/platform/operator/infra-guide).
+- Developers should read [Core Primitives](/platform/core/primitives) and [API Overview](/platform/api/overview) next.

versioned_docs/version-v0.1/platform-guides/core/repos-and-services.mdx

@@ -0,0 +1,36 @@
+---
+id: repos-and-services
+title: Repos & Services
+sidebar_position: 8
+slug: /platform/core/repos-and-services
+---
+
+The BlackRoad OS ecosystem is intentionally modular. Each repository owns a specific responsibility so teams can iterate independently while sharing common primitives like events, capabilities, and journaling. Use this map to understand where to look when debugging or extending the platform.
+
+## Core (`blackroad-os-core`)
+
+Holds domain models (`Agent`, `Capability`, `Task`, `Event`, `JournalEntry`), event bus abstractions, and the PS-SHA∞ interface. Everything else depends on these contracts.
+
+## Operator (`blackroad-os-operator`)
+
+Hosts agents and orchestrators. Finance agents live here alongside scheduling logic and escalation rules. Registries describe capabilities so orchestration remains declarative.
+
+## API (`blackroad-os-api`)
+
+Exposes public HTTP endpoints for metrics, task submission, and finance controls. It mediates between external callers and the operator while enforcing authentication and policy.
+
+## Prism Console (`blackroad-os-prism-console`)
+
+Provides dashboards for agents, events, and finance workflows. It consumes the API and requires `NEXT_PUBLIC_API_BASE_URL` to be configured per environment.
+
+## Web (`blackroad-os-web`)
+
+The marketing and public storytelling site. It links visitors to documentation and captures interest without exposing internal control surfaces.
+
+## Infra (`blackroad-os-infra`)
+
+Terraform modules, environment definitions, DNS, networking, and runbooks. It keeps deployments consistent and auditable across dev, staging, and prod.
+
+## Docs (`blackroad-os-docs`)
+
+This repository. It aggregates architecture, developer, operator, and compliance guidance so contributors have a single source of truth. For local setup, see [Local Development](/platform/core/local-development).

versioned_docs/version-v0.1/platform-guides/core/seasons-overview.mdx

@@ -0,0 +1,21 @@
+---
+id: platform-seasons
+title: Seasons Overview
+slug: /platform/core/seasons
+sidebar_position: 3
+---
+
+Seasons describe the architecture phases BlackRoad OS moves through. They keep every repository aligned on the same goals and ensure the infra season tracker can reflect progress across codebases.
+
+## How Seasons work
+- A **Season** captures a thematic milestone with clear goals, expected changes to the stack, and cross-repo implications.
+- Season checkpoints are mirrored in `blackroad-os-infra` (environment definitions, DNS, deployment plans) and should be referenced before landing any major change.
+- Each repo should note which Season its default branch targets; unfinished work can live behind flags or feature branches.
+
+## Season snapshots
+- **Season 0–1: Genesis / OS Skeleton** — establish PS-SHA∞ identity types, core Result helpers, initial Operator runtime, and minimal API to expose health.
+- **Season 2: Multi-repo cohesion (current)** — align Core, Operator, API, Prism Console, Infra, and Docs with shared language and event shapes; stand up RoadChain journaling.
+- **Season 3: Intelligence Layer** — expand agent registry (Atlas, Lucidia), richer verification jobs, and tighter Prism insights for agents and finance.
+- **Season 4+: Ecosystem** — public RoadChain visibility, wallets, demos/worlds, and broader partner integrations.
+
+When in doubt, check the Season tracker in `blackroad-os-infra` and mirror the labels here so future contributors and agents know the current operating context.

versioned_docs/version-v0.1/platform-guides/core/stack-map.mdx

@@ -0,0 +1,26 @@
+---
+id: platform-stack-map
+title: Stack Map
+slug: /platform/core/stack-map
+sidebar_position: 2
+---
+
+The stack is intentionally split across focused repositories while sharing vocabulary and event types. Use this table to quickly align components, responsibilities, and maturity.
+
+| Name | Repository | Layer | Description | Status |
+| --- | --- | --- | --- | --- |
+| Core | `blackroad-os-core` | Core / Domain primitives | Result helpers, PS-SHA∞ identity types, events, truth pipeline models, job lifecycle helpers. | Alpha |
+| Operator | `blackroad-os-operator` | Runtime / Agents & jobs | Runs agents (Atlas and more), manages queues, emits DomainEvents, exposes `/internal/*` for orchestration. | Alpha |
+| API | `blackroad-os-api` | Runtime / HTTP surface | Public HTTP surface for system overview, agents, finance snapshots, events, and RoadChain blocks. | Alpha |
+| Prism Console | `blackroad-os-prism-console` | Interface / Ops | Operator-facing cockpit for system health, agents, finance, events, and future inbox/roadmail. | Alpha |
+| Web | `blackroad-os-web` | Interface / Public | Public-facing shell that tells the BlackRoad OS story. | Planned |
+| Infra | `blackroad-os-infra` | Infra / Environments | DNS, environments, Railway, and deployment blueprints plus runbooks and season tracker. | In-flight |
+| Docs | `blackroad-os-docs` | Docs / Canonical hub | This site—the authoritative documentation for architecture, operations, and business context. | In-flight |
+| Agents | `blackroad-os-operator` (registry) | Agents / Runtime | Atlas (ops-aware assistant) today; Lucidia and other agents planned. Anchored with PS-SHA∞ identities. | Alpha |
+| Brand | `blackroad-os-brand` | Brand / Narrative | Visual system, storytelling, and investor-facing material. | Planned |
+| Home | `blackroad-os-home` | Content / Handbook | Long-form essays, product thinking, and handbook references. | Planned |
+| Ideas | `blackroad-os-ideas` | Research / Backlog | Experimentation space and design spikes. | Planned |
+| Demo | `blackroad-os-demo` | Demos / Worlds | Example worlds and demo scenarios for partners. | Planned |
+| Research | `blackroad-os-research` | Exploration / Labs | Deeper R&D that may graduate into the core stack. | Planned |
+
+Keep descriptions short and consistent. When a repo crosses layers, list its primary responsibility first and note secondary roles inline.

versioned_docs/version-v0.1/platform-guides/operator/deployments-and-runbooks.mdx

@@ -0,0 +1,22 @@
+---
+id: operator-deployments-and-runbooks
+title: Deployments & Runbooks
+sidebar_position: 5
+slug: /platform/operator/deployments-and-runbooks
+---
+
+Deployment, incident, and maintenance runbooks live alongside Terraform in `blackroad-os-infra/runbooks`. They capture repeatable procedures so operators can move quickly without skipping safety gates. This page summarizes the flow; always defer to the runbook for environment-specific commands.
+
+## Deployment flow
+
+- Prepare infrastructure changes in `blackroad-os-infra`, pairing them with any service releases that depend on new resources.
+- Apply to `dev` first, validate health checks, then promote to `staging` and `prod` with human sign-off recorded via PS-SHA∞ entries.
+- Coordinate app releases (API, Operator, Prism Console, Web) so API contracts and agent expectations stay aligned across environments.
+
+## Incident runbooks
+
+Incident runbooks describe detection, triage, rollback, and communication steps. They lean on event streams and journal data to reconstruct timelines quickly. TODO: link specific incident playbooks once codified.
+
+## Maintenance
+
+Maintenance runbooks cover certificate rotation, database upgrades, and other periodic tasks. Only authorized operators should apply Terraform or modify shared secrets. When changes intersect with finance agents or regulated data, ensure approvals from the designated human orchestrator before proceeding.

versioned_docs/version-v0.1/platform-guides/operator/dns-and-networking.mdx

@@ -0,0 +1,23 @@
+---
+id: operator-dns-and-networking
+title: DNS & Networking
+sidebar_position: 3
+slug: /platform/operator/dns-and-networking
+---
+
+DNS is managed through Cloudflare with a consistent pattern per environment. Each service receives a predictable subdomain so operators, agents, and external users know where to reach it. Terraform modules in `blackroad-os-infra` own zone records, TLS settings, and any required tunnels.
+
+## Base strategy
+
+- Root zones exist for production and environment-specific subdomains (e.g., `blackroad.systems`, `dev.blackroad.systems`, `stg.blackroad.systems`).
+- Service records follow a consistent pattern, typically `<service>.<env>.blackroad.systems`.
+- Cloudflare handles TLS termination and security policies, with origin servers pinned to known IPs or load balancers.
+
+## Adding a new service
+
+1. Define the DNS record in the `dns` module within `blackroad-os-infra`, specifying the environment and target.
+2. Associate the record with the appropriate service module so that infrastructure and DNS changes roll out together.
+3. Apply the Terraform changes for the desired environment after peer review and required approvals.
+4. Validate propagation and health checks before advertising the new endpoint to agents or users.
+
+Networking relies on consistent CIDR allocations and security groups defined in infra modules. Coordinate with the infra team when introducing new ingress/egress paths or when agents need to reach sensitive systems. For deployment choreography, see [Deployments & Runbooks](/platform/operator/deployments-and-runbooks).

versioned_docs/version-v0.1/platform-guides/operator/environments.mdx

@@ -0,0 +1,24 @@
+---
+id: operator-environments
+title: Environments
+sidebar_position: 4
+slug: /platform/operator/environments
+---
+
+BlackRoad OS is deployed across three environments that share Terraform modules but differ in usage and change cadence. The `blackroad-os-infra` repository holds the definitions under `envs/`, keeping configuration predictable and reviewable.
+
+| Environment | Purpose | URL Example |
+|------------|---------------------|---------------------------------|
+| dev | Experiments | `*.dev.blackroad.systems` |
+| staging | Pre-production | `*.stg.blackroad.systems` |
+| prod | Live customer usage | `*.blackroad.systems` |
+
+## How the environments are structured
+
+Each environment directory defines its own variables, state backend, and service maps. Shared modules handle DNS, networking, and cluster bootstrapping to minimize drift. Promotion follows a dev → staging → prod flow, with change windows and approvals tracked through PS-SHA∞ journal entries.
+
+## Working with envs
+
+When introducing a new service, add it to the relevant environment definitions and ensure DNS entries are present (see [DNS & Networking](/platform/operator/dns-and-networking)). Use Terraform workspaces or separate state files as defined in `blackroad-os-infra` to avoid collisions. Apply changes in dev first, validate health checks, then promote to staging and prod with the appropriate human approvals.
+
+Runbooks for deploying and verifying updates live in `blackroad-os-infra/runbooks`. Coordinate with operators when changes affect shared resources like VPCs, certificates, or secrets. TODO: add direct links to specific runbooks once the directory is finalized.

versioned_docs/version-v0.1/platform-guides/operator/infra-guide.mdx

@@ -0,0 +1,22 @@
+---
+id: operator-infra-guide
+title: Infra Guide
+slug: /platform/operator/infra-guide
+sidebar_position: 2
+---
+
+Infrastructure definitions live in `blackroad-os-infra`. This guide orients operators to the core references rather than duplicating them here.
+
+## Where to look
+- **Service registry** — canonical list of services, ports, and dependencies. Use it to align `NEXT_PUBLIC_API_BASE_URL`, API origins, and Operator endpoints.
+- **Environment config** — dev/staging/prod settings, secrets management approach, and expected DNS names per environment.
+- **DNS blueprint** — Cloudflare/registrar mappings and how services are exposed externally.
+- **Deployment runbooks** — Railway or other deployment steps, rollback procedures, and incident checklists.
+- **Season tracker** — authoritative source for which repositories are in which Season.
+
+## How this repo uses infra
+- Docs are static and built with Docusaurus, but they should mirror environment naming and base URLs used across the stack.
+- When adding examples that reference services, match the ports and hostnames from the service registry to avoid drift.
+- Incidents or outages should point to RoadChain blocks or event IDs plus the runbooks stored in `blackroad-os-infra`.
+
+Treat infra as shared contract: changes there should ripple into Prism configuration, API origins, and any URLs mentioned in these docs.

versioned_docs/version-v0.1/platform-guides/operator/operator-runtime.mdx

@@ -0,0 +1,30 @@
+---
+id: operator-runtime
+title: Operator Runtime
+slug: /platform/operator/runtime
+sidebar_position: 1
+---
+
+`blackroad-os-operator` is the runtime where agents live, jobs run, and DomainEvents originate. It coordinates work, keeps a registry of agents, and exposes internal HTTP routes for orchestration tools.
+
+## Responsibilities
+- Host agents (Atlas and future peers) with PS-SHA∞ identity anchors and metadata.
+- Manage the job queue, lifecycle transitions, and worker loop that executes tasks.
+- Emit DomainEvents and persist journal entries for every notable state change.
+- Provide `/internal/*` HTTP endpoints for health checks, orchestration, and debugging.
+
+## Core concepts
+- **Agent Registry** — catalog of agents with IDs, capabilities, and state; used by Prism and the API.
+- **Job Queue** — accepted work items with statuses (`queued`, `running`, `succeeded`, `failed`, `cancelled`).
+- **Worker loop** — pulls jobs from the queue, runs the chosen agent, and records results plus events.
+- **EventBus & JournalStore** — emit DomainEvents and capture journal entries that ultimately roll into RoadChain blocks.
+
+## Example internal endpoints
+- `GET /internal/health` — runtime liveness.
+- `GET /internal/agents` — list registered agents.
+- `GET /internal/agents/:id` — inspect a specific agent, including PS-SHA∞ identity data.
+- `POST /internal/jobs` — submit a job to the queue.
+- `GET /internal/jobs/:id` — check job status.
+- `GET /internal/events` — stream or page through recent DomainEvents.
+
+Types come from `blackroad-os-core`. Keep Operator thin: it runs agents and emits events, while `blackroad-os-api` is the only HTTP surface intended for external consumers.

versioned_docs/version-v0.1/platform-guides/prism-console/prism-console-legacy.mdx

@@ -0,0 +1,27 @@
+---
+id: prism-console-legacy
+title: Prism Console (Legacy)
+slug: /platform/prism-console/legacy
+sidebar_position: 2
+---
+
+# Prism Console
+
+Prism Console is the operator-facing UI for BlackRoad OS. It surfaces agent health, finance workflows, and event streams so humans can supervise automation. The console connects to `blackroad-os-api` and relies on that service for data freshness and authorization.
+
+## Pages
+
+- **Dashboard:** High-level status across agents, environments, and active tasks.
+- **Agents:** Inventory of agents and capabilities, including health signals and recent activity.
+- **Finance:** Views tailored for the finance layer—close progress, ledger snapshots, and treasury positions.
+- **Events:** Stream of recent events and journal entries to trace actions and debug issues.
+
+## Configuration
+
+Set `NEXT_PUBLIC_API_BASE_URL` to the API endpoint for your environment before starting the console. For local development, point it at the API port you started from [Local Development](/platform/core/local-development). Ensure CORS and auth settings on the API side permit console access.
+
+## Usage
+
+Start the API and operator, then run Prism Console. Navigate to `/dashboard` for overall health or `/finance` to check the finance agents. Use event views to confirm that PS-SHA∞ journal entries are flowing as expected. TODO: add screenshots once the UI stabilizes.
+
+> This page is legacy. See the updated [Prism Console guide](/platform/prism-console/overview) for the v1 docs home experience.

versioned_docs/version-v0.1/platform-guides/prism-console/prism-console.mdx

@@ -0,0 +1,42 @@
+---
+id: prism-console
+title: Prism Console
+slug: /platform/prism-console/overview
+sidebar_position: 1
+---
+
+Prism Console is the operator-facing cockpit for BlackRoad OS. It brings system status, agent state, finance visibility, and the RoadChain event stream into one UI so an orchestrator can act quickly and with evidence.
+
+## What Prism Console covers
+- **Dashboard** — high-level health, pending jobs, recent truth state changes, and alerts from the Operator runtime.
+- **Agents** — registry view of Atlas and future agents, including PS-SHA∞ anchors, current jobs, and state transitions.
+- **Finance** — wallet/treasury snapshot, ROI views, and agent cost attribution where available.
+- **Events / RoadChain Explorer** — chronological DomainEvents, journal entries, and RoadChain blocks with search and filters.
+- **Future pages** — Inbox/RoadMail, Hardware/Nodes, and Operator Chat are planned as the runtime expands.
+
+## How it talks to the API
+Prism is a Next.js app that reads from `blackroad-os-api`. Configure the base URL via:
+
+```bash
+NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
+```
+
+Typical endpoints consumed:
+- `GET /api/v1/system/overview`
+- `GET /api/v1/agents`
+- `GET /api/v1/agents/:id`
+- `GET /api/v1/finance/snapshot`
+- `GET /api/v1/events`
+- `GET /api/v1/roadchain/blocks`
+
+## Running locally
+1. Start `blackroad-os-api` (or point at a deployed instance) and ensure CORS is configured for the console host.
+2. Set `NEXT_PUBLIC_API_BASE_URL` to the API origin.
+3. Run `npm install && npm run dev` inside `blackroad-os-prism-console`.
+4. Log in or load the dashboard; confirm the agents and finance panels populate.
+
+## Reading the dashboards
+- Treat the **Dashboard** as your pulse: spikes in failed jobs or truth retractions should drive investigation.
+- Use **Agents** to verify Atlas (or others) are registered and emitting events; cross-check IDs against PS-SHA∞ anchors.
+- The **Finance** tab is the bridge between operations and ROI; if numbers look wrong, check the event stream for missing ledger entries.
+- The **Events / RoadChain Explorer** is the audit trail. When filing incidents or compliance reports, capture block references instead of screenshots alone.

versioned_docs/version-v0.1/reference/architecture/agents-and-orchestration.mdx

@@ -0,0 +1,25 @@
+---
+id: architecture-agents-and-orchestration
+title: Agents and Orchestration
+sidebar_position: 2
+slug: /reference/architecture/agents-and-orchestration
+---
+
+Agents are the atomic workers inside BlackRoad OS. Each agent advertises capabilities, consumes tasks through the event bus, and emits journal entries for every significant action. The intent is to keep agents composable and observable so humans can inspect, approve, or override critical steps without rewriting code paths.
+
+## Core concepts
+
+- **Agent** – a unit that owns business logic, typically bound to a narrow domain such as ledgering or treasury. Agents may run standalone or inside orchestrators.
+- **Capability** – a declared operation an agent can perform. Capabilities make routing explicit and let orchestrators compose complex flows.
+- **Task** – a discrete piece of work, such as “run monthly close.” Tasks carry metadata, initiator context, and expected outputs.
+- **Event Bus** – transports tasks and events between producers and consumers. It decouples initiators from workers and keeps journaling central.
+
+## Walkthrough: Run Monthly Close
+
+1. A scheduler or external caller creates a “Run Monthly Close” task through `blackroad-os-api`.
+2. The task is dispatched onto the event bus with a requested capability and scope (entity, period, currency).
+3. Finance agents in `blackroad-os-operator` pull the task, coordinate ledger checks, and produce working entries.
+4. Every state transition emits events and PS-SHA∞ journal entries so downstream systems and auditors can trace actions.
+5. When human sign-off is required, the orchestrator escalates to the appropriate approver before closing the loop.
+
+The same pattern applies to incident response, treasury moves, and infrastructure changes. For a catalog of finance-specific agents, see the [Finance Layer](/packs/finance/finance-layer). To extend the system with new automations, follow the guidance in [Extending Agents](/platform/api/extending-agents).

versioned_docs/version-v0.1/reference/architecture/overview.mdx

@@ -0,0 +1,33 @@
+---
+id: architecture-overview
+title: Architecture Overview
+sidebar_position: 1
+slug: /reference/architecture/overview
+---
+
+BlackRoad OS is organized into a small set of collaborating services that work together to deliver AI-led operations with human oversight. Each component owns a clear domain boundary and communicates through events, APIs, and shared journaling. Understanding these responsibilities helps contributors reason about changes without losing sight of compliance and observability goals.
+
+## Logical components
+
+- **Core (`blackroad-os-core`)** – defines domain models such as `Agent`, `Capability`, `Task`, `Event`, and `JournalEntry`. It contains the event bus abstraction and the PS-SHA∞ journaling interface used by every runtime participant.
+- **Operator (`blackroad-os-operator`)** – hosts finance, infra, and future agents. It provides orchestrators that chain capabilities together and manage agent lifecycle, scheduling, and escalation.
+- **API (`blackroad-os-api`)** – the public HTTP API exposing OS metrics, task submission, and finance controls. It is the main entry point for external callers and the Prism Console.
+- **Prism Console (`blackroad-os-prism-console`)** – administrative UI that surfaces agent health, finance workflows, and event streams to operators.
+- **Web (`blackroad-os-web`)** – marketing and public-facing site that communicates the platform story.
+- **Infra (`blackroad-os-infra`)** – Terraform modules, environment definitions, DNS, and runbooks that bind the ecosystem to cloud resources.
+
+## Data flow at a glance
+
+```
+User / Orchestrator -> Web (marketing) -> (optional) Docs
+           |                               \
+           |                                \
+           v                                 v
+        Prism Console  <-->  API  <-->  Operator & Agents
+           ^                                 |
+           |                                 v
+         Observability & Journaling (PS-SHA∞)
+Infra (DNS, networking, environments) underpins every service
+```
+
+Core primitives flow through the Operator and API: tasks are emitted onto the event bus, agents claim work, and every significant action emits a journal entry. Prism Console consumes the API and stream endpoints to present live state, while Infra ensures each environment is consistent and auditable. For deeper agent mechanics, see [Agents and Orchestration](/reference/architecture/agents-and-orchestration); for finance-specific behavior, head to the [Finance Layer](/packs/finance/finance-layer).