diff --git a/CODEBASE_STATUS.md b/CODEBASE_STATUS.md
new file mode 100644
index 0000000..aad90fa
--- /dev/null
+++ b/CODEBASE_STATUS.md
@@ -0,0 +1,57 @@
+# BlackRoad OS Repository Snapshot
+
+## 1. Repo Structure Summary
+- `backend/`: FastAPI backend with routing, models, and the canonical `backend/static` UI bundle served by the API layer.
+- `backend/static/`: Windows 95-inspired single-page interface served by FastAPI (`/` and `/static`).
+- `blackroad-os/`: Older standalone static build (HTML/JS/assets) that appears superseded by `backend/static` but still present in the repo.
+- `agents/`: Python agent library with base abstractions, categories, templates, and tests.
+- `sdk/`: Language-specific SDKs (Python/TypeScript) for integrating with the platform.
+- `docs/`, `scripts/`, `CI` assets (`.github/workflows`), and root-level guidance/vision documents provide deployment, security, and integration references.
+
+## 2. Backend Analysis
+- Framework: FastAPI with CORS middleware, mounted static files, and `/health` endpoint; routes imported from many service modules (auth, email, social, video, files, blockchain, AI chat, integrations, v0.2 capture/identity/notifications/creator/compliance/search).
+- Lifespan creates DB tables via SQLAlchemy async engine and rotates wallet keys on startup; shutdown closes Redis and disposes DB connections.
+- Settings default to SQLite for local/dev while `.env` template targets PostgreSQL/Redis; ALLOWED_ORIGINS, JWT secrets, and cloud keys are environment-driven.
+- ENV vars referenced include database URLs, Redis URL, SECRET_KEY/JWT settings, wallet master key, OpenAI key, S3 credentials, SMTP settings, blockchain tuning, Stripe keys, Twilio/Slack/Discord/Sentry tokens, Railway config, and more (see `.env.example`).
+- Health check: `/health` returns JSON with status/timestamp; OpenAPI docs served under `/api/docs`.
+
+## 3. Frontend Analysis
+- Primary SPA lives in `backend/static/index.html` with inline assets, delivered directly by FastAPI root route for API co-location.
+- Additional legacy UI in `blackroad-os/index.html` with supporting JS/assets suggests duplication/possible drift from canonical static bundle.
+- No build tooling; vanilla HTML/CSS/JS per root README instructions.
+
+## 4. Auth & Identity
+- Backend includes `auth` router providing JWT-based auth with access/refresh expiry settings; relies on SECRET_KEY/ALGORITHM env vars.
+- New identity-centric routes included via `identity_center` router (v0.2 APIs) though implementation status should be validated per-router.
+
+## 5. Stripe & Payments
+- Stripe router is included in `app.main`; `.env.example` declares `STRIPE_SECRET_KEY` and `STRIPE_PUBLISHABLE_KEY`, but actual wiring/state of routes should be confirmed in stripe module before production use.
+
+## 6. Agent / AI Logic
+- Agent library lives in `agents/` with base agent/executor/registry, 10 category folders, templates, and tests; advertised as 200+ agents.
+- AI chat router loaded in FastAPI alongside OpenAI API key in settings, but external provider configuration depends on env vars.
+
+## 7. DevOps / CI-CD
+- GitHub Actions workflows present for CI (`ci.yml`), backend tests, deploy, Railway automation/deploy.
+- Dockerfile and docker-compose in `backend/`; Railway configs (`railway.toml`/`railway.json`) at repo root.
+- Tests exist under `backend/tests/` covering auth, blockchain, miner, integrations, dashboard, VS Code router; test results not run in this snapshot.
+
+## 8. Critical Risks
+- Missing or incorrect env vars (DB/Redis/SECRET_KEY/Stripe/OpenAI/etc.) will break startup or integrations.
+- Legacy `blackroad-os` static bundle could diverge from `backend/static`, leading to inconsistent deployments if wrong entry point is published.
+- SQLite defaults in `app.config.Settings` may hide Postgres/Redis issues until production; migrations/alembic configs exist but runtime auto-creates tables at startup, risking schema drift.
+- External integration routers (Stripe/Twilio/Slack/Discord/etc.) may be stubbed or unconfigured; deployment without keys will fail requests.
+- CI presence suggests expectations for tests; failing/long-running suites could block PRs if dependencies not installed.
+
+## 9. Low-Hanging Fruit
+- Validate `.env` contents against `app.config.Settings` using `scripts/railway/validate_env_template.py` before deployment to ensure secrets alignment.
+- Consolidate on `backend/static` as the authoritative UI and document deprecation of `blackroad-os` to reduce confusion.
+- Add explicit status documentation per router (implemented vs stub) to set expectations for integrations like Stripe/Twilio.
+- Switch default settings to rely on env vars (or fail-fast) in non-dev environments to avoid accidental SQLite/localhost usage.
+- Run and document backend test results in CI badges to highlight current health.
+
+## 10. Recommended Branch Strategy
+- Use `main` for stable releases tied to Railway deploys; require CI pass and env validation before merge.
+- Maintain `develop` (or feature branches) for active work on routers/agents/UI; protect with PR checks and targeted reviewers per area (backend vs agents vs static UI).
+- When touching integrations, gate merges behind mocked tests plus manual smoke checks against a staging environment with representative secrets.
+