Merge pull request #8 from BlackRoad-OS/codex/standardize-documentation-structure

.github/workflows/docs-deploy.yaml

@@ -1,4 +1,4 @@
-name: Deploy docs to Railway
+name: Docs Deploy
 
 on:
   push:
@@ -8,14 +8,14 @@ on:
       - main
 
 jobs:
-  deploy:
+  build-and-deploy:
-    name: Deploy docs-site
+    name: Build and deploy docs-site
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Select environment
+      - name: Resolve environment
         id: env
         run: |
           case "$GITHUB_REF_NAME" in
@@ -44,7 +44,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: '18'
-          cache: npm
+          cache: 'npm'
 
       - name: Install dependencies
         run: npm ci
@@ -61,12 +61,10 @@ jobs:
       - name: Deploy to Railway
         env:
           RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
-        run: |
+        run: railway up --service docs-site --environment ${{ steps.env.outputs.env_name }} --ci
-          railway up --service docs-site --environment ${{ steps.env.outputs.env_name }} --ci
 
-      - name: Run healthcheck (staging/prod)
+      - name: Smoke check
-        if: 'steps.env.outputs.env_name == ''staging'' || steps.env.outputs.env_name == ''prod'''
         run: |
-          url=${{ steps.env.outputs.docs_url }}/health
+          url="${{ steps.env.outputs.docs_url }}/health"
-          echo "Checking $url"
+          echo "Pinging $url"
-          curl -f "$url" && echo "Healthcheck passed"
+          curl -fL "$url"

README.md

@@ -3,10 +3,10 @@
 This repository hosts the **BlackRoad OS Handbook**, the production-ready documentation hub for all BlackRoad surfaces (core backend, Web UI, Prism Console, agents, and infrastructure).
 
 ## What lives here
-- Structured documentation powered by Docusaurus v3 with sidebar navigation.
+- Structured documentation powered by **Docusaurus v3** (content lives in `docs/`, navigation in `sidebars.js`).
 - Opinionated style guide, glossary, and onboarding playbooks.
 - Static health/version endpoints generated at build time (`/health.json`, `/version.json`).
-- CI/CD and deployment workflow definitions for Railway or GitHub Pages.
+- CI/CD and deployment workflow definitions for Railway.
 
 ## Getting started
 1. Install Node 18+ and npm.
@@ -17,13 +17,36 @@ This repository hosts the **BlackRoad OS Handbook**, the production-ready docume
    ```
 3. Visit [http://localhost:3000](http://localhost:3000) to browse the docs.
 
-## Deployment
+## Documentation framework & structure
-- The docs build with `npm run build` (includes generating health/version metadata).
+- **Framework:** Docusaurus v3 (static site). Routing is rooted at `/` (`routeBasePath: '/'` in `docusaurus.config.js`).
-- Deploy to Railway using the provided `railway.json` or to GitHub Pages via the `deploy-docs` workflow.
+- **Docs location:** `docs/` organized into the following standard sections:
-- Branch mapping:
+  - `intro/`
-  - `dev` → preview/staging deployment
+  - `core/`
-  - `staging` → staging environment
+  - `web/`
-  - `main` → production
+  - `console/`
+  - `agents/`
+  - `operator/` (stubbed until playbooks are written)
+  - `infra/`
+  - `onboarding/`
+- **Navigation:** `sidebars.js` defines the tree for the `primarySidebar`. The navbar shows the unified "Docs" sidebar.
+
+### Adding or updating pages
+1. Add a Markdown file to the correct section in `docs/` (e.g., `docs/core/new-page.md`).
+2. Register it in `sidebars.js` under the matching category so it appears in navigation.
+3. Run `npm start` to verify local rendering.
+
+### Health & hosting
+- The site is static and exposes `static/health.json` and `static/health/index.json` at `/health` and `/health.json` for probes. A version payload lives at `/version` and `/version.json`.
+- The production hostname is controlled through the `PUBLIC_DOCS_URL` env var (see below) and consumed via `src/config/docsConfig.js`.
+
+### Deployment
+- The docs build with `npm run build` (includes generating health/version metadata via `scripts/generateMeta.js`).
+- Deploy to Railway using the provided `railway.json` and GitHub Actions workflow `.github/workflows/docs-deploy.yaml`.
+- Branch mapping in the workflow:
+  - `dev` → Railway environment `dev` (https://dev.docs.blackroad.systems)
+  - `staging` → Railway environment `staging` (https://staging.docs.blackroad.systems)
+  - `main` → Railway environment `prod` (https://docs.blackroad.systems)
+  The workflow performs a smoke check against `/health` after deployment.
 
 ## Docs Deployment & Environments
 This repository is the official BlackRoad OS documentation site. It deploys to the Railway project at
@@ -35,13 +58,13 @@ Environment → URL mapping:
 - **staging**: https://staging.docs.blackroad.systems
 - **prod**: https://docs.blackroad.systems
 
-Required environment variables:
+Required environment variables (loaded via `src/config/docsConfig.js`):
+- `PUBLIC_DOCS_URL` (required outside of local dev, used for canonical links and metadata)
 - `NODE_ENV`
-- `PUBLIC_DOCS_URL`
 - Optional cross-link targets: `CORE_API_URL`, `WEB_APP_URL`, `CONSOLE_URL`, `AGENTS_API_URL`
 
-The `railway.json` file and `.github/workflows/deploy-docs.yml` workflow keep build (`npm run build`) and start
+The `railway.json` file and `.github/workflows/docs-deploy.yaml` workflow keep build (`npm run build`) and start
-(`npm run start`) commands aligned for deploys.
+(`npm run start`) commands aligned for deploys, with `/health` configured as the probe path.
 
 ## Related repositories
 - Core backend: https://github.com/blackroad-os/blackroad-os-core

docs/operator/overview.md

@@ -0,0 +1,11 @@
+# Operator Playbooks
+
+> TODO: Flesh out runbooks for console operators, incident response, and release management.
+>
+> This section should eventually include:
+> - **Runbooks:** standard operating procedures for on-call and console operators.
+> - **Playbooks:** repeatable steps for common production tasks (failover, migrations, cache warm-ups).
+> - **Dashboards & alerts:** links to observability dashboards and alert routing.
+> - **Run readiness:** preflight checklists for deploys and maintenance windows.
+
+This stub anchors the `operator/` section in navigation so the structure stays stable while content is authored.

docusaurus.config.js

@@ -70,10 +70,7 @@ const config = {
         src: 'img/logo.svg',
       },
       items: [
-        {type: 'docSidebar', sidebarId: 'introSidebar', position: 'left', label: 'Introduction'},
+        {type: 'docSidebar', sidebarId: 'primarySidebar', position: 'left', label: 'Docs'},
-        {type: 'docSidebar', sidebarId: 'systemSidebar', position: 'left', label: 'Systems'},
-        {type: 'docSidebar', sidebarId: 'infraSidebar', position: 'left', label: 'Infra'},
-        {type: 'docSidebar', sidebarId: 'enablementSidebar', position: 'left', label: 'Enablement'},
         {href: 'https://github.com/blackroad-os/blackroad-os-docs', label: 'GitHub', position: 'right'},
       ],
     },
@@ -94,6 +91,7 @@ const config = {
             {label: 'Infra', to: '/infra/railway-architecture'},
             {label: 'CI/CD', to: '/infra/ci-cd'},
             {label: 'Environment Reference', to: '/infra/env-reference'},
+            {label: 'Operator Playbooks', to: '/operator/overview'},
           ],
         },
         {

railway.json

@@ -8,6 +8,7 @@
       "name": "docs-site",
       "buildCommand": "npm ci && npm run build",
       "startCommand": "npm run start",
+      "healthcheckPath": "/health",
       "env": {
         "NODE_ENV": "production",
         "PUBLIC_DOCS_URL": "https://docs.blackroad.dev"

sidebars.js

@@ -1,45 +1,74 @@
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
-  introSidebar: [
+  primarySidebar: [
-    'intro/overview',
+    {
+      type: 'category',
+      label: 'Introduction',
+      link: {type: 'doc', id: 'intro/overview'},
+      items: [
+        'intro/what-is-blackroad-os',
         'intro/vision',
         'intro/architecture',
+        'intro/architecture-overview',
         'intro/versioning-strategy',
       ],
-  systemSidebar: [
+    },
     {
       type: 'category',
       label: 'Core Backend',
-      items: ['core/overview', 'core/api', 'core/endpoints', 'core/env-vars', 'core/deployment'],
+      link: {type: 'doc', id: 'core/overview'},
+      items: ['core/api', 'core/endpoints', 'core/env-vars', 'core/deployment'],
     },
     {
       type: 'category',
       label: 'Web UI',
-      items: ['web/overview', 'web/env-vars', 'web/routing', 'web/environment-config', 'web/infra'],
+      link: {type: 'doc', id: 'web/overview'},
+      items: ['web/env-vars', 'web/routing', 'web/environment-config', 'web/infra'],
     },
     {
       type: 'category',
       label: 'Prism Console',
-      items: ['console/overview', 'console/operators-view', 'console/structure', 'console/integrating-with-core'],
+      link: {type: 'doc', id: 'console/overview'},
+      items: ['console/operators-view', 'console/structure', 'console/integrating-with-core'],
     },
     {
       type: 'category',
       label: 'Agents Runtime',
-      items: ['agents/overview', 'agents/runtime', 'agents/queues', 'agents/worker-architecture', 'agents/queue', 'agents/api', 'agents/versioning'],
+      link: {type: 'doc', id: 'agents/overview'},
-    },
+      items: [
+        'agents/runtime',
+        'agents/queues',
+        'agents/queue',
+        'agents/worker-architecture',
+        'agents/api',
+        'agents/versioning',
       ],
-  infraSidebar: [
+    },
+    {
+      type: 'category',
+      label: 'Operator Playbooks',
+      link: {type: 'doc', id: 'operator/overview'},
+      items: [],
+    },
     {
       type: 'category',
       label: 'Infrastructure',
-      items: ['infra/railway', 'infra/cloudflare', 'infra/environments', 'infra/railway-architecture', 'infra/cloudflare-architecture', 'infra/domains', 'infra/ci-cd', 'infra/env-reference'],
+      link: {type: 'doc', id: 'infra/railway-architecture'},
-    },
+      items: [
+        'infra/railway',
+        'infra/cloudflare',
+        'infra/cloudflare-architecture',
+        'infra/domains',
+        'infra/environments',
+        'infra/env-reference',
+        'infra/ci-cd',
       ],
-  enablementSidebar: [
+    },
     {
       type: 'category',
       label: 'Onboarding',
-      items: ['onboarding/developer-setup', 'onboarding/repos', 'onboarding/repo-guide', 'onboarding/branching-strategy'],
+      link: {type: 'doc', id: 'onboarding/developer-setup'},
+      items: ['onboarding/repos', 'onboarding/repo-guide', 'onboarding/branching-strategy'],
     },
     'glossary',
     'style-guide',

static/health.json

@@ -1,5 +1,5 @@
 {
   "status": "ok",
-  "timestamp": "2025-11-19T21:19:39.408Z",
+  "timestamp": "2025-11-20T18:35:36.292Z",
   "environment": "production"
 }

static/health/index.json

@@ -1,5 +1,5 @@
 {
   "status": "ok",
-  "timestamp": "2025-11-19T21:19:39.408Z",
+  "timestamp": "2025-11-20T18:35:36.292Z",
   "environment": "production"
 }

static/version.json

@@ -1,8 +1,8 @@
 {
   "service": "docs-site",
   "appVersion": "0.1.0",
-  "commit": "2c239fe5f225f96afdf8f615caa84c98e86d6cd0",
+  "commit": "76f3de887875c785944a97d81e17b199b3b3b5e7",
-  "buildTime": "2025-11-19T21:19:39.407Z",
+  "buildTime": "2025-11-20T18:35:36.292Z",
   "environment": "production",
   "docsUrl": "http://localhost:3000"
 }

static/version/index.json

@@ -1,8 +1,8 @@
 {
   "service": "docs-site",
   "appVersion": "0.1.0",
-  "commit": "2c239fe5f225f96afdf8f615caa84c98e86d6cd0",
+  "commit": "76f3de887875c785944a97d81e17b199b3b3b5e7",
-  "buildTime": "2025-11-19T21:19:39.407Z",
+  "buildTime": "2025-11-20T18:35:36.292Z",
   "environment": "production",
   "docsUrl": "http://localhost:3000"
 }