Merge branch origin/codex/refactor-repo-structure-and-documentation into main

.gitignore

@@ -66,3 +66,8 @@ yarn-error.log*
 *.tmp
 *.temp
 .cache/
+
+# Allow checked-in environment mapping docs (no secrets)
+!infra/
+!infra/env/
+!infra/env/ENVIRONMENT_MAP.md

docs/architecture/README.md

@@ -0,0 +1,66 @@
+# BlackRoad OS Architecture Overview
+
+BlackRoad OS combines the Pocket OS front-end, a Python backend, and deployment infrastructure across Railway, Cloudflare, and GitHub Actions. This document captures the high-level layout, the next build milestones, and the prompts/processes needed to keep contributors and agents aligned.
+
+## Repository Layout (proposed)
+
+```
+/
+  backend/             # API, workers, models, tests
+  frontend/            # Pocket OS UI
+  apps/                # Modular OS applications (planned)
+  infra/               # Deployment, DNS, automation configs
+    env/               # Environment variable source of truth
+  docs/                # Architecture, onboarding, specs
+```
+
+Use this as the north-star layout when moving files or adding new components so tooling and contributors can find things quickly.
+
+## Current System
+
+- **Frontend**: Pocket OS UI deployed via Railway static hosting with Cloudflare in front.
+- **Backend**: Python service (FastAPI/Flask) deployed on Railway with `/health` available for smoke checks.
+- **CI/CD**: GitHub Actions building and deploying to Railway; DNS managed via Cloudflare/GoDaddy.
+
+## Next Three Moves (execution-focused)
+
+1. **Stabilize the foundation**
+   - Refine the directory structure above; group backend code into `app/api`, `app/models`, `app/utils`, `app/workers`, and collect tests under `backend/tests`.
+   - Centralize environment variables under `infra/env/ENVIRONMENT_MAP.md` and sync to Railway, GitHub Actions, and Cloudflare.
+   - Maintain a single architectural source of truth (this file) to reduce context churn for agents.
+
+2. **Turn the OS into an OS**
+   - Introduce a pluggable app system under `/apps/<app-name>` with a `manifest.json` and optional `index.js`/`api.js` entrypoints.
+   - Persist user state (open windows, layout, theme, installed apps, agent console state) via localStorage initially, with a path to backend storage.
+   - Build an **Agent Panel** so Lucidia, Cece, Codex, Silas, etc. appear as processes inside the OS.
+
+3. **Harden deployments**
+   - Split CI pipelines so backend and frontend deploy independently; include Cloudflare cache invalidation.
+   - Add smoke/health checks (backend `/health`, frontend `/`) gated in the pipeline.
+   - Define fallback routing: if Railway is unavailable, serve from GitHub Pages; otherwise serve backend static as a last resort.
+
+## Visual Identity (priority)
+
+Lock in the OS look-and-feel early:
+- Neon spectrum palette, window chrome, typography, animation timing, and a short boot sequence.
+- Keep these tokens centralized (e.g., a theme module in `frontend/src/systems/theme`).
+
+## Agent Kernel Concept
+
+A lightweight kernel to orchestrate agents inside the OS:
+```
+/kernel/
+  agent_registry.js
+  message_bus.js
+  process_scheduler.js
+```
+Agents register with the kernel and render inside the Agent Panel for observability and control.
+
+## Prompt for Scaffolding Agents
+
+When onboarding new AI agents, provide this file plus:
+- The environment map (`infra/env/ENVIRONMENT_MAP.md`).
+- The current CI/CD pipeline summary.
+- The pluggable app spec (once created).
+
+This reduces hallucinations and keeps responses grounded in the actual architecture.

infra/env/ENVIRONMENT_MAP.md

@@ -0,0 +1,35 @@
+# Environment Variable Map
+
+Use this file as the single source of truth for environment variables across Railway, GitHub Actions, Cloudflare, and local development. Keep values out of the repo; document names, purposes, and where they are set.
+
+## How to Read This Map
+- **Name**: The canonical environment variable name.
+- **Purpose**: What it controls.
+- **Railway**: Project/service variable name and scope.
+- **GitHub Actions**: Secret name or workflow variable.
+- **Cloudflare**: Worker/Pages binding or secret name.
+- **Local**: `.env` or shell export guidance.
+
+| Name | Purpose | Railway | GitHub Actions | Cloudflare | Local |
+| --- | --- | --- | --- | --- | --- |
+| `API_BASE_URL` | Public URL for the backend API. | Service variable on backend service. | `API_BASE_URL` repository secret. | Worker env var if proxied. | `.env` entry used by frontend build. |
+| `FRONTEND_URL` | Public URL for the Pocket OS UI. | Static hosting env var. | `FRONTEND_URL` secret used in deploy jobs. | Origin override or Pages env var. | `.env` entry for local testing. |
+| `DB_URL` | Database connection string. | Service variable for backend. | `DB_URL` secret for migrations/tests. | - | `.env` entry; never committed. |
+| `CF_ZONE_ID` | Cloudflare zone identifier. | - | `CF_ZONE_ID` secret for cache purge. | Config variable in Workers/Pages. | Export in terminal when running scripts. |
+| `CF_API_TOKEN` | Token for DNS/cache automation. | - | `CF_API_TOKEN` secret. | Secret binding in Workers automation. | Export in terminal; do not store. |
+| `RAILWAY_TOKEN` | Token for CLI/CI deployments. | N/A | `RAILWAY_TOKEN` secret. | - | Export locally when using Railway CLI. |
+| `OPENAI_API_KEY` | Agent/LLM access key. | Backend variable if used server-side. | `OPENAI_API_KEY` secret for agent jobs. | Worker secret if routing requests. | `.env` entry for local agent dev. |
+| `GITHUB_TOKEN` | GitHub API access for agents/prism. | - | Automatic Actions token or PAT secret. | Worker secret if used in edge functions. | Export locally when testing agent integrations. |
+
+## Usage Notes
+- Whenever a new variable is introduced, add a row and propagate to all providers during PR review.
+- Prefer service-scoped variables on Railway to limit blast radius.
+- Keep provider names identical where possible to reduce mapping friction.
+- Store local values in a private `.env` not committed to git; provide `.env.example` if defaults are safe.
+
+## Sync Checklist
+1. Update this map.
+2. Apply changes to Railway environments (backend + frontend services).
+3. Update GitHub Actions secrets or workflow envs.
+4. Update Cloudflare Workers/Pages bindings.
+5. Verify `.env`/local instructions.