Add v1 docs home and audience guides

README.md

@@ -1,6 +1,8 @@
 # BlackRoad OS Docs
 
-This repository powers the BlackRoad OS documentation site built with **Docusaurus v2**. It is the central hub for architecture, agents, finance automation, infrastructure, developer workflows, and compliance guidance.
+This repository hosts the **official documentation hub** for BlackRoad OS. It aligns architecture language, operational guidance, developer surfaces, and business context across the stack while participating in the shared **"BlackRoad OS - Master Orchestration"** project.
+
+Built with **Docusaurus v3**, the site lives at the docs root (`routeBasePath: '/'`) and mirrors the same components found in `blackroad-os-core`, `blackroad-os-operator`, `blackroad-os-api`, `blackroad-os-prism-console`, `blackroad-os-web`, and `blackroad-os-infra`.
 
 ## Running the docs locally
 
@@ -21,9 +23,10 @@ npm run serve
 `npm run serve` serves the static build locally for validation.
 
 ## Where to start
+- [Docs Home](docs/index.md) — choose your path for operating, building, or understanding the OS.
+- [Stack Map](docs/overview/STACK_MAP.md) — repositories mapped to layers and status.
+- [Prism Console](docs/ops/PRISM_CONSOLE.md) — cockpit for operators.
+- [Core Primitives](docs/dev/CORE_PRIMITIVES.md) — shared domain types for agents, jobs, and events.
 
-- [Introduction](docs/intro.md) – welcome and quick orientation.
+## Contributing
-- [Architecture Overview](docs/architecture/overview.md) – how services fit together.
+Keep content concise, link across sections, and prefer iterative updates over monolithic rewrites. Mark components as planned/alpha/in-flight when appropriate so operators, developers, and partners have an honest view of the system.
-- [Finance Layer](docs/architecture/finance-layer.md) – catalog of finance agents and their responsibilities.
-
-Contributions are welcome. Keep content concise, link across sections, and add TODOs where deeper technical details will follow.

docs/business/PAIN_POINTS_SUMMARY.md

@@ -0,0 +1,23 @@
+---
+id: business-pain-points
+title: Pain Points Summary
+slug: /business/pain-points
+---
+
+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.

docs/business/VALUE_PROPOSITION.md

@@ -0,0 +1,24 @@
+---
+id: business-value-proposition
+title: Value Proposition
+slug: /business/value-proposition
+---
+
+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.

docs/dev/AGENTS_ATLAS_AND_FRIENDS.md

@@ -0,0 +1,30 @@
+---
+id: dev-agents-atlas-and-friends
+title: Agents – Atlas and Friends
+slug: /dev/agents-atlas-and-friends
+---
+
+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.

docs/dev/API_OVERVIEW.md

@@ -0,0 +1,55 @@
+---
+id: dev-api-overview
+title: API Overview
+slug: /dev/api-overview
+---
+
+`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.

docs/dev/CORE_PRIMITIVES.md

@@ -0,0 +1,35 @@
+---
+id: dev-core-primitives
+title: Core Primitives
+slug: /dev/core-primitives
+---
+
+`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.

docs/dev/EVENTS_AND_ROADCHAIN.md

@@ -0,0 +1,28 @@
+---
+id: dev-events-and-roadchain
+title: Events and RoadChain
+slug: /dev/events-and-roadchain
+---
+
+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.

docs/index.md

@@ -0,0 +1,34 @@
+---
+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/meta/ARCHITECTURE_DECISIONS.md

@@ -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.

docs/meta/GLOSSARY.md

@@ -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`.

docs/ops/INFRA_GUIDE.md

@@ -0,0 +1,21 @@
+---
+id: ops-infra-guide
+title: Infra Guide
+slug: /ops/infra-guide
+---
+
+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.

docs/ops/OPERATOR_RUNTIME.md

@@ -0,0 +1,29 @@
+---
+id: ops-operator-runtime
+title: Operator Runtime
+slug: /ops/operator-runtime
+---
+
+`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.

docs/ops/PRISM_CONSOLE.md

@@ -0,0 +1,41 @@
+---
+id: ops-prism-console
+title: Prism Console
+slug: /ops/prism-console
+---
+
+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.

docs/ops/prism-console.md

@@ -1,3 +1,9 @@
+---
+id: ops-prism-console-legacy
+title: Prism Console (Legacy)
+slug: /ops/prism-console-legacy
+---
+
 # 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.
@@ -16,3 +22,5 @@ Set `NEXT_PUBLIC_API_BASE_URL` to the API endpoint for your environment before s
 ## 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.

docs/overview/BLACKROAD_OS_OVERVIEW.md

@@ -0,0 +1,32 @@
+---
+id: overview-blackroad-os-overview
+title: BlackRoad OS Overview
+slug: /overview/blackroad-os-overview
+---
+
+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](../ops/prism-console) and [Infra Guide](../ops/infra-guide).
+- Developers should read [Core Primitives](../dev/core-primitives) and [API Overview](../dev/api-overview) next.

docs/overview/SEASONS_OVERVIEW.md

@@ -0,0 +1,20 @@
+---
+id: overview-seasons
+title: Seasons Overview
+slug: /overview/seasons
+---
+
+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.

docs/overview/STACK_MAP.md

@@ -0,0 +1,25 @@
+---
+id: overview-stack-map
+title: Stack Map
+slug: /overview/stack-map
+---
+
+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.

docusaurus.config.ts

@@ -52,24 +52,25 @@ const config: Config = {
         {
           title: 'BlackRoad OS',
           items: [
-            {label: 'Architecture', to: '/architecture/overview'},
+            {label: 'Docs Home', to: '/'},
-            {label: 'Finance Layer', to: '/architecture/finance-layer'},
+            {label: 'Stack Map', to: '/overview/stack-map'},
+            {label: 'Seasons Overview', to: '/overview/seasons'},
+          ],
+        },
+        {
+          title: 'Operate the OS',
+          items: [
             {label: 'Prism Console', to: '/ops/prism-console'},
+            {label: 'Operator Runtime', to: '/ops/operator-runtime'},
+            {label: 'Infra Guide', to: '/ops/infra-guide'},
           ],
         },
         {
-          title: 'Build & Operate',
+          title: 'Build & Business',
           items: [
-            {label: 'Getting Started', to: '/getting-started'},
+            {label: 'Core Primitives', to: '/dev/core-primitives'},
-            {label: 'Local Development', to: '/dev/local-development'},
+            {label: 'API Overview', to: '/dev/api-overview'},
-            {label: 'Deployments & Runbooks', to: '/infra/deployments-and-runbooks'},
+            {label: 'Value Proposition', to: '/business/value-proposition'},
-          ],
-        },
-        {
-          title: 'Compliance',
-          items: [
-            {label: 'Regulated Overview', to: '/compliance/regulated-overview'},
-            {label: 'Audit & Journaling', to: '/compliance/audit-and-journaling'},
           ],
         },
       ],

sidebars.ts

@@ -2,50 +2,50 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
 
 const sidebars: SidebarsConfig = {
   docsSidebar: [
-    'intro',
+    'docs-home',
     'getting-started',
     {
       type: 'category',
-      label: 'Architecture',
+      label: 'Overview',
       items: [
-        'architecture/overview',
+        'overview/overview-blackroad-os-overview',
-        'architecture/agents-and-orchestration',
+        'overview/overview-stack-map',
-        'architecture/finance-layer',
+        'overview/overview-seasons',
-        'architecture/ps-sha-infinity',
       ],
     },
     {
       type: 'category',
-      label: 'Infrastructure',
+      label: 'Operate the OS',
       items: [
-        'infra/environments',
+        'ops/ops-prism-console',
-        'infra/dns-and-networking',
+        'ops/ops-operator-runtime',
-        'infra/deployments-and-runbooks',
+        'ops/ops-infra-guide',
       ],
     },
     {
       type: 'category',
-      label: 'Developers',
+      label: 'Build on the OS',
       items: [
-        'dev/repos-and-services',
+        'dev/dev-core-primitives',
-        'dev/local-development',
+        'dev/dev-api-overview',
-        'dev/extending-agents',
+        'dev/dev-agents-atlas-and-friends',
+        'dev/dev-events-and-roadchain',
       ],
     },
     {
       type: 'category',
-      label: 'Operations',
+      label: 'Business & Vision',
       items: [
-        'ops/prism-console',
+        'business/business-pain-points',
-        'ops/incidents-and-incident-response',
+        'business/business-value-proposition',
       ],
     },
     {
       type: 'category',
-      label: 'Compliance',
+      label: 'Meta',
       items: [
-        'compliance/regulated-overview',
+        'meta/meta-glossary',
-        'compliance/audit-and-journaling',
+        'meta/meta-architecture-decisions',
       ],
     },
   ],

src/pages/index.tsx

@@ -1,6 +0,0 @@
-import React from 'react';
-import {Redirect} from '@docusaurus/router';
-
-export default function Home(): JSX.Element {
-  return <Redirect to="/intro" />;
-}