Prepare docs site for Railway deployment

.github/workflows/deploy-docs.yml

@@ -1,4 +1,4 @@
-name: deploy-docs
+name: Deploy docs to Railway
 
 on:
   push:
@@ -6,60 +6,67 @@ on:
       - dev
       - staging
       - main
-  workflow_dispatch:
 
 jobs:
-  build-and-deploy:
+  deploy:
+    name: Deploy docs-site
     runs-on: ubuntu-latest
-    env:
-      NODE_ENV: production
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 18
-          cache: npm
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Build docs
-        run: npm run build
-
-      - name: Health check bundle
-        run: |
-          python -m http.server 3000 --directory build &
-          SERVER_PID=$!
-          trap "kill $SERVER_PID" EXIT
-          sleep 5
-          curl -f http://localhost:3000/health.json
-          curl -f http://localhost:3000/version.json
       - name: Select environment
         id: env
         run: |
-          if [[ "${GITHUB_REF_NAME}" == "main" ]]; then
+          case "$GITHUB_REF_NAME" in
-            echo "environment=prod" >> "$GITHUB_OUTPUT"
+            dev)
-          elif [[ "${GITHUB_REF_NAME}" == "staging" ]]; then
+              target_env="dev"
-            echo "environment=staging" >> "$GITHUB_OUTPUT"
+              docs_url="https://dev.docs.blackroad.systems"
-          else
+              ;;
-            echo "environment=dev" >> "$GITHUB_OUTPUT"
+            staging)
-          fi
+              target_env="staging"
+              docs_url="https://staging.docs.blackroad.systems"
+              ;;
+            main)
+              target_env="prod"
+              docs_url="https://docs.blackroad.systems"
+              ;;
+            *)
+              echo "Branch $GITHUB_REF_NAME is not mapped to a Railway environment" >&2
+              exit 1
+              ;;
+          esac
+
+          echo "env_name=$target_env" >> "$GITHUB_OUTPUT"
+          echo "docs_url=$docs_url" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs
+        env:
+          NODE_ENV: production
+          PUBLIC_DOCS_URL: ${{ steps.env.outputs.docs_url }}
+        run: npm run build
 
       - name: Install Railway CLI
-        if: ${{ secrets.RAILWAY_TOKEN != '' }}
         run: npm install -g @railway/cli
 
       - name: Deploy to Railway
-        if: ${{ secrets.RAILWAY_TOKEN != '' }}
-        run: railway up --service docs-site --environment ${{ steps.env.outputs.environment }}
         env:
           RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
+        run: |
+          railway up --service docs-site --environment ${{ steps.env.outputs.env_name }} --ci --token "$RAILWAY_TOKEN"
 
-      - name: Upload artifact (GH Pages fallback)
+      - name: Run healthcheck (staging/prod)
-        if: ${{ !secrets.RAILWAY_TOKEN }}
+        if: steps.env.outputs.env_name == 'staging' || steps.env.outputs.env_name == 'prod'
-        uses: actions/upload-pages-artifact@v3
+        run: |
-        with:
+          url=${{ steps.env.outputs.docs_url }}/health
-          path: build
+          echo "Checking $url"
+          curl -f "$url" && echo "Healthcheck passed"

README.md

@@ -25,6 +25,24 @@ This repository hosts the **BlackRoad OS Handbook**, the production-ready docume
   - `staging` → staging environment
   - `main` → production
 
+## Docs Deployment & Environments
+This repository is the official BlackRoad OS documentation site. It deploys to the Railway project at
+`https://railway.com/project/a4efb8cd-0d67-4b19-a7f3-b6dbcedf2079?environmentId=a41a126f-ecf9-47b1-8bd6-11ff9a02d799`
+as the `docs-site` service.
+
+Environment → URL mapping:
+- **dev**: https://dev.docs.blackroad.systems (or local http://localhost:3000 via `npm run dev`)
+- **staging**: https://staging.docs.blackroad.systems
+- **prod**: https://docs.blackroad.systems
+
+Required environment variables:
+- `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
+(`npm run start`) commands aligned for deploys.
+
 ## Related repositories
 - Core backend: https://github.com/blackroad-os/blackroad-os-core
 - Web UI: https://github.com/blackroad-os/blackroad-os-web

docs/agents/queues.md

@@ -0,0 +1,9 @@
+# Agents queues
+
+List the queues, topics, and retry semantics that the Agents runtime depends on.
+
+- Default queue: general automation jobs.
+- Priority queue: time-sensitive work such as provisioning.
+- Dead-letter strategy: capture failed jobs with visibility in Prism Console.
+
+TODO: Add SLOs, retry backoff settings, and queue-specific observability dashboards.

docs/agents/runtime.md

@@ -0,0 +1,9 @@
+# Agents runtime
+
+Describe how agents are scheduled, executed, and monitored. This complements the architecture diagrams and queue details.
+
+- Runtime responsibilities: pick jobs from queues, call Core API, emit telemetry.
+- Deployment: packaged alongside the Core platform on Railway; surface `/health` for liveness.
+- Configuration: align with `AGENTS_API_URL` and queue configs documented below.
+
+TODO: Add lifecycle diagrams and scaling strategies per environment.

docs/console/operators-view.md

@@ -0,0 +1,9 @@
+# Operators view
+
+Document the Prism Console experience for operators: queues, audit trails, and escalation flows.
+
+- Home: operational dashboard for current tenants.
+- Actions: pause/resume agents, review job histories, and triage alerts.
+- URLs: prefer `CONSOLE_URL` from `src/config/docsConfig.js` when linking out.
+
+TODO: Add screenshots and end-to-end runbooks for incident workflows.

docs/core/api.md

@@ -0,0 +1,9 @@
+# Core API guide
+
+Outline the critical endpoints, authentication model, and versioning expectations for the Core API. Link to OpenAPI/Swagger docs when available.
+
+- Authentication: JWT or service tokens issued by the Core platform.
+- Key flows: tenant provisioning, identity management, agent registration, and observability hooks.
+- Environments: prefer URLs sourced from `CORE_API_URL` in `src/config/docsConfig.js`.
+
+TODO: Add sample requests and error envelopes per endpoint family.

docs/infra/cloudflare.md

@@ -0,0 +1,9 @@
+# Cloudflare delivery
+
+Cloudflare fronts the docs site and other BlackRoad surfaces. It should proxy to the Railway-hosted service and cache static assets aggressively.
+
+- Domains: `docs.blackroad.systems` (prod) and `staging.docs.blackroad.systems` (staging).
+- TLS and redirects managed at Cloudflare; keep origin pointing at the Railway service URL.
+- Add cache busting rules for static assets after each deploy.
+
+TODO: Document the exact DNS records and SSL/TLS settings used across environments.

docs/infra/environments.md

@@ -0,0 +1,19 @@
+# Environment reference
+
+Track the dev, staging, and prod mappings for the docs site and related services. Use `PUBLIC_DOCS_URL` plus the optional URLs in `src/config/docsConfig.js` to keep cross-links aligned.
+
+| Environment | Docs URL | Core API | Web App | Console | Agents API |
+| --- | --- | --- | --- | --- | --- |
+| Dev | http://localhost:3000 (default) | `CORE_API_URL` | `WEB_APP_URL` | `CONSOLE_URL` | `AGENTS_API_URL` |
+| Staging | https://staging.docs.blackroad.systems | Update per deployment | Update per deployment | Update per deployment | Update per deployment |
+| Prod | https://docs.blackroad.systems | Update per deployment | Update per deployment | Update per deployment | Update per deployment |
+
+Usage example (client code):
+
+```js
+import docsConfig from '@site/src/config/docsConfig';
+
+console.log('Docs served from', docsConfig.publicDocsUrl);
+```
+
+TODO: Add per-service secrets and operational notes as they stabilize.

docs/infra/railway.md

@@ -0,0 +1,9 @@
+# Railway deployment
+
+Railway hosts the docs site alongside other BlackRoad OS services. Deploy using the `docs-site` service defined in `railway.json` with `npm run build` followed by `npm run start`.
+
+- Branch mappings: dev, staging, and prod map to Railway environments of the same name.
+- Health probes: `/health` returns status JSON; `/version` returns build metadata.
+- Config: ensure `PUBLIC_DOCS_URL` is set per environment so canonical links resolve correctly.
+
+TODO: Add screenshots of Railway service settings and environment variable layouts.

docs/intro/architecture.md

@@ -0,0 +1,9 @@
+# BlackRoad OS architecture
+
+A layered platform stitches together the Core API, frontends (Web UI and Prism Console), and the Agents runtime. Each surface is documented in its own section; this page gives you the edges to look for when integrating.
+
+- Core API exposes the contracts that Web UI, Console, and Agents rely on.
+- Agents runtime executes queued work against the Core API and external systems.
+- Frontends are delivered via Cloudflare and backed by the Core API running on Railway.
+
+For deeper endpoint and environment notes, jump into the component sections linked from the sidebar.

docs/intro/overview.md

@@ -0,0 +1,9 @@
+# BlackRoad OS overview
+
+Welcome to the BlackRoad OS handbook. This overview anchors the platform pillars, high-level services, and how the product suite hangs together. Use this page as a landing spot before diving into detailed playbooks.
+
+- Platform pillars: Core API, Web App, Prism Console, Agents runtime, and shared infrastructure.
+- Operates across dev, staging, and prod environments; the docs surface uses the `PUBLIC_DOCS_URL` configured via `src/config/docsConfig.js`.
+- Health and version metadata live at `/health` and `/version` for quick uptime checks.
+
+See the architecture deep-dive in [`intro/architecture.md`](./architecture.md) for diagrams and service boundaries.

docs/onboarding/repos.md

@@ -0,0 +1,11 @@
+# Repository map
+
+The BlackRoad OS platform spans multiple repositories. Start with this list when onboarding or coordinating changes.
+
+- Docs: `blackroad-os-docs` (this site) – deployed as `docs-site` on Railway.
+- Core backend: `blackroad-os-core` – source of truth for APIs and domain logic.
+- Web UI: `blackroad-os-web` – customer-facing frontend.
+- Prism Console: `blackroad-os-console` – operator-facing controls.
+- Agents runtime: `blackroad-os-agents` – automation and background processing.
+
+TODO: Add cross-repo release procedures and branching conventions.

docs/web/env-vars.md

@@ -0,0 +1,10 @@
+# Web app environment variables
+
+Track the configuration needed for the BlackRoad Web UI. Align this table with the `WEB_APP_URL` value in `src/config/docsConfig.js` and the environment reference under infra.
+
+| Variable | Purpose | Notes |
+| --- | --- | --- |
+| `WEB_APP_URL` | Public URL for the Web UI | Used in cross-links from docs and Console |
+| `CORE_API_URL` | API the Web UI talks to | Keep in sync with backend deployments |
+
+TODO: Add feature flag toggles and analytics settings as they are introduced.

docusaurus.config.js

@@ -1,11 +1,12 @@
 // @ts-check
 const {themes: prismThemes} = require('prism-react-renderer');
+const docsConfig = require('./src/config/docsConfig');
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'BlackRoad OS Handbook',
   tagline: 'Unified documentation for BlackRoad OS platform',
-  url: 'https://blackroad-os-docs.example.com',
+  url: docsConfig.publicDocsUrl,
   baseUrl: '/',
   onBrokenLinks: 'throw',
   onBrokenMarkdownLinks: 'warn',
@@ -25,6 +26,13 @@ const config = {
       agents: 'https://github.com/blackroad-os/blackroad-os-agents',
       docs: 'https://github.com/blackroad-os/blackroad-os-docs'
     },
+    links: {
+      docs: docsConfig.publicDocsUrl,
+      coreApi: docsConfig.coreApiUrl,
+      webApp: docsConfig.webAppUrl,
+      consoleApp: docsConfig.consoleUrl,
+      agentsApi: docsConfig.agentsApiUrl,
+    },
     deployment: {
       platform: 'Railway',
       healthcheck: '/health',

package.json

@@ -4,9 +4,10 @@
   "private": true,
   "description": "Official documentation hub for BlackRoad OS",
   "scripts": {
-    "start": "docusaurus start",
+    "dev": "docusaurus start",
     "build": "npm run generate:meta && docusaurus build",
-    "serve": "docusaurus serve",
+    "start": "docusaurus serve --dir build --host 0.0.0.0 --port ${PORT:-3000}",
+    "serve": "npm run start",
     "generate:meta": "node scripts/generateMeta.js"
   },
   "dependencies": {

railway.json

@@ -6,11 +6,11 @@
   "services": [
     {
       "name": "docs-site",
-      "buildCommand": "npm run build",
+      "buildCommand": "npm ci && npm run build",
-      "startCommand": "npx docusaurus serve --dir build --host 0.0.0.0 --port $PORT",
+      "startCommand": "npm run start",
       "env": {
         "NODE_ENV": "production",
-        "PUBLIC_DOCS_URL": "https://docs.blackroad.dev"
+        "PUBLIC_DOCS_URL": "https://docs.blackroad.systems"
       }
     }
   ]

scripts/generateMeta.js

@@ -1,8 +1,16 @@
 const { execSync } = require('node:child_process');
 const { writeFileSync, mkdirSync, readFileSync } = require('node:fs');
 const { join } = require('node:path');
+const docsConfig = require('../src/config/docsConfig');
+
+const BUILD_TIME = process.env.RAILWAY_BUILD_TIME || process.env.BUILD_TIME || new Date().toISOString();
+
+const SERVICE_NAME = docsConfig.serviceName;
 
 function getCommitSha() {
+  if (process.env.RAILWAY_GIT_COMMIT_SHA) {
+    return process.env.RAILWAY_GIT_COMMIT_SHA;
+  }
   try {
     return execSync('git rev-parse HEAD').toString().trim();
   } catch (error) {
@@ -24,22 +32,33 @@ function buildMeta() {
   const timestamp = new Date().toISOString();
   const commit = getCommitSha();
   const version = getVersion();
-  const payload = {
+
+  const healthPayload = {
     status: 'ok',
-    environment: process.env.NODE_ENV || 'development',
     timestamp,
+    environment: docsConfig.env,
+  };
+
+  const versionPayload = {
+    service: SERVICE_NAME,
+    appVersion: version,
     commit,
-    version
+    buildTime: BUILD_TIME,
+    environment: docsConfig.env,
+    docsUrl: docsConfig.publicDocsUrl,
   };
 
   const staticDir = join(process.cwd(), 'static');
   mkdirSync(staticDir, { recursive: true });
-  writeFileSync(join(staticDir, 'health.json'), JSON.stringify(payload, null, 2));
+
-  writeFileSync(join(staticDir, 'version.json'), JSON.stringify(payload, null, 2));
+  writeFileSync(join(staticDir, 'health.json'), JSON.stringify(healthPayload, null, 2));
+  writeFileSync(join(staticDir, 'version.json'), JSON.stringify(versionPayload, null, 2));
+
   mkdirSync(join(staticDir, 'health'), { recursive: true });
   mkdirSync(join(staticDir, 'version'), { recursive: true });
-  writeFileSync(join(staticDir, 'health', 'index.json'), JSON.stringify(payload, null, 2));
+
-  writeFileSync(join(staticDir, 'version', 'index.json'), JSON.stringify(payload, null, 2));
+  writeFileSync(join(staticDir, 'health', 'index.json'), JSON.stringify(healthPayload, null, 2));
+  writeFileSync(join(staticDir, 'version', 'index.json'), JSON.stringify(versionPayload, null, 2));
 }
 
 buildMeta();

sidebars.js

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

src/config/docsConfig.js

@@ -0,0 +1,41 @@
+/**
+ * Centralized configuration for the docs site.
+ * Reads environment variables at build/start time so links between services stay consistent.
+ */
+
+const DEFAULT_DOCS_URL = 'http://localhost:3000';
+
+const env = process.env.NODE_ENV || 'development';
+const isProdLike = env !== 'development';
+
+function readEnv(name, fallback = '') {
+  const value = process.env[name] || fallback;
+  if (isProdLike && name === 'PUBLIC_DOCS_URL' && !value) {
+    throw new Error('PUBLIC_DOCS_URL must be defined in non-development environments');
+  }
+  return value;
+}
+
+/**
+ * @typedef {Object} DocsConfig
+ * @property {string} env
+ * @property {string} publicDocsUrl
+ * @property {string|null} coreApiUrl
+ * @property {string|null} webAppUrl
+ * @property {string|null} consoleUrl
+ * @property {string|null} agentsApiUrl
+ * @property {string} serviceName
+ */
+
+/** @type {DocsConfig} */
+const config = {
+  env,
+  publicDocsUrl: readEnv('PUBLIC_DOCS_URL', DEFAULT_DOCS_URL),
+  coreApiUrl: process.env.CORE_API_URL || null,
+  webAppUrl: process.env.WEB_APP_URL || null,
+  consoleUrl: process.env.CONSOLE_URL || null,
+  agentsApiUrl: process.env.AGENTS_API_URL || null,
+  serviceName: 'docs-site',
+};
+
+module.exports = config;

src/pages/index.jsx

@@ -1,6 +1,7 @@
 import Link from '@docusaurus/Link';
 import Layout from '@theme/Layout';
 import React from 'react';
+import docsConfig from '../config/docsConfig';
 
 export default function Home() {
   return (
@@ -10,10 +11,10 @@ export default function Home() {
           <h1 className="hero__title">BlackRoad OS Handbook</h1>
           <p className="hero__subtitle">One place for platform architecture, operational playbooks, and onboarding.</p>
           <div className="buttons">
-            <Link className="button button--secondary button--lg" to="/intro/what-is-blackroad-os">
+            <Link className="button button--secondary button--lg" to="/intro/overview">
               Start with the overview
             </Link>
-            <Link className="button button--outline button--lg" to="/infra/env-reference">
+            <Link className="button button--outline button--lg" to="/infra/environments">
               Environment reference
             </Link>
           </div>
@@ -32,7 +33,7 @@ export default function Home() {
             <h3>Infra & Deploy</h3>
             <p className="card-subtitle">Railway + Cloudflare</p>
             <p>Deployment flows, domains, CI/CD, and environment mappings with health/version probes baked in.</p>
-            <Link to="/infra/railway-architecture">Read infra playbooks →</Link>
+            <Link to="/infra/railway">Read infra playbooks →</Link>
           </div>
           <div className="callout-card">
             <h3>Onboarding</h3>
@@ -41,6 +42,16 @@ export default function Home() {
             <Link to="/onboarding/developer-setup">Onboard now →</Link>
           </div>
         </div>
+
+        <div className="margin-top--lg">
+          <p className="text--center">
+            Docs served from <strong>{docsConfig.publicDocsUrl}</strong>{' '}
+            {docsConfig.coreApiUrl && <>| Core API: {docsConfig.coreApiUrl} </>}
+            {docsConfig.webAppUrl && <>| Web App: {docsConfig.webAppUrl} </>}
+            {docsConfig.consoleUrl && <>| Console: {docsConfig.consoleUrl} </>}
+            {docsConfig.agentsApiUrl && <>| Agents API: {docsConfig.agentsApiUrl}</>}
+          </p>
+        </div>
       </main>
     </Layout>
   );

static/health.json

@@ -1,7 +1,5 @@
 {
   "status": "ok",
-  "environment": "development",
+  "timestamp": "2025-11-19T21:19:39.408Z",
-  "timestamp": "2025-11-19T19:34:36.366Z",
+  "environment": "production"
-  "commit": "be7f85024cdcfed6c1c88a14642ab097f05bfec2",
-  "version": "0.1.0"
 }

static/health/index.json

@@ -1,7 +1,5 @@
 {
   "status": "ok",
-  "environment": "development",
+  "timestamp": "2025-11-19T21:19:39.408Z",
-  "timestamp": "2025-11-19T19:34:36.366Z",
+  "environment": "production"
-  "commit": "be7f85024cdcfed6c1c88a14642ab097f05bfec2",
-  "version": "0.1.0"
 }

static/version.json

@@ -1,7 +1,8 @@
 {
-  "status": "ok",
+  "service": "docs-site",
-  "environment": "development",
+  "appVersion": "0.1.0",
-  "timestamp": "2025-11-19T19:34:36.366Z",
+  "commit": "2c239fe5f225f96afdf8f615caa84c98e86d6cd0",
-  "commit": "be7f85024cdcfed6c1c88a14642ab097f05bfec2",
+  "buildTime": "2025-11-19T21:19:39.407Z",
-  "version": "0.1.0"
+  "environment": "production",
+  "docsUrl": "http://localhost:3000"
 }

static/version/index.json

@@ -1,7 +1,8 @@
 {
-  "status": "ok",
+  "service": "docs-site",
-  "environment": "development",
+  "appVersion": "0.1.0",
-  "timestamp": "2025-11-19T19:34:36.366Z",
+  "commit": "2c239fe5f225f96afdf8f615caa84c98e86d6cd0",
-  "commit": "be7f85024cdcfed6c1c88a14642ab097f05bfec2",
+  "buildTime": "2025-11-19T21:19:39.407Z",
-  "version": "0.1.0"
+  "environment": "production",
+  "docsUrl": "http://localhost:3000"
 }