@oneie/claude 0.1.0

package/commands/close.md

@@ -0,0 +1,143 @@
+# /close
+
+**Skills:** `/signal` (4-outcome grammar: result / timeout / dissolved / failure) · `/typedb` (mark-dims, rubric scoring, write completion)
+
+Mark a result — close the signal loop.
+
+## Flags
+
+| Flag | Signal | Outcome | Loop |
+|------|--------|---------|------|
+| `<task-id>` | mark() | result — chain strengthens | L2 |
+| `<task-id> --fail` | warn(1) | failure — full warn, chain breaks | L2 |
+| `<task-id> --dissolved` | warn(0.5) | dissolved — mild warn | L2 |
+| `<task-id> --timeout` | neutral | timeout — slow, not bad | L2 |
+| *(no arg)* | mark() + tick | session report — record all outcomes | L2, L6 |
+| `--todo <slug> --wave N` | emit `do:close` | wave close (soft gate) — append learnings.md; next wave proceeds if skipped | L1, L6 |
+| `--todo <slug> --cycle N` | emit `do:close` | cycle close (**hard gate**) — verify learnings grew; block next cycle if missing | L1, L2, L6 |
+| `--todo <slug> --cycle N --wave N` | emit `do:close` | specific wave of a cycle — used for re-running a failed close | L1 |
+
+## Routing
+
+`/close` maps to `mark()` or `warn()` — the human emitting the Four Outcomes
+signal back into the substrate. Rule 1 (Closed Loop): every signal must close.
+Without `/close`, paths cannot learn.
+
+## Four Outcomes Reference (smoke)
+
+The four flags map 1:1 to the Four Outcomes from routing.md:
+
+```
+result     → /close <id>              mark()    strength++   chain strengthens
+timeout    → /close <id> --timeout    neutral   no change    chain continues
+dissolved  → /close <id> --dissolved  warn(0.5) resist+=0.5  mild — path missing
+failure    → /close <id> --fail       warn(1)   resist+=1    full — agent failed
+```
+
+Every possible outcome has a corresponding `/close` flag. No outcome goes unmarked.
+This is Rule 1 enforced at the human boundary.
+
+## Steps
+
+### `<task-id>` — success
+
+1. Run W4 gate — score code rubric (each dimension 0–1, composite ≥ 0.65 to close):
+   - **security**:   no injections, no secrets, all API routes validated
+   - **stability**:  tests pass, zero type errors, every handler closes its loop
+   - **simplicity**: files focused, functions ≤ 20 lines, no ceremony beyond scope
+   - **speed**:      Lighthouse held, bundle ≤ W0, tokens lean, cache hit ≥ 80%
+   - composite: `0.35·security + 0.30·stability + 0.25·simplicity + 0.10·speed`
+2. POST `http://localhost:4321/api/tasks/{id}/complete`
+3. POST `http://localhost:4321/api/loop/mark-dims` with `{ security, stability, simplicity, speed }`:
+   - Dim ≥ 0.5 → mark() on that dimension path (strength++)
+   - Dim < 0.5 → warn() on that dimension path (resistance++)
+4. Self-checkoff: update task checkbox in the TODO file `[ ]` → `[x]`
+5. **Emit feedback signal** — POST `http://localhost:4321/api/signal`:
+   ```json
+   {
+     "receiver": "loop:feedback",
+     "data": {
+       "tags": ["<task-tags>"],
+       "strength": "<composite 0–1>",
+       "content": {
+         "task_id": "<id>",
+         "rubric": { "security": X, "stability": Y, "simplicity": Z, "speed": W },
+         "composite": N,
+         "velocity": "±N",
+         "outcome": "result"
+       }
+     }
+   }
+   ```
+   This is the return-path pheromone. Future agents with matching tags follow this trail.
+   `composite >= 0.65` → mark each tag path. `composite < 0.65` → warn(0.5) each tag path.
+6. Report unlocked tasks (tasks where this was in their `blocks` list)
+7. **Propagate to docs** — auto-edit when triggers from the cycle's `.w2-doc-plan.json` match. Zero agent spawns; all bash + Edit tool.
+
+   | Trigger from W3 diff | Target | Edit |
+   |---|---|---|
+   | new MCP / CLI / SDK / API export | root `README.md` § public surface | append row |
+   | new component family or directory | nearest `one.ie/web/src/components/*/CLAUDE.md` | append section |
+   | 6-dim, L1-L8, or locked-rule change | root `CLAUDE.md` | edit relevant section |
+   | feature doc named in plan `source_of_truth` | feature doc | sync verb/component/endpoint counts |
+   | rename across W3 | every `.md` containing old name (W4 stale-name list) | already done by W3 grep |
+
+   For each trigger, the bash dispatcher reads the W3 diff, locates the anchor in the target doc, and applies the Edit tool inline. Anchor mismatch → log to `docs/improvements.md` for manual W2 next cycle (no halt).
+
+8. Report:
+   ```
+   mark(+5) on <from>→<to>
+   Rubric: security=X  stability=Y  simplicity=Z  speed=W  composite=N  velocity=±N
+   Feedback: signal emitted → loop:feedback  tags=[<tags>]  strength=N
+   Propagate: docs=N edited  triggers=[<codes>]  manual=N
+   Unlocked: N tasks
+   ```
+
+### `--fail`
+
+1. POST `http://localhost:4321/api/tasks/{id}/complete` with `{ failed: true }`
+2. warn(1) — resistance += 1 on the path. Full failure, chain breaks.
+3. Report:
+   ```
+   warn(1) on <from>→<to>
+   Full failure — resistance++. Chain breaks.
+   ```
+
+### `--dissolved`
+
+1. POST `http://localhost:4321/api/tasks/{id}/complete` with `{ dissolved: true }`
+2. warn(0.5) — resistance += 0.5. Mild warn — path doesn't exist yet.
+3. Report:
+   ```
+   warn(0.5) on <from>→<to>
+   Dissolved — missing unit/capability. Mild warn. Chain breaks.
+   ```
+
+### `--timeout`
+
+1. POST `http://localhost:4321/api/tasks/{id}/complete` with `{ timeout: true }`
+2. No mark, no warn — neutral. Slow, not bad.
+3. Report:
+   ```
+   neutral on <from>→<to>
+   Timeout — slow, not bad. Chain continues.
+   ```
+
+### *(no arg)* — session report
+
+1. Read git diff: `git diff --stat HEAD` — what changed this session
+2. For each completed task this session: POST `/api/tasks/{id}/complete`
+3. POST `http://localhost:4321/api/tick` — process accumulated pheromone
+4. Report session outcomes (numbers first):
+   ```
+   Session:    N tasks completed  M tests  K commits
+   Pheromone:  N marks  M warns this session
+   Rubric:     security=X  stability=Y  simplicity=Z  speed=W  composite=N  velocity=±N  (session averages)
+   Hardened:   N highways promoted to permanent (L6)
+   Frontiers:  N new unexplored clusters (L7)
+   Next:       1. <task>  priority=N  2. <task>  priority=M  3. <task>  priority=K
+   ```
+
+---
+
+*`/close` is `mark()` made human-readable. Every outcome must close its loop.*

package/commands/create.md

@@ -0,0 +1,78 @@
+# /create
+
+**Skills:** `/typedb` (write new entity) · `/signal` (emit creation, `ui:*` or `cli:create:*`)
+
+Emit a new entity into the substrate.
+
+## Nouns
+
+| Noun | What | Loop |
+|------|------|------|
+| `task <name> [--tags T] [--weight W]` | Atomic task into TypeDB via API | L1 |
+| `todo <source-doc?>` | TODO from template (Haiku extract + wave structure) | L1 |
+| `agent <markdown-file>` | Parse agent.md frontmatter → TypeDB unit + skills | L1 |
+| `signal <receiver> <data>` | Ad-hoc signal emission for testing | L1 |
+
+## Routing
+
+`/create` maps to `send()` — emit new entity or signal into the substrate.
+Every noun writes to TypeDB and/or the in-memory queue.
+
+| Noun | Primitive | Destination |
+|------|-----------|-------------|
+| task | `send()` | POST `/api/tasks` |
+| todo | `send()` | Write `docs/{name}-todo.md` + POST `/api/tasks/sync` |
+| agent | `send()` | `agent-md.ts` → TypeDB unit + skills + capabilities |
+| signal | `send()` | POST `/api/signal` |
+
+## Steps
+
+### task
+
+1. Parse `$ARGUMENTS` into task fields:
+   - id (kebab-case from name), name
+   - value: critical / high / medium
+   - phase: C1-C7
+   - persona: ceo / dev / investor / gamer / kid / freelancer / agent
+   - tags (space-separated), blocks (other task IDs), exit condition
+2. Compute priority: value + phase + persona + blocking weight (max 115, min 35)
+3. POST to `http://localhost:4321/api/tasks` with JSON body
+4. Confirm created task: id, name, priority score + formula, tags
+5. Suggest `/see tasks` to view ranked list
+
+### todo
+
+1. Resolve source doc from `$ARGUMENTS`: try full path → `docs/$ARGUMENTS` → `docs/$ARGUMENTS.md`
+2. Run Haiku one-shot to extract raw tasks (~$0.004):
+   - Read doc, extract actionable items as checkbox tasks with metadata
+3. Load base context: `one/dictionary.md`, `one/rubrics.md`, `one/template-todo.md`
+4. Promote raw tasks into full wave template:
+   - Group by cycles (Wire → Prove → Grow) and waves (W1=Haiku, W2=Opus, W3=Sonnet, W4=Sonnet)
+   - Assign full metadata per task: id, value, effort, phase, persona, blocks, exit, tags
+   - Include: routing diagram, schema reference, wave structure, rubric scoring in W4, self-checkoff
+5. Write `docs/{docname}-todo.md`
+6. Verify: all tasks have 7 metadata fields, blocks references are valid, exit conditions are verifiable
+7. Report: cycle count, tasks per cycle, critical path, cost estimate
+
+### agent
+
+1. Read `<markdown-file>` (frontmatter: name, model, channels, group, skills, sensitivity)
+2. Parse via `src/engine/agent-md.ts` → `AgentSpec`
+3. Sync to TypeDB:
+   - Unit: uid, name, model, system-prompt, tags
+   - Skills: skill-id, name, price, tags per skill
+   - Capabilities: (provider: unit, offered: skill) relation
+   - Group membership: (group: $g, member: unit) relation
+4. Report: uid, model, skills count, group, TypeDB insert count
+
+### signal
+
+1. Parse `<receiver>` and `<data>` from `$ARGUMENTS`
+   - receiver: string (e.g. `bob:schema`, `analyst`)
+   - data: JSON or plain string
+2. POST to `http://localhost:4321/api/signal` with `{ receiver, data }`
+3. Report: signal sent, response outcome (result / timeout / dissolved / failure), any path marks triggered
+
+---
+
+*Every `/create` is a `send()` call — a new signal enters the world.*

package/commands/deploy.md

@@ -0,0 +1,415 @@
+# /deploy
+
+**Skills:** `/cloudflare` (Workers auth) · `/signal` (deploy:success / deploy:degraded)
+
+Ship all four services to Cloudflare. Deterministic sandwich — W0 baseline, build, smoke, approval, parallel deploy, health.
+
+> **Production cutover (2026-05-23):** Astro site runs on **CF Workers with Static Assets** (not Pages). Production target is **`https://one.ie`** via the `one-prod` worker. Deploy command is `wrangler deploy --env production`.
+>
+> **Environment model:**
+> - **Production (live):** `https://one.ie` — `one-prod` worker, deployed from `one.ie/web/` via `wrangler deploy --env production`
+> - **Dev (live):** `https://dev.one.ie` — `one-substrate` worker, deployed on every `main` push
+> - **Gateway (live, stable):** `https://api.one.ie` — `one-gateway` worker
+> - **Legacy idle (rollback only — do not deploy):**
+>   - `https://oneie.pages.dev` — old Pages project for `one.ie` ("Ecommerce Playbook" content). Re-attach `one.ie` to this project to roll back.
+>   - `app.one.ie`, `demo.one.ie`, `onestudio.dev` — still bound to the prior `one-demo` worker. `one-demo` stays in the account untouched for rollback; redeploying `one-demo` would push stale code, so don't.
+>   - `https://one-substrate.pages.dev` — paused Pages project, rollback only.
+>
+> See `docs/cf-workers-migration-todo.md` for migration history. The custom-domain detach step (Pages → Worker) is done manually via the CF API (no in-repo script today).
+
+## Modes
+
+| Invocation | What |
+|-----------|------|
+| `/deploy` | Full pipeline — W0 + build + 4 services + health |
+| `/deploy --skip-tests` | Skip W0 baseline (risky — use only when already verified) |
+| `/deploy --dry-run` | Build + smoke only, no deploy |
+| `/deploy --preview-only` | Build + preview Worker deploy (no CI-gated services) |
+| `/deploy astro` | Astro Worker only (re-bundle after UI changes) |
+| `/deploy workers` | Gateway + Sync + Agents only (no Astro rebuild) |
+| `/deploy gateway` | Gateway worker only |
+| `/deploy sync` | Sync worker only |
+| `/deploy agents` | Agents edge agents only |
+
+## The 8-Step Pipeline
+
+```bash
+bun run deploy          # full pipeline
+bun run deploy -- --dry-run
+bun run deploy -- --skip-tests
+DEPLOY_CONFIRM=yes bun run deploy   # CI / non-interactive
+```
+
+**Step 1 — W0 Baseline**
+```bash
+bun run verify   # biome + tsc --noEmit + vitest run + audit:design
+```
+Record tests passed/total. Fix before proceeding — never deploy on red.
+
+**Step 2 — Changes**
+`git diff` summary. Flag large changesets.
+
+**Step 3 — Build**
+```bash
+NODE_ENV=production astro build
+```
+Target: ~23s. Emits `dist/_worker.js/index.js` + static assets via `@astrojs/cloudflare@13`. Watch for bundle size warnings.
+
+**Step 4 — Credentials**
+`CLOUDFLARE_API_TOKEN` must be unset. Deploy uses `CLOUDFLARE_GLOBAL_API_KEY` only.
+Scoped tokens lack permissions for workers + custom domains.
+
+**Step 5 — Smoke**
+Verify `dist/server/` exists, all 4 wrangler configs present: `api/wrangler.toml`, `sync/wrangler.toml`, `agents/wrangler.toml`, root `wrangler.toml`.
+
+**Step 6 — Approval**
+`main` branch: prompts "yes". Other branches: auto-approved.
+CI: `DEPLOY_CONFIRM=yes bun run deploy` (already set in `.github/workflows/deploy.yml`).
+
+**Step 6.5 — D1 Migrations**
+Run before any worker deploy so schema is current when new code lands:
+```bash
+cd one.ie/web && bunx wrangler d1 migrations apply DB --remote --env production
+```
+"✅ No migrations to apply!" is a pass. Any applied migration is logged and counted.
+Migration failures block deploy — never ship worker code ahead of its schema.
+
+**Step 7 — Deploy (parallel workers + astro)**
+Gateway + Sync + Agents deploy in parallel (~16s). Astro Worker deploys after (~16s).
+
+**Step 8 — Health**
+```bash
+curl https://api.one.ie/health                   # Gateway
+curl https://one.ie/api/health                   # Astro Worker (production)
+curl https://one-sync.oneie.workers.dev/         # Sync
+curl https://agents.oneie.workers.dev/health   # Agents
+```
+3 retries with backoff. All 4 must return 200. Astro `/api/health` must report `units: 140` (or current count) — empty `units: 0` means the build didn't bake `PUBLIC_GATEWAY_URL` correctly.
+
+---
+
+## Bundle Size Rules (CF Workers Free Tier — 3 MiB gzipped upload)
+
+The Astro Worker upload must stay under **3 MiB gzipped** on the free tier (10 MiB
+on paid). Wrangler reports both `Total Upload` (uncompressed) and `gzip` — only
+gzip counts toward the ceiling. All chunks in `dist/server/chunks/` are uploaded
+together; dynamic `await import()` does NOT exclude code from the upload.
+
+These rules are **LOCKED** — do not revert them. Apply identically to any
+developer template we ship (`oneie init` Workers scaffold mirrors this shape).
+
+### Rule 1 — `syntaxHighlight: false` in `astro.config.mjs`
+
+```js
+markdown: { syntaxHighlight: false }
+```
+
+Disables Shiki from Astro's markdown pipeline. Without this, Shiki pulls ~5.8 MiB of
+language grammar files into the SSR worker on every build. **Do not re-enable.**
+
+### Rule 2 — `ssr.external` for heavy packages
+
+```js
+ssr: {
+  external: ["node:async_hooks", "@mysten/sui", "@mysten/bcs", "shiki", "@shikijs/core", "@shikijs/types"]
+}
+```
+
+The CF adapter bundles everything by default. `ssr.external` creates a bare
+`import { x } from 'pkg'` reference without inlining the package.
+
+**Critical nuance:** `ssr.external` only works safely when the externalized package is
+never executed on the server path. For `shiki`: `codeToHtml` is imported by `code-block.tsx`,
+but all components that use `code-block.tsx` are `client:only` — so `codeToHtml` is never
+called in the worker. The import statement exists in the bundle but is dead code.
+
+If you add a new heavy dependency used only client-side, add it here.
+
+### Rule 3 — Pure-shell pages use `client:only` + `prerender = true`
+
+```astro
+---
+export const prerender = true
+import { MyComponent } from "@/components/MyComponent"
+---
+<Layout title="...">
+  <MyComponent client:only="react" />
+</Layout>
+```
+
+`client:only="react"` — Astro renders an empty div on the server; the component never
+runs in the worker. The React component tree (+ all its imports) stays out of the SSR bundle.
+
+`export const prerender = true` — the page becomes a static asset generated once
+at build time. The page's SSR handler collapses to a small stub. Zero worker cost
+at runtime.
+
+**Use this pattern for:** any page that has no server-side data dependencies
+(no `Astro.locals`, no `Astro.request`, no DB queries in frontmatter).
+
+Currently prerendered (verify with `grep -l "export const prerender = true" src/pages/*.astro`):
+`404.astro`, `board.astro`, `build.astro`, `ceo.astro`, `chat.astro`, `chat-agents.astro`,
+`chat-fast.astro`, `chat-routing.astro`, `in.astro`, `speed.astro`.
+
+Pages that CANNOT be prerendered (need runtime session/auth):
+`world.astro` (reads `Astro.locals.session`), `market.astro` (fetches capabilities).
+
+### Rule 4 — `inlineStylesheets: 'auto'` in `astro.config.mjs`
+
+```js
+build: { inlineStylesheets: 'auto' },   // ← NEVER 'always'
+```
+
+With `'always'`, Astro inlines the full Tailwind stylesheet into **every route's
+serialized manifest entry**. With ~100 routes the entry chunk balloons by 8+ MiB
+of duplicated CSS as a single string literal — diagnosable in worker-entry at
+the line `const _manifest = deserializeManifest({...})`.
+
+`'auto'` ships the bundle as one external `<link rel="stylesheet">` referenced
+once across all routes. Browsers cache it across navigations — a page-speed
+win, not just a worker-size win.
+
+**Verified 2026-05-22:** flipping `always` → `auto` dropped worker-entry from
+9.5 MiB → 672 KiB and total gzip from 3302 KiB → 2079 KiB.
+
+### Rule 5 — `react-dom/server.edge` alias (production only)
+
+```js
+resolve: {
+  alias: {
+    ...(isDev ? {} : { "react-dom/server": "react-dom/server.edge" })
+  }
+}
+```
+
+Already in `astro.config.mjs`. Required for CF Edge runtime compatibility.
+Do not remove for production builds.
+
+---
+
+## Verified Bundle Numbers
+
+| Snapshot | Total upload | gzip | Worker-entry | What changed |
+|---|---|---|---|---|
+| 2026-04-18 (post Pages→Workers migration) | — | — | 9.5 MiB | Rules 1-3 + 5 |
+| 2026-05-22 before `inlineStylesheets` fix | 18.5 MiB | 3.3 MiB | 9.5 MiB | Over 3 MiB ceiling — deploy FAILED |
+| 2026-05-22 after Rule 4 (`'always'` → `'auto'`) | 10.1 MiB | **2.1 MiB** | **672 KiB** | Under ceiling — deploy ✓ |
+
+The 2026-05-22 regression was caused by `build: { inlineStylesheets: 'always' }`
+inlining the full Tailwind stylesheet into every route's manifest entry. One
+char change (`always` → `auto`) saved 8.8 MiB.
+
+---
+
+## Service Map (post-migration)
+
+| Service | URL | Config | Deploy command |
+|---------|-----|--------|---------------|
+| Astro Worker (prod) | `one.ie` → `one-prod` | `one.ie/web/wrangler.toml` | `cd one.ie/web && wrangler deploy --env production` |
+| Astro Worker (dev) | `dev.one.ie` → `one-substrate` | `wrangler.toml` (root) | `wrangler deploy` |
+| Gateway | `api.one.ie` → `one-gateway` | `api/wrangler.toml` | `cd api && wrangler deploy` |
+| Sync | `one-sync.oneie.workers.dev` | `sync/wrangler.toml` | `cd sync && wrangler deploy` |
+| Agents | `agents.oneie.workers.dev` | `agents/wrangler.toml` | `cd agents && wrangler deploy` |
+| Pages (legacy idle, rollback) | `oneie.pages.dev` | — | **do not deploy** — rollback target for `one.ie` |
+| Worker (legacy idle, rollback) | `one-demo` (still serves `app.one.ie`, `demo.one.ie`, `onestudio.dev`) | — | **do not deploy** — rollback window for the prod cutover |
+
+---
+
+## Auth (CRITICAL — never change)
+
+Always: `CLOUDFLARE_GLOBAL_API_KEY` + `CLOUDFLARE_EMAIL`.
+Never: `CLOUDFLARE_API_TOKEN` (scoped token lacks workers + custom domain permissions).
+
+The deploy script auto-unsets `CLOUDFLARE_API_TOKEN` from the spawned env to prevent
+accidental use of a scoped token that was exported in the shell.
+
+CI secrets required in `.github/workflows/deploy.yml` env block:
+- `CLOUDFLARE_API_KEY` (mapped from `secrets.CLOUDFLARE_GLOBAL_API_KEY`)
+- `CLOUDFLARE_EMAIL`
+- `CLOUDFLARE_ACCOUNT_ID`
+- `CLOUDFLARE_API_TOKEN: ''` (explicit blank)
+- `DEPLOY_CONFIRM: 'yes'`
+- `PUBLIC_GATEWAY_URL: https://api.one.ie` (build-time-inlined by Astro — **required**; without this the Worker bundle falls back to `one-gateway.oneie.workers.dev` and `/api/health` returns `units: 0`)
+
+---
+
+## Steps
+
+### `/deploy` (full pipeline)
+
+1. `bun run verify` — W0 gate. Fail here means don't deploy.
+2. `git diff` summary — surface scope to user.
+3. `NODE_ENV=production bun run build` — Astro production build.
+4. Verify credentials: assert `CLOUDFLARE_GLOBAL_API_KEY` present, unset `CLOUDFLARE_API_TOKEN`.
+5. Smoke check: assert `dist/_worker.js/` exists, all 4 wrangler configs present.
+6. Approval gate: prompt on `main`, auto on other branches.
+7. Parallel deploy: Gateway + Sync + Agents concurrently, then Astro Worker.
+8. Health checks: all 4 endpoints × 3 retries with backoff.
+9. Report:
+   ```
+   Branch:     main
+   Tests:      320/320 pass
+   Build:      23.2s
+   Migrations: 2 applied (0 already up-to-date)
+   Workers:    parallel 16.7s (vs ~42s sequential)
+   Astro:      16.1s
+   Health:     4/4 (Gateway 308ms, Astro 666ms, Sync 287ms, Agents 287ms)
+   Preview:    https://<hash>.one-substrate.<account>.workers.dev
+   Total:      ~65s
+   ```
+
+### `/deploy astro`
+
+Deploys the production worker (`one-prod`) to `one.ie` from the `one.ie/web/` directory.
+
+1. `cd one.ie/web && NODE_ENV=production bun run build`
+2. Check bundle size: `du -sh one.ie/web/dist/server/`
+3. If > 12 MiB: check which chunk grew (`ls -lhS one.ie/web/dist/server/chunks/ | head -15`)
+4. Run D1 migrations: `cd one.ie/web && bunx wrangler d1 migrations apply DB --remote --env production`
+5. `cd one.ie/web && bunx wrangler deploy --env production`
+6. Health: `curl -sL https://one.ie/api/health` (expect 200, `units > 0`)
+
+**Pre-flight (one-time, on cutover only):** ensure no other CF entity owns the `one.ie` custom domain. If wrangler errors with a hostname conflict, detach the prior owner first:
+
+```bash
+# If a Pages project owns it (was `oneie` project pre-cutover):
+curl -s -X DELETE \
+  "https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/pages/projects/oneie/domains/one.ie" \
+  -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
+  -H "X-Auth-Key: $CLOUDFLARE_GLOBAL_API_KEY"
+```
+
+### `/deploy workers`
+
+```bash
+cd api && bun wrangler deploy && cd ../workers/sync && bun wrangler deploy && cd ../../agents && bun wrangler deploy && cd ..
+```
+
+Report: version hash per worker, health latency per service.
+
+### Cutover tool (`scripts/cf-cutover.ts`)
+
+For Pages→Workers custom-domain flips on other services (script is parameterized):
+
+```bash
+bun run cf-cutover                # dry-run, safe
+bun run cf-cutover --execute      # real cutover: Workers route + Pages detach + health verify + substrate signal
+```
+
+Defaults: domain=`dev.one.ie`, worker=`one-substrate`, pages=`one-substrate`. Override via `CF_CUTOVER_DOMAIN`, `CF_CUTOVER_WORKER`, `CF_CUTOVER_PAGES_PROJECT` env vars.
+
+---
+
+## Bundle Size Diagnosis
+
+If build fails with "exceeds size limit":
+
+```bash
+# Check total worker size
+du -sh dist/server/
+
+# Find top offenders
+ls -lhS dist/server/chunks/ | head -20
+
+# Check if a new import pulled in Shiki
+grep -r "from 'shiki'" dist/server/chunks/ | wc -l
+# If > 0: a component that imports shiki was SSR'd
+# Fix: make its page client:only="react" + prerender=true
+
+# Check if React crept back into worker via client:load
+grep -l "react-vendor" dist/server/chunks/
+# If multiple chunks: some page SSR-renders React via client:load
+# Fix: audit src/pages/*.astro for client:load on pure-shell pages
+```
+
+---
+
+## Rollback
+
+```bash
+# Workers — rollback to previous version
+bun wrangler rollback --name one-prod        # production
+bun wrangler rollback --name one-substrate   # dev
+
+# Legacy Pages fallback (still live at one-substrate.pages.dev for rollback window):
+bun wrangler pages deployment list --project-name=one-substrate
+bun wrangler pages deployments rollback --project-name=one-substrate
+
+# Revert a Worker via git
+cd api && git stash && bun wrangler deploy
+```
+
+---
+
+## Known-Flaky Test Allowlist
+
+Located in `scripts/deploy.ts`:
+
+```typescript
+const KNOWN_FLAKY = [
+  'Act 15: Speed Benchmarks',  // hardware-dependent
+  'STAN distribution',          // stochastic
+  'explorer mode',              // stochastic
+]
+```
+
+These failures don't block deploy. Real failures (type errors, broken logic)
+always block. Use `--strict` to require full green.
+
+---
+
+## First-Time Setup
+
+Only needed once — see `docs/deploy.md` for full walkthrough:
+
+```bash
+# Create CF resources
+bun wrangler d1 create one
+bun wrangler kv namespace create KV
+# → Paste IDs into wrangler.toml + sync/wrangler.toml
+
+# Run D1 migration
+bun wrangler d1 execute one --remote --file=migrations/0001_init.sql
+
+# Gateway secrets (TypeDB credentials)
+cd api
+printf 'admin' | bun wrangler secret put TYPEDB_USERNAME
+printf 'YOUR-PASSWORD' | bun wrangler secret put TYPEDB_PASSWORD
+cd ..
+
+# First deploy — Worker auto-provisions on first `wrangler deploy`
+bun run deploy
+```
+
+---
+
+## Logs
+
+- `.deploy.log` — all deployment output, each worker appends here
+- `.deploy-build.log` — W0 baseline diagnostics (biome + tsc + vitest separate)
+
+Live logs:
+
+```bash
+bun wrangler tail --name one-prod            # Astro Worker (production)
+bun wrangler tail --name one-substrate       # Astro Worker (dev)
+cd api && bun wrangler tail && cd ..     # Gateway
+bun wrangler deployments list --name one-prod | head -10
+```
+
+---
+
+## Gotchas
+
+- TypeDB Cloud port is **1729** (not 80 or 443)
+- TypeDB HTTP API prefix is `/v1/` (signin, query, databases)
+- Always `CLOUDFLARE_GLOBAL_API_KEY` — scoped tokens lack permissions for workers + custom domains
+- `import.meta.env` is build-time — `PUBLIC_GATEWAY_URL` is baked into the worker bundle at build. Missing → `/api/health` returns `units: 0`
+- Custom domains: `[[routes]]` double bracket, no wildcards, add `workers_dev = true`
+- Worker upload limit: **3 MiB gzipped** on free tier (10 MiB on paid). Wrangler reports `gzip:` — only that number counts. Follow the 5 Bundle Size Rules above
+- **D1 schema-drift fails at runtime, not compile-time.** Migrations that DROP+CREATE a table (e.g. `0059_domains.sql` renamed `slug`→`gid`, `verified`→`verified_at`) silently break any code that queries the old columns — typecheck passes, deploy succeeds, the route 500s in production. After any DROP+CREATE migration, grep the codebase for the old column names and fix call sites BEFORE deploying
+- **Error responses get the same `cache-control` as success responses.** Astro's Layout sets `public, max-age=300, s-maxage=86400, stale-while-revalidate=604800` on every render including 5xx pages. A bad deploy will be cached at the CF edge for 24h. When diagnosing, always bust the cache: `curl "https://host/path?_t=$(date +%s)"`. Consider a middleware rule that strips `cache-control` on `>= 500` status
+
+---
+
+*Deploy is the closed loop. W0 baseline in, health check out. If health fails, mark() is blocked. Determinism: every step reports numbers, every number gets marked.*