# CoreReflex — Developer Docs

The engineering index for CoreReflex: what the platform is, how the repo is laid out, which doc to read for each subsystem, and the order to read them in.

CoreReflex is a governed, self-hosted, white-label **AI creative studio** — one place to make, master, and ship *any* creative output and to run the business that sells it. Video is the flagship (sentence → directed, generated, graded, cut 4K film, then auto-cut into vertical shorts), but the platform underneath is broader: an **audio & music studio** (Lyria + Chirp generation plus real mixing/mastering DSP), an **image & design studio** (Imagen + masks, outpaint, adjustments), a real **NLE editor** with keyframe animation and a curve editor, a **brand / agency layer** (brand cascade, CRM, booking, automation, proofing), an **Auto-Clips pipeline** (long-form → ranked highlights → captioned, voiced vertical shorts), a suite-wide **AI Agent** (plan → approve → execute with budget guardrails and full audit), and a **programmable, dependency-free JSON engine** over the composition ("query the tool like Remotion — JSON in / structured JSON out"). Everything is **own-the-stack**: first-party Google Vertex AI for generation (Gemini, Veo, Imagen, Lyria, Chirp — named as the integrations they are, orchestrated by our code), raw Postgres + MinIO for state and media, an in-house node-graph canvas (CrFlow), and no third-party creative SaaS in the critical path.

Architecturally it is a custom **Node HTTP server with no web framework** — `src/server.js` serves static pages (stamping a per-request CSP nonce and the white-label theme early-paint into every HTML response) and hands `/api/*` requests to `src/api.js`, a single ~2,500-line `if (method && pathname)` route ladder (~393 route branches at last count) that calls focused domain modules and delegates three families to their own routers (chat/support SSE, the God-Mode admin surface, and the real-time voice WebSocket bridge). Persistence is **raw PostgreSQL** through `pg` (`src/database.js`) with hand-written additive migrations in `migrations/` (**001–033**, 34 files — two share the number 014); generated and uploaded media live in **MinIO** (S3-compatible, served only through a signed app proxy). Real-time UI (chat, live-agent, editor comments, agent progress) rides an in-process **SSE bus** (`src/realtime-bus.js`). The browser **editor is a separate Remotion `4.0.483` + React Router v8 SPA** under `editor/` (SSR disabled, Node ≥ 22 to build) hosting eight studio modes on one shared store. Rendering is **live in production**: the `render-worker/` container drains `render_jobs`, bundles the same Remotion composition the editor previews, and writes MP4s to MinIO — it also co-hosts the media sidecar services (audio FX, upscale, remove-bg, vectorize, clip proxy).

The forward direction is captured in [`planning/ROADMAP.md`](../../planning/ROADMAP.md) — the **12-pillar creative-studio roadmap** — with per-pillar backlogs under [`planning/roadmap/`](../../planning/roadmap).

> **White-label theming — no hard-coded brand colors.** The old fixed palette is gone. Every page resolves its colors from CSS custom properties: preset tokens in `public/css/themes.css`, per-workspace overrides (migration `033_workspace_theme.sql` + `src/theme-settings.js`), and a sanitized `cr-theme` cookie that `src/server.js` stamps onto the first paint so there is no flash of the wrong theme. New UI must use theme tokens, never literal hex brand colors. See [architecture.md](architecture.md) (White-label theming section).

## On this page

- [Reading order](#reading-order)
- [Doc index](#doc-index)
- [Repository map](#repository-map)
- [Four deployables](#four-deployables)
- [Public pages](#public-pages)
- [Quick start (local)](#quick-start-local)
- [Testing](#testing)
- [Production status](#production-status)
- [Deep dives & references one level up](#deep-dives--references-one-level-up)

---

## Reading order

New to the codebase? Read these five in order — they are the spine everything else hangs off:

1. [architecture.md](architecture.md) — the system map: server → route ladder → domain modules, the SSE bus, the deployables, and a short overview of every subsystem.
2. [data-model.md](data-model.md) — the Postgres schema, migrations 001–033, numbering conventions, and the applied-vs-pending production table.
3. [api-reference.md](api-reference.md) — the full HTTP surface, auth (session cookie / JWT / `cr_live_` API keys), and the complete route index.
4. [configuration.md](configuration.md) — every environment variable and feature flag, grouped by subsystem.
5. [security.md](security.md) — CSP nonces, rate limits, the SSRF guard, tenant isolation, and the operator checklist.

Then branch by what you're working on:

| You are… | Read |
|----------|------|
| A backend engineer adding an API feature | [api-reference.md](api-reference.md) → [data-model.md](data-model.md) → [billing.md](billing.md) (if it costs credits) → [contributing.md](contributing.md) |
| Working on the editor / a studio mode | [editor.md](editor.md) → [json-engine.md](json-engine.md) → [render-worker.md](render-worker.md) |
| Working on generation, models, or the director | [generation-and-models.md](generation-and-models.md) → [agent-kernel.md](agent-kernel.md) → [vertex-scale-runbook.md](vertex-scale-runbook.md) |
| Bringing the self-hosted AI models online (the GPU box) | [own-the-stack.md](own-the-stack.md) → [../INFERENCE-GATEWAY.md](../INFERENCE-GATEWAY.md) → [`planning/GPU_BOX_EXECUTION.md`](../../planning/GPU_BOX_EXECUTION.md) |
| Working on talking avatars / lip-sync / personas | [avatar-lipsync-engines.md](avatar-lipsync-engines.md) → [own-the-stack.md](own-the-stack.md) → [../INFERENCE-GATEWAY.md](../INFERENCE-GATEWAY.md) |
| Building programmatic / faceless long-form video | [faceless-video-pipeline.md](faceless-video-pipeline.md) → [json-engine.md](json-engine.md) → [render-worker.md](render-worker.md) |
| Working on Auto-Clips | [auto-clips-pipeline.md](auto-clips-pipeline.md) (application layer) → [auto-clips-infra.md](auto-clips-infra.md) (fleet + recovery) |
| Working on chat, support, or the self-healing loop | [chat-system.md](chat-system.md) → [self-healing.md](self-healing.md) |
| An external integrator / building on the platform API | [platform-api.md](platform-api.md) → [api-reference.md](api-reference.md) → [json-engine.md](json-engine.md) |
| An operator deploying or recovering prod | [deployment.md](deployment.md) → [auto-clips-infra.md](auto-clips-infra.md) → [configuration.md](configuration.md) |

## Doc index

Every doc in this folder, grouped by layer.

### Platform spine

| Doc | Covers |
|-----|--------|
| [architecture.md](architecture.md) | System architecture: the framework-free Node server, request flow, the SSE realtime bus, asset/render data flow, subsystem overviews (agent kernel, Auto-Clips, recipes/budget, chat/self-heal, comments + versions, audio-session split, Files + content credentials, social publishing, brand cascade, white-label theming). |
| [api-reference.md](api-reference.md) | HTTP API reference: conventions (auth ladder, errors, rate limits, body caps, credit metering, SSE), every route family with request/response examples, and the complete route index. |
| [data-model.md](data-model.md) | Postgres schema & migrations 001–033: per-migration entries, the duplicate-014 hazard and numbering rules, the 003 reconcile runbook, applied-vs-pending in prod, and schema conventions (tenancy, idempotency, FTS/vector search, encrypted secrets). |
| [configuration.md](configuration.md) | Environment variables & flags: core/deploy, the model registry, director/agent knobs, billing, scheduler, render + the five worker-hosted media seams, Auto-Clips, voice/persona, chat, GHL, signing keys, security limits. |
| [security.md](security.md) | Security model: nonce-based CSP, HTML no-store, rate-limit table, SSRF guard, tenant isolation, API keys, secret encryption (crypto-box), chat redaction, agent guardrails, proof tokens, Ed25519 content credentials, operator checklist. |
| [billing.md](billing.md) | Billing & packaging: Stripe checkout/webhook/portal, plan tiers, the credit ledger, all 14 `USAGE_COSTS` reasons with a route-level metering map, metering invariants, storage accounting + grants, one-time add-on SKUs, owner god-mode. |
| [deployment.md](deployment.md) | Deploy & operations: the four production deployables, the `RENDER_ENABLED`/`CLIP_PROXY_URL` gates, monitor.sh self-healing, build verification (`/api/health` version), migration runs, order-of-operations rules. |
| [contributing.md](contributing.md) | Working in the repo: the Bootspring planning loop, code style, tests, conventional commits. |

### Product engines

| Doc | Covers |
|-----|--------|
| [editor.md](editor.md) | The editor SPA: all eight studio modes (`studio-mode.tsx`), the shared undoable store, the keyframe animation engine + curve editor, grid/snapping/markers, transcript/comments, the export suite, the activity bus, the agent panel, the JSON console, theming bridge, build/test instructions, gotchas. |
| [json-engine.md](json-engine.md) | The programmable JSON engine: the 47-command inventory, the 12-operator query language, server-side extensions (selection, safe/dryRun), the four surfaces (editor console, HTTP, SDK, MCP), and test commands. |
| [generation-and-models.md](generation-and-models.md) | Generation & the model router: `src/models.js` registry + quality-tier routing, Veo conditioning (lastFrame/referenceImages), the camera-move channel, and every modality — video, image edit/assist, captions, story, voice presets, remove-bg/vectorize/upscale, logos, enhance, soundscapes, semantic search. |
| [render-worker.md](render-worker.md) | Rendering (live in prod): `render-worker/` as the production in-container renderer, the `src/render-worker.js` → `RENDER_WORKER_URL` alternate mode, retry/lease/DLQ (migration 017), post-render enhance + QA, and the five co-hosted media services with their port/URL seams. |
| [faceless-video-pipeline.md](faceless-video-pipeline.md) | The programmatic long-form / faceless-video pipeline (proven live): compose any video by code with the JSON engine (Ken Burns via keyframes, crossfades), source clips from Pexels stock **or** — once the GPU box is up — self-hosted AI generation, add a CoreReflex Voice narration track, and render to MP4. The signed-asset-URL gotchas and how AI clips slot into the same pipeline. |
| [agent-kernel.md](agent-kernel.md) | The suite-wide AI Agent: two-phase PLAN→EXECUTE, the live-derived tool registry, validation/feasibility/clarification, governance (approval policies, confirm floor, budget ledger), `agent_runs` audit, SSE observability, the full `/api/agent/*` surface. |
| [auto-clips-pipeline.md](auto-clips-pipeline.md) | Auto-Clips, application layer: highlight detection (video-native + transcript), the 1-fps clip-proxy long-video path, cut/reframe manifest shaping, caption personas, voiceover + ducking, story mode, publish relay, the `/auto-clips` studio page, API + metering. |
| [auto-clips-infra.md](auto-clips-infra.md) | Auto-Clips, production infrastructure: which container runs where on the fleet, the two env gates that must stay set, clip-proxy recreation/recovery, and Coolify token minting. |
| [chat-system.md](chat-system.md) | Chat & support: the grounded RAG pipeline (chat-kb hybrid retrieval + answer gate), the human-handoff state machine, the God-Mode live-agent cockpit, support tickets, and the realtime-bus channels. |
| [self-healing.md](self-healing.md) | The self-healing loop: bug ticket → `self_heal_briefs` repair brief → human-reviewed PR; sync/report scripts and admin endpoints. Human-in-the-loop by design — the agent never merges. |
| [client-ops.md](client-ops.md) | Client-operations layer (Pro): CRM, tasks, booking, voice intake, and the automation engine — all seven triggers, all six actions, the tick-loop scheduler, and the AI automation planner. |

### Platform API & stack strategy

| Doc | Covers |
|-----|--------|
| [platform-api.md](platform-api.md) | The integrator's quick guide: API keys (`cr_live_…`), the model catalog, the zero-dep SDK (`sdk/`), and the MCP server (`mcp/`) that expose the whole platform to agents and CI. |
| [own-the-stack.md](own-the-stack.md) | The engine-agnostic seams (voice, lip-sync, render, upscale) for swapping in self-hosted open-source models behind env-var contracts — with the SSRF rules every seam must respect. |
| [avatar-lipsync-engines.md](avatar-lipsync-engines.md) | Talking avatars & lip-sync, end to end: the two seams (lip-sync vs avatar), the four self-hosted engines (MuseTalk / LatentSync / EchoMimic / LongCat-Avatar) and their first-party wrappers, the gateway topology + canonical bodies, the `renderPersonaClip` consent-gated pipeline, the non-GPU mock smoke path, the engine bake-off, and the per-engine license gates. |
| [gpu-inference-fleet-ops.md](gpu-inference-fleet-ops.md) | Fleet operations for the GPU inference node: the HostSSH launch sequence, how it joins the fleet (proxy route / Cloudflare Tunnel), and how its **usage, billing (credits + GPU-rental COGS), and management** (health, recovery, cost hygiene) are tracked. Pairs with [`planning/GPU_BOX_EXECUTION.md`](../../planning/GPU_BOX_EXECUTION.md). |
| [vertex-scale-runbook.md](vertex-scale-runbook.md) | Ops playbooks for managed Google infrastructure we deliberately *don't* run yet — Vertex Agent Engine and Provisioned Throughput: the trigger, the commands, the cost trade-off. |

## Repository map

Top-level layout, then the `src/` module families.

| Path | What lives here |
|------|-----------------|
| `src/` | The API/app server — every domain module (families below). |
| `migrations/` | Hand-written additive SQL migrations **001–033** (34 files; `014_automation_schedule.sql` and `014_email_verification.sql` share a number — see [data-model.md](data-model.md)). Applied once each via `scripts/migrate.mjs`, recorded in `schema_migrations`. |
| `editor/` | The Remotion `4.0.483` + React Router v8 studio SPA (separate `package.json`; also ships `render-service.mjs`, the standalone render HTTP service for the alternate render mode). |
| `render-worker/` | **The production renderer** (`worker.js`: polls `render_jobs`, bundles `editor/src/remotion` in-container with `@remotion/bundler`/`@remotion/renderer` `4.0.483`, ffmpeg → MinIO) plus the five sidecar media services: `audio-fx-service.js`, `upscale-service.js` (+ `sr-backend.js`), `remove-bg-service.js`, `vectorize-service.js`, `clip-proxy-service.js`. Only deps: Remotion bundler/renderer + `pg`. |
| `public/` | Static pages served by `src/server.js` — see [Public pages](#public-pages). `public/js/` + `public/css/` hold the dashboard modules, theme tokens (`themes.css`), and switcher (`theme.js`). |
| `sdk/` | `@corereflex/sdk` — zero-dependency, isomorphic thin client for the platform API. |
| `mcp/` | `@corereflex/mcp` — zero-dependency MCP server (JSON-RPC over stdio) exposing the platform API as agent tools. |
| `extension/` | Chrome MV3 extension for tab-to-timeline screen recording. |
| `test/` | The server test suite (~160 `node --test` files). Editor and worker tests live next to their code. |
| `scripts/` | Operational scripts: `migrate.mjs`, `check-syntax.mjs` (the lint), `verify-backend.mjs`, `admin-set-password.mjs`, `ingest-chat-kb.mjs`, `self-heal-sync.mjs`/`self-heal-report.mjs`, `db-tunnel.sh`, Vertex smoke tests, blog tooling, batch embedding. |
| `ops/` | Infra runbooks (Coolify DB, migration-application runbooks) + compose files. |
| `self-healing/` | The materialized repair-brief inbox worked by the `/schedule` loop (see [self-healing.md](self-healing.md)). |
| `hyperframes/`, `src/hyperframes.js` | The hyperframes HTML routes rendered into shots. |
| `docs/` | This documentation tree (`docs/dev/`, `docs/user/`, plus the deep-dive specs one level up). |
| `planning/` | The Bootspring planning loop — **source of truth for what to build** (see [contributing.md](contributing.md)). |

### `src/` module families

The route ladder in `src/api.js` stays thin; behavior lives in these modules.

| Family | Modules | Notes |
|--------|---------|-------|
| HTTP core | `server.js`, `api.js`, `http-error.js`, `rate-limit.js`, `net-guard.js`, `realtime-bus.js` | `server.js`: static serving, CSP nonce stamping, theme early-paint, health/robots/sitemap. `net-guard.js`: the SSRF guard (`safePublicUrl`). `realtime-bus.js`: the in-process SSE channel bus (`conv:`, `admin:support`, `comp:` — reused by chat, comments, and agent events). |
| Auth, identity & admin | `auth.js`, `session.js`, `account.js`, `password-reset.js`, `email.js`, `email-verification.js`, `permissions.js`, `modes.js`, `admin-api.js`, `god-console.js`, `team.js` | scrypt + HS256 JWT sessions; God Mode admin routes; team roles/invites (collab). Email sends via the usermails provider ([configuration.md](configuration.md)). |
| **Agent kernel** | `agent.js`, `agent-tools.js`, `agent-ask.js`, `agent-context.js`, `agent-recipe.js`, `agent-runs.js`, `agent-eval.js` | Two-phase plan/execute, live tool registry, workspace grounding, plan→recipe conversion, `agent_runs` audit (032), eval. See [agent-kernel.md](agent-kernel.md). |
| Generation & models | `models.js`, `providers.js`, `vertex.js`, `generation.js`, `generation-jobs.js`, `director.js`, `director-eval.js`, `producer.js`, `camera.js`, `inference.js`, `eval.js`, `gemini-cache.js`, `embeddings.js`, `prompts/` | Central model registry + quality-tier routing; the film director/producer; camera-move channel; inference tracing; context caching; the portable prompt-spec registry. |
| Media modalities | `voice.js`, `voice-design.js`, `music.js`, `soundscape.js`, `imagen.js`, `image-edit.js`, `image-assist.js`, `captions.js`, `enhance.js` | Chirp TTS + describe-a-voice, Lyria, Imagen generate/edit/assist, STT captions + translation, prompt/brand-voice enhance. |
| **Image AI & pixel engines** | `upscale.js`, `upscale-engine.js`, `remove-bg-engine.js`, `vectorize-engine.js`, `audio-fx-engine.js` | App-side adapters for the worker-hosted DSP/pixel services (each behind a `*_PORT`/`*_URL` seam). |
| **Auto-Clips** | `highlights.js`, `auto-clips.js`, `autoclips-proxy.js`, `caption-styles.js`, `caption-generate.js`, `story-narrator.js`, `voice-presets.js`, `manifest-builder.js`, `reframe.js`, `shorts.js`, `media-fetch.js` | Long-form → ranked highlights → captioned/voiced vertical shorts; 9 caption personas; story mode; hardened media fetch. See [auto-clips-pipeline.md](auto-clips-pipeline.md). |
| **Audio sessions** | `audio-sessions.js` | Server mirror of the editor's at-rest `audioSessions` manifest split (deploy-skew-safe). |
| Compositions & render | `render.js`, `render-engine.js`, `render-worker.js`, `render-qa.js`, `render-qa-analyzer.js`, `qa.js`, `qa-plan.js`, `qa-structure.js`, `qa-analyzer.js`, `composition-versions.js`, `hyperframes.js` | Render enqueue + engine seam; the alternate-mode queue worker; post-render QA15; automatic composition version snapshots (028). |
| **JSON engine & platform API** | `json-engine.js`, `json-api.js`, `catalog.js`, `api-keys.js` | The dependency-free query/command engine over compositions; the model/API catalog; `cr_live_` key auth (018). See [json-engine.md](json-engine.md). |
| **Files pillar** | `assets.js`, `collections.js`, `content-credentials.js`, `gallery.js`, `storage.js` | The unified file repo: assets rows + collections (031), Ed25519-signed content credentials, semantic media search, MinIO presign/proxy. |
| **Social & distribution** | `social.js`, `ghl.js`, `crypto-box.js`, `analytics.js`, `leads.js` | Publishing/scheduling through the GoHighLevel relay (029), AES-256-GCM secret-at-rest for third-party tokens, first-party analytics events (023), lead capture (024). |
| **Collaboration** | `comments.js`, `composition-versions.js`, `team.js`, `proofing.js` | Editor comment threads with SSE (030), version history/restore, team roles, tokenized client proofing (022). |
| **Chat & self-heal** | `chat.js`, `chat-routes.js`, `chat-kb.js`, `chat-config.js`, `chat-safety.js`, `chat-handoff.js`, `chat-handoff-routes.js`, `admin-chat-api.js`, `support.js`, `self-heal.js` | Grounded pre-sales/support chat (027), human handoff, God-Mode live-agent cockpit, tickets, repair briefs. See [chat-system.md](chat-system.md). |
| **Brands & theming** | `brands.js`, `brand-kit.js`, `brand-generate.js`, `theme-settings.js` | The Account→Brand→Project cascade (025) + storage grants (026); legacy workspace brand kit (021); white-label workspace themes (033). |
| **Recipes & workflows** | `recipes.js`, `recipe-runner.js`, `recipe-starters.js`, `checkpoints.js`, `budget.js`, `csv.js`, `workflow-planner.js`, `campaign-planner.js`, `campaigns.js`, `algorithms.js`, `data.js`, `index.js` | JSON workflow recipes (016) + autopilot schedules, review checkpoints (019), budget governance, bulk CSV, AI workflow/campaign planners, channel profiles. |
| Client ops (Pro) | `crm.js`, `tasks.js`, `booking.js`, `automation.js`, `connections.js`, `meeting.js`, `import.js` | CRM/tasks/booking/automations (007–010, 014) + meeting briefs and URL import. See [client-ops.md](client-ops.md). |
| Write pillar & content | `content.js`, `content-store.js`, `content/` (template registry + quality), `scripts.js`, `personas.js`, `voice-agent/` | Templated copywriting (020), script studio, consent-gated personas, and the real-time voice-agent WebSocket bridge (browser + Twilio). |
| Billing | `billing.js`, `cost-model.js` | Stripe + the credit ledger + `USAGE_COSTS`; vendor cost model. See [billing.md](billing.md). |
| Public site | `blog.js`, `blog-markdown.js`, `blog-render.js`, `blog-render-chrome.js`, `case-studies.js`, `case-study-render.js`, `testimonials.js`, `votes.js`, `preferences.js`, `kb.js` | File-based journal + server-rendered case studies, testimonials, gallery votes, preference briefs, the workspace knowledge base (013). |
| Data layer | `database.js`, `env.js` | `pg` pool + query/transaction helpers; minimal `.env` loader. |

### Editor (`editor/src/editor/`) highlights

One shared undoable store, eight studio modes switched by `studio-mode.tsx`: **video** (timeline NLE), **audio-studio**, **image-studio**, **brand-studio**, **slide-studio**, **diagram-studio** (Excalidraw), **workflow-studio** (live node graph + the in-house **CrFlow** canvas engine at `workflow-studio/graph/flow/` — React Flow was removed), and **write**. Cross-cutting modules worth knowing: `animation/` (keyframe engine — `keyframes.ts` is the single easing authority), `agent/` (the agent panel), `activity/` (global progress/toast bus), `console/` + `json-api/` (the JSON console), `captioning/`, `comments/`, `export/` (PNG/JPG/WebP/SVG/PDF/PPTX), `timeline/grid/` (SMPTE/BPM grid + snapping), `state/` (store + actions). Full tour: [editor.md](editor.md).

## Four deployables

Production runs **four** pieces (see [deployment.md](deployment.md) for the operational detail):

| Deployable | Source | How it deploys | Public domain |
|------------|--------|----------------|---------------|
| **API / app** | `src/` + `public/` (`npm start`) | Coolify app, git `main` auto-deploy | `corereflex.com` |
| **Editor studio** | `editor/` (`react-router build`, SPA, SSR off) | Coolify app | `editor.corereflex.com` |
| **Render worker** | `render-worker/` (`node worker.js`) | Manual `docker run` container on the App box (`--restart unless-stopped`) | none — polls `render_jobs` |
| **Clip proxy** | `render-worker/clip-proxy*` files (reuses the worker image) | Manual `docker run` container (`corereflex-clip-proxy`, `:9099` on the coolify network) | none — long-video prepare for Auto-Clips |

All four share one Postgres database and one MinIO bucket on the private fleet. Two env gates on the API app must stay set for the full pipeline: `RENDER_ENABLED=true` (renders enqueue instead of returning an honest 503) and `CLIP_PROXY_URL` (long-video prepare), with `RENDER_SHARED_SECRET` matching on both sides — see [auto-clips-infra.md](auto-clips-infra.md).

**Version lockstep rule:** the worker's `@remotion/bundler`/`@remotion/renderer` must match the editor's `remotion` version exactly (both `4.0.483` today). A mismatch breaks video bundling.

## Public pages

Routes served by `src/server.js` (all from `public/`, themed, CSP-nonced, `no-store`):

| Route | File | What it is |
|-------|------|------------|
| `/` | `home.html` | Marketing homepage. |
| `/app`, `/dashboard`, `/admin`, `/sign-in`, `/login` | `dashboard.html` | The canonical studio hub (God Console is a route inside it). |
| `/auto-clips` | `auto-clips.html` | The self-contained Auto-Clips studio. |
| `/book`, `/book/:slug` | `book.html` | White-label public booking page. |
| `/proof`, `/proof/:token` | `proof.html` | Tokenized client review/approval surface. |
| `/voice` | `voice.html` | Voice-agent web widget page. |
| `/pricing`, `/terms`, `/privacy` | `pricing.html`, `terms.html`, `privacy.html` | Marketing/legal pages (honest — no fake prices or certifications). |
| `/docs` | `docs.html` | Public docs page. |
| `/blog`, `/blog/:slug`, `/blog/category/*` | `blog.html` + `src/blog-render.js` | File-based journal (server-rendered posts). |
| `/case-studies`, `/case-studies/:slug` | `src/case-study-render.js` | Server-rendered case studies. |
| `/healthz`, `/robots.txt`, `/sitemap.xml`, `/js/analytics.js` | inline | Liveness probe, SEO, first-party analytics snippet. |

Every response also sends `Alt-Svc: clear` (defensive HTTP/3 cache reset).

## Quick start (local)

```bash
# Root API / app
cp .env.example .env          # fill DATABASE_URL, JWT_SECRET, ASSET_* (see configuration.md)
npm install
npm run db:migrate            # apply migrations/ via scripts/migrate.mjs
npm start                     # node src/server.js → http://localhost:4173

# Editor studio (separate process; Node ≥ 22)
cd editor && npm install && npm run dev   # proxies /api to CORE_API_TARGET (default http://localhost:4173)
```

Local rendering has two modes (details + env in [render-worker.md](render-worker.md)):

```bash
# Production-parity: the in-container renderer (needs DB + MinIO env; bundles editor/src/remotion)
cd render-worker && npm install && npm start

# Alternate mode: queue worker + standalone render HTTP service
cd editor && npm run render-service       # Remotion render service on :8088
RENDER_ENABLED=true RENDER_WORKER_URL=http://localhost:8088 npm run worker
```

`npm run build` runs the lint/syntax gate (`scripts/check-syntax.mjs`); `npm run verify:backend` runs the backend smoke test. See [contributing.md](contributing.md) for the planning loop and commit conventions.

## Testing

| Suite | Where | Run |
|-------|-------|-----|
| Server (~160 files: API, agent, billing, auto-clips, chat, recipes, …) | `test/` | `npm test` (Node's built-in runner) |
| Render worker + sidecar services | `render-worker/*.test.js` | `cd render-worker && node --test` |
| Editor (state actions, animation, captioning, JSON parity, CrFlow, …) | `editor/src/editor/**/*.test.*` | per-file `node --test` invocations — see [editor.md](editor.md) |

The JSON-engine parity tests lock the editor and server command sets together; the workflow-graph parity test locks builder templates to the server's `STEP_KINDS`. Treat parity failures as contract breaks, not flaky tests.

## Production status

Everything documented in this folder is **live** unless the doc says otherwise. In particular:

- **Rendering is live in prod** — the render worker has been proven end-to-end (real composition → MinIO), `RENDER_ENABLED=true` is durable in the Coolify env store, and the Auto-Clips pipeline (detect → cut → render → captions/voice → library) works end to end, including long-video prepare through the clip-proxy container.
- The historical "render worker not yet deployed / `POST /api/render` returns 503" framing is obsolete; the 503 now only appears if the `RENDER_ENABLED` gate is deliberately unset.
- Deferred/roadmap items live where they can't be mistaken for shipped features: [`../user/coming-soon.md`](../user/coming-soon.md) (product framing) and `planning/` (engineering backlog).

## Deep dives & references one level up

Strategy and infrastructure references live in [`docs/`](../README.md):

- [../MODEL-ROUTER.md](../MODEL-ROUTER.md) — capability-driven model registry, routing policy, and resolution tiers.
- [../PROMPTING.md](../PROMPTING.md) — the four-layer prompting system (schema → director → LLM-judge → execution).
- [../UPSCALING-8K.md](../UPSCALING-8K.md) — the governed 8K "Master" stage and loss-free punch-in / reframes.
- [../ASSET-SERVING.md](../ASSET-SERVING.md) — the signed app proxy that streams private-fleet MinIO footage to the browser.
- [../AGENTIC-ADK.md](../AGENTIC-ADK.md) — the original orchestration/memory/eval design note. **Historical**: the shipped implementation is documented in [agent-kernel.md](agent-kernel.md).
- [../REMOTION-LICENSE.md](../REMOTION-LICENSE.md) — Remotion company-license obligations to confirm before commercial use.
- [../BOOTSPRING-HANDOFF.md](../BOOTSPRING-HANDOFF.md) and [../HANDOFF-2026-06-28.md](../HANDOFF-2026-06-28.md) — pause-state handoffs: infra, shipped work, queue, verification commands.

User-facing documentation lives in [`docs/user/`](../user/README.md) — task-oriented guides for every studio, written for non-technical readers.