Merge pull request 'deployment-patch' (#4) from deployment-patch into main

Reviewed-on: https://git.deltaisland.io/dirtydishes/islandflow/pulls/4

.beads/issues.jsonl

@@ -1,3 +1,4 @@
+{"_type":"issue","id":"islandflow-jor","title":"Support Forgejo pull request status in desktop git panel","description":"The desktop app currently reports pull request status unavailable when a repository only has a Forgejo remote. Add native Forgejo/Gitea-style remote detection and pull request status lookup so Forgejo-only repositories can show PR state in the Codex app git panel.","status":"closed","priority":1,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-19T20:55:15Z","created_by":"dirtydishes","updated_at":"2026-05-19T20:59:46Z","started_at":"2026-05-19T20:55:25Z","closed_at":"2026-05-19T20:59:46Z","close_reason":"Patched the installed Codex desktop app bundle with a Forgejo PR status fallback and documented the local change.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-g3a","title":"Reconcile PR merge conflicts","description":"Resolve the current pull request conflicts for the nextjs-upgrade branch, validate the result, document the turn, and push the reconciled branch.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-19T18:44:51Z","created_by":"dirtydishes","updated_at":"2026-05-19T18:47:35Z","started_at":"2026-05-19T18:44:56Z","closed_at":"2026-05-19T18:47:35Z","close_reason":"Merged forgejo/main into nextjs-upgrade, resolved README and Beads conflicts, updated JetStream retention tests, validated deploy help, Docker workspace sync, API/bus tests, and web build, and added turn documentation.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-jbi","title":"Hydrate alert evidence details from ClickHouse","description":"Alert detail drawers need to fetch persisted alert context from ClickHouse by trace id, including linked flow packets, option prints, preserved execution context, and explicit missing refs for UI diagnostics.","status":"closed","priority":1,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-17T14:55:43Z","created_by":"dirtydishes","updated_at":"2026-05-17T15:01:58Z","started_at":"2026-05-17T14:55:53Z","closed_at":"2026-05-17T15:01:58Z","close_reason":"Implemented ClickHouse-backed alert context hydration across storage, API, terminal drawer, tests, and turn documentation.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-8kj","title":"Configure persistent beads Dolt remote on deltaisland server","description":"Install the beads and Dolt CLIs on the server, configure a persistent Dolt sync remote backed by the server-hosted Forgejo repository, verify refs/dolt/data publication, and document Nginx Proxy Manager / firewall considerations.","status":"closed","priority":1,"issue_type":"task","assignee":"delta","created_at":"2026-05-17T10:31:31Z","created_by":"delta","updated_at":"2026-05-17T10:37:47Z","started_at":"2026-05-17T10:32:16Z","closed_at":"2026-05-17T10:37:47Z","close_reason":"Installed bd and dolt on the server, configured the Forgejo-backed Dolt remote, published refs/dolt/data, and documented the setup.","dependency_count":0,"dependent_count":0,"comment_count":0}
@@ -14,6 +15,11 @@
 {"_type":"issue","id":"islandflow-ayo","title":"Drop stale backlog events from live fanout","description":"Follow-up to live freshness rollout: /ws/live was still fanning out stale backlog events for freshness-gated channels, which kept tape panes in Live feed behind despite active synthetic ingest. Gate fanout and cache ingest by freshness for options/nbbo/equities/flow.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:26:39Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:26:44Z","started_at":"2026-04-28T21:26:44Z","closed_at":"2026-04-28T21:26:44Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-0v6","title":"Fix tape freshness, NBBO coverage, pause controls, and filter popup","description":"Implement the tape fixes requested for synthetic options notional sizing, strict live freshness, live-mode pause/resume behavior, stronger NBBO snapshot coverage, and moving flow filters behind a popup. Includes server-side live cache changes, web terminal state/UI changes, and tests for synthetic pricing, live snapshot freshness/NBBO retention, and live pause/filter interactions.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:02:52Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:13:38Z","started_at":"2026-04-28T21:02:57Z","closed_at":"2026-04-28T21:13:38Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-e4r","title":"Implement smart-money flow filtering and synthetic firehose modes","description":"Implement the approved multi-surface plan for named synthetic market profiles, options raw-vs-signal filtering, live/API filter contracts, Tape page client-side flow filters, firehose-readiness improvements, tests, and README updates.","status":"closed","priority":1,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T20:10:49Z","created_by":"dirtydishes","updated_at":"2026-04-28T20:29:29Z","started_at":"2026-04-28T20:10:53Z","closed_at":"2026-04-28T20:29:29Z","close_reason":"Implemented synthetic market profiles, options signal-path filtering, signal-aware API/replay contracts, Tape page filters, tests, and README updates. Follow-up tracked in islandflow-biq.","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"islandflow-fmg","title":"Fix native deploy SSH path and verification cwd assumptions","description":"Native deploys over SSH assumed bun was already on PATH and that remote verification would run from the repository root. On the live VPS, non-login SSH shells omitted /home/delta/.bun/bin and remote native verification could not find deployment/native/check-native-infra.sh because it ran from the home directory. Update the deploy helper to prepend /Users/kell/.bun/bin when present and cd into the repo before native verification checks run.","status":"closed","priority":2,"issue_type":"bug","owner":"dishes@dpdrm.com","created_at":"2026-05-19T23:38:32Z","created_by":"dirtydishes","updated_at":"2026-05-19T23:40:33Z","closed_at":"2026-05-19T23:40:33Z","close_reason":"Updated native SSH deploy flow to prepend Bun's home install path when present and run native verification from the repo root before health scripts.","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"islandflow-wf5","title":"Harden native options provider configuration after synthetic recovery","description":"Native production recovery restored OPTIONS_INGEST_ADAPTER=synthetic because the current Alpaca setup fails authentication and crash-loops ingest-options. Follow up by deciding whether production options should remain synthetic or move to a supported live provider auth path, then add a deploy-time smoke test or config validation that catches provider auth failures before native cutover.","status":"open","priority":2,"issue_type":"task","owner":"dishes@dpdrm.com","created_at":"2026-05-19T23:27:51Z","created_by":"dirtydishes","updated_at":"2026-05-19T23:27:51Z","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"islandflow-m83","title":"Restore options ingestion and print generation on native deployment","description":"After moving the production/VPS deployment from Docker-managed services to the native runtime, the options feed appears behind and fresh option prints are not reaching the UI. Investigate the native deployment path on the server, identify the ingestion or compute breakage, apply the required code and/or host configuration changes, validate that fresh option prints resume, and document any follow-up operational work.","status":"closed","priority":2,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-19T23:20:01Z","created_by":"dirtydishes","updated_at":"2026-05-19T23:27:52Z","started_at":"2026-05-19T23:20:10Z","closed_at":"2026-05-19T23:27:52Z","close_reason":"Restored native options ingest by switching the VPS back to the last known-good synthetic adapter, verified fresh option prints and compute output, and documented the native env precedence gotcha.","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"islandflow-o1v","title":"Add SCM provider layer with Forgejo detection","description":"Implement provider-aware source-control detection and mirror-aware guardrails for repo automation so Forgejo remotes are treated as authoritative when present.","status":"closed","priority":2,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-19T23:04:33Z","created_by":"dirtydishes","updated_at":"2026-05-19T23:06:55Z","started_at":"2026-05-19T23:04:35Z","closed_at":"2026-05-19T23:06:55Z","close_reason":"created by mistake during interrupted turn; no implementation was started","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"islandflow-tqk","title":"publish docs/ to github pages with navigable index","description":"Set up docs deployment so repository docs are published to dirtydishes.github.io/islandflow/docs with a nicer, browsable experience than a raw file listing.","status":"closed","priority":2,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-19T18:56:02Z","created_by":"dirtydishes","updated_at":"2026-05-19T18:59:55Z","started_at":"2026-05-19T18:56:04Z","closed_at":"2026-05-19T18:59:55Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-lm6","title":"Clarify repo turn documentation scope","description":"Update AGENTS.md so repository turn documentation clearly uses repo-local docs/turns and impeccable styling, without inheriting global non-repo computer-task styling.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-19T12:05:07Z","created_by":"dirtydishes","updated_at":"2026-05-19T12:06:12Z","started_at":"2026-05-19T12:05:14Z","closed_at":"2026-05-19T12:06:12Z","close_reason":"Verified AGENTS.md now scopes repo turn docs to docs/turns and makes impeccable the styling authority; added turn documentation.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-6iq","title":"Update README for current project state","description":"Resolve README merge conflicts and document the current project state, including the smart money classification taxonomy, Next.js update, and deployment workflow changes.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-19T11:37:24Z","created_by":"dirtydishes","updated_at":"2026-05-19T11:40:01Z","started_at":"2026-05-19T11:37:31Z","closed_at":"2026-05-19T11:40:01Z","close_reason":"README conflict resolved and current project state documented, including smart-money taxonomy, Next.js update, and deployment workflow.","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-lib","title":"Upgrade apps/web to Next.js 16.2.6","description":"Upgrade the web app dependency stack to Next.js 16.2.6 with React 19, refresh Bun and mirrored Docker workspace lockfiles, keep runtime behavior unchanged, fix any focused web test fallout, validate the web build and targeted route tests, and document the completed work.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-19T11:04:51Z","created_by":"dirtydishes","updated_at":"2026-05-19T11:31:23Z","started_at":"2026-05-19T11:04:57Z","closed_at":"2026-05-19T11:31:23Z","close_reason":"Upgraded apps/web to Next.js 16.2.6 with React 19, refreshed Bun lockfiles including the Docker workspace mirror, fixed the React 19 nullable ref type issue, and validated the web build, focused tests, Docker workspace sync, and route smoke checks.","dependency_count":0,"dependent_count":0,"comment_count":0}
@@ -53,6 +59,7 @@
 {"_type":"issue","id":"islandflow-zs0","title":"Migrate terminal UI to smart-money profiles","description":"Migrate apps/web terminal rendering to consume SmartMoneyEvent directly: primary profile, probability ladder, reason codes, and suppression/abstention state, while preserving legacy alert/classifier displays during the bridge.","status":"closed","priority":2,"issue_type":"task","owner":"dishes@dpdrm.com","created_at":"2026-05-04T21:35:23Z","created_by":"dirtydishes","updated_at":"2026-05-05T05:39:58Z","closed_at":"2026-05-05T05:39:58Z","close_reason":"Completed terminal smart-money profile migration","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-igk","title":"Add plan mode","description":"Implement a user-facing plan mode in the application so users can switch into planning before taking action. Scope to be clarified from existing app patterns.","status":"closed","priority":2,"issue_type":"feature","owner":"dishes@dpdrm.com","created_at":"2026-05-04T04:22:37Z","created_by":"dirtydishes","updated_at":"2026-05-04T04:26:18Z","started_at":"2026-05-04T04:22:40Z","closed_at":"2026-05-04T04:26:18Z","close_reason":"Implemented as a global pi extension toggled with Shift+P","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-biq","title":"Finish raw live options delivery and filter/backpressure observability","description":"The smart-money signal path and Tape filters are in place, but the next firehose pass should finish server-side selective raw live delivery for options subscriptions and add explicit filtered-out/backpressure observability for API/web counters. This was discovered while landing islandflow-e4r.\n","status":"in_progress","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T20:28:58Z","created_by":"dirtydishes","updated_at":"2026-04-29T03:54:12Z","started_at":"2026-04-29T03:54:12Z","dependencies":[{"issue_id":"islandflow-biq","depends_on_id":"islandflow-e4r","type":"discovered-from","created_at":"2026-04-28T16:28:58Z","created_by":"auto-import","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"islandflow-0ty","title":"Recreate May 18 standup summary after merge","description":"Regenerate docs/daily-git/2026-05-19-standup-summary-2026-05-18.html using merged history so it reflects all commits in the May 18 window, including native deployment and merge commits.","status":"closed","priority":3,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-19T18:53:48Z","created_by":"dirtydishes","updated_at":"2026-05-19T18:55:33Z","started_at":"2026-05-19T18:53:52Z","closed_at":"2026-05-19T18:55:33Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-2df","title":"Publish 2026-05-18 git standup summary","description":"Why: the daily automation needs a grounded standup summary for May 18, 2026. What: review commits from 2026-05-18, create a scannable HTML summary in docs/daily-git, and capture only commit/file-backed statements.","status":"closed","priority":3,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-19T18:41:07Z","created_by":"dirtydishes","updated_at":"2026-05-19T18:42:42Z","started_at":"2026-05-19T18:41:10Z","closed_at":"2026-05-19T18:42:42Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-x70","title":"Create 2026-05-17 git standup summary","description":"Why this issue exists and what needs to be done:\\n- Produce the daily automation summary for 2026-05-17 git activity.\\n- Ground statements in commits, PRs, and touched files only.\\n- Create a user-readable HTML document in docs/general and update automation memory.\\n- Complete the Beads sync and git push workflow after documenting the run.","status":"closed","priority":3,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-18T13:01:43Z","created_by":"dirtydishes","updated_at":"2026-05-18T13:05:37Z","started_at":"2026-05-18T13:01:53Z","closed_at":"2026-05-18T13:05:37Z","close_reason":"Closed","dependency_count":0,"dependent_count":0,"comment_count":0}
 {"_type":"issue","id":"islandflow-zsy","title":"Expose Forgejo SSH on a direct DNS hostname","description":"git.deltaisland.io currently resolves through Cloudflare's proxy, so SSH on port 2222 does not complete even though the Forgejo container is listening on the host. If SSH-based git/beads workflows are desired, add a DNS-only hostname (or adjust the existing record) that points directly at the server for Forgejo SSH.","status":"open","priority":3,"issue_type":"task","created_at":"2026-05-17T10:34:06Z","created_by":"delta","updated_at":"2026-05-17T10:34:06Z","dependency_count":0,"dependent_count":0,"comment_count":0}

.github/workflows/docs-pages.yml

@@ -0,0 +1,56 @@
+name: Publish Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "scripts/generate-docs-index.mjs"
+      - ".github/workflows/docs-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build docs index
+        run: node scripts/generate-docs-index.mjs
+
+      - name: Prepare static site payload
+        run: |
+          mkdir -p site/docs
+          cp -R docs/. site/docs/
+          printf '%s\n' '<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=./docs/"><title>Islandflow Docs</title><a href="./docs/">Continue to docs</a>' > site/index.html
+          touch site/.nojekyll
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

deployment/native/README.md

@@ -98,6 +98,8 @@ These are written for the current VPS layout:
 - Bun binary: `/home/delta/.bun/bin/bun`
 - env file: `/home/delta/islandflow/.env`
 
+Important: treat `/home/delta/islandflow/.env` as the effective source of truth for adapter selection. The Bun-launched services read that file directly at runtime, so a conflicting `OPTIONS_INGEST_ADAPTER` value in `.env` can still win over a systemd-only override and push `ingest-options` onto the wrong provider path.
+
 ### Install the units
 
 ```bash

deployment/native/systemd/user/islandflow-ingest-options.service

@@ -7,7 +7,6 @@ Wants=network-online.target
 Type=simple
 WorkingDirectory=/home/delta/islandflow
 EnvironmentFile=/home/delta/islandflow/.env
-Environment=OPTIONS_INGEST_ADAPTER=synthetic
 ExecStart=/home/delta/.bun/bin/bun services/ingest-options/src/index.ts
 Restart=always
 RestartSec=2

docs/daily-git/2026-05-19-standup-summary-2026-05-18.html

@@ -3,27 +3,23 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Daily Git Summary for 2026-05-18</title>
+    <title>Daily Git Summary for 2026-05-18 (Merged View)</title>
     <style>
       :root {
         color-scheme: dark;
         --bg: #06080b;
-        --bg-top: #091018;
+        --panel: #111820;
-        --panel: rgba(17, 24, 32, 0.94);
+        --panel-2: #0d141b;
-        --panel-strong: rgba(13, 20, 27, 0.98);
+        --border: rgba(255, 255, 255, 0.09);
-        --border: rgba(255, 255, 255, 0.08);
-        --border-strong: rgba(245, 166, 35, 0.28);
         --text: #e6edf4;
         --muted: #90a0b2;
         --faint: #6e7b8c;
         --accent: #f5a623;
-        --accent-soft: rgba(245, 166, 35, 0.12);
+        --accent-soft: rgba(245, 166, 35, 0.14);
         --blue: #4da3ff;
-        --blue-soft: rgba(77, 163, 255, 0.12);
+        --blue-soft: rgba(77, 163, 255, 0.14);
         --green: #25c17a;
-        --green-soft: rgba(37, 193, 122, 0.12);
+        --green-soft: rgba(37, 193, 122, 0.14);
-        --red: #ff6b5f;
-        --red-soft: rgba(255, 107, 95, 0.12);
       }
 
       * {
@@ -34,58 +30,27 @@
         margin: 0;
         background:
           radial-gradient(circle at top right, rgba(245, 166, 35, 0.1), transparent 24%),
-          linear-gradient(180deg, var(--bg-top) 0%, var(--bg) 28%, #05070a 100%);
+          linear-gradient(180deg, #091018 0%, var(--bg) 30%, #05070a 100%);
         color: var(--text);
         font-family: "IBM Plex Sans", "Segoe UI", sans-serif;
-        line-height: 1.6;
+        line-height: 1.58;
       }
 
       main {
-        width: min(1120px, calc(100% - 40px));
+        width: min(1120px, calc(100% - 36px));
-        margin: 32px auto 56px;
+        margin: 28px auto 48px;
       }
 
       .hero,
       section {
-        background: linear-gradient(180deg, var(--panel), var(--panel-strong));
         border: 1px solid var(--border);
-        border-radius: 18px;
+        border-radius: 16px;
+        background: linear-gradient(180deg, rgba(17, 24, 32, 0.95), rgba(13, 20, 27, 0.98));
       }
 
       .hero {
-        padding: 32px;
+        padding: 28px;
-        box-shadow: 0 24px 60px rgba(0, 0, 0, 0.32);
+        box-shadow: 0 22px 56px rgba(0, 0, 0, 0.34);
-      }
-
-      .eyebrow,
-      .pill,
-      .file-pill,
-      .commit-id,
-      .timestamp {
-        font-family: "IBM Plex Mono", monospace;
-      }
-
-      .eyebrow,
-      .pill {
-        display: inline-flex;
-        align-items: center;
-        gap: 8px;
-        padding: 6px 10px;
-        border-radius: 999px;
-        font-size: 12px;
-        letter-spacing: 0.12em;
-        text-transform: uppercase;
-      }
-
-      .eyebrow {
-        background: var(--accent-soft);
-        color: var(--accent);
-      }
-
-      .pill {
-        border: 1px solid var(--border);
-        background: rgba(255, 255, 255, 0.04);
-        color: var(--text);
       }
 
       h1,
@@ -97,14 +62,13 @@
       }
 
       h1 {
-        margin-top: 18px;
+        margin-top: 14px;
-        font-size: clamp(2rem, 3.5vw, 2.9rem);
+        font-size: clamp(1.9rem, 3.3vw, 2.7rem);
-        line-height: 1.05;
       }
 
       h2 {
-        font-size: 1.22rem;
+        font-size: 1.2rem;
-        margin-bottom: 16px;
+        margin-bottom: 14px;
       }
 
       h3 {
@@ -113,168 +77,159 @@
 
       p {
         margin: 0;
-        max-width: 82ch;
         color: var(--muted);
+        max-width: 86ch;
       }
 
-      .hero p {
+      section {
         margin-top: 14px;
-        font-size: 1rem;
+        padding: 22px;
       }
 
-      .meta-grid,
+      .eyebrow,
-      .summary-grid,
+      .pill,
-      .impact-grid {
+      .commit,
+      .time,
+      .label {
+        font-family: "IBM Plex Mono", monospace;
+      }
+
+      .eyebrow {
+        display: inline-block;
+        padding: 6px 10px;
+        border-radius: 999px;
+        text-transform: uppercase;
+        letter-spacing: 0.12em;
+        font-size: 12px;
+        background: var(--accent-soft);
+        color: var(--accent);
+      }
+
+      .meta {
+        margin-top: 20px;
         display: grid;
-        gap: 12px;
-      }
-
-      .meta-grid {
         grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
-        margin-top: 24px;
+        gap: 10px;
       }
 
-      .summary-grid,
+      .meta-card {
-      .impact-grid {
-        grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
-      }
-
-      .meta-card,
-      .summary-card,
-      .impact-card,
-      .commit-card,
-      .snippet-card,
-      .callout {
-        padding: 16px 18px;
         border: 1px solid var(--border);
-        border-radius: 14px;
+        border-radius: 12px;
-        background: rgba(255, 255, 255, 0.025);
+        background: rgba(255, 255, 255, 0.03);
+        padding: 12px 14px;
       }
 
       .label {
         display: block;
         margin-bottom: 6px;
         color: var(--text);
-        font-family: "IBM Plex Mono", monospace;
-        font-size: 0.76rem;
-        letter-spacing: 0.12em;
         text-transform: uppercase;
+        letter-spacing: 0.12em;
+        font-size: 0.74rem;
       }
 
       .metric {
-        font-size: 1.6rem;
         color: var(--text);
         font-weight: 700;
+        font-size: 1.45rem;
       }
 
-      section {
+      .cards,
-        padding: 24px;
+      .impact-cards {
-        margin-top: 16px;
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+        gap: 10px;
+      }
+
+      .card {
+        border: 1px solid var(--border);
+        border-radius: 12px;
+        background: rgba(255, 255, 255, 0.025);
+        padding: 14px;
+      }
+
+      .card.feature {
+        border-color: rgba(37, 193, 122, 0.28);
+        background: linear-gradient(180deg, rgba(37, 193, 122, 0.1), rgba(255, 255, 255, 0.02));
+      }
+
+      .card.ops {
+        border-color: rgba(77, 163, 255, 0.28);
+        background: linear-gradient(180deg, rgba(77, 163, 255, 0.1), rgba(255, 255, 255, 0.02));
       }
 
       .timeline {
         display: grid;
-        gap: 14px;
+        gap: 11px;
       }
 
-      .timeline-meta {
+      .entry {
+        border: 1px solid var(--border);
+        border-radius: 12px;
+        background: rgba(255, 255, 255, 0.022);
+        padding: 14px;
+      }
+
+      .entry-head {
         display: flex;
         flex-wrap: wrap;
-        gap: 10px 14px;
+        gap: 8px 12px;
         align-items: baseline;
-        margin-bottom: 8px;
+        margin-bottom: 7px;
       }
 
-      .commit-id,
+      .commit {
-      .timestamp {
-        font-size: 0.76rem;
-        letter-spacing: 0.08em;
-        text-transform: uppercase;
-      }
-
-      .commit-id {
         color: var(--blue);
+        text-transform: uppercase;
+        font-size: 0.75rem;
+        letter-spacing: 0.08em;
       }
 
-      .timestamp {
+      .time {
         color: var(--faint);
+        text-transform: uppercase;
+        font-size: 0.74rem;
+        letter-spacing: 0.08em;
+      }
+
+      .pill {
+        border: 1px solid var(--border);
+        border-radius: 999px;
+        padding: 5px 8px;
+        background: rgba(255, 255, 255, 0.04);
+        font-size: 0.72rem;
       }
 
       ul {
         margin: 0;
-        padding-left: 20px;
+        padding-left: 19px;
         color: var(--muted);
       }
 
       li + li {
-        margin-top: 10px;
+        margin-top: 8px;
-      }
-
-      .file-list {
-        display: flex;
-        flex-wrap: wrap;
-        gap: 8px;
-        margin-top: 12px;
-      }
-
-      .file-pill {
-        padding: 5px 8px;
-        border-radius: 999px;
-        border: 1px solid var(--border);
-        background: rgba(255, 255, 255, 0.045);
-        color: var(--text);
-        font-size: 0.73rem;
-      }
-
-      .snippets {
-        display: grid;
-        gap: 14px;
       }
 
       pre {
-        margin: 12px 0 0;
+        margin: 10px 0 0;
-        padding: 14px;
+        padding: 12px;
         overflow-x: auto;
-        border-radius: 12px;
+        border: 1px solid rgba(255, 255, 255, 0.08);
-        border: 1px solid rgba(255, 255, 255, 0.06);
+        border-radius: 10px;
         background: rgba(6, 8, 11, 0.9);
-        color: #d8e4ef;
+        color: #d7e2ec;
         font-family: "IBM Plex Mono", monospace;
-        font-size: 0.8rem;
+        font-size: 0.79rem;
-        line-height: 1.55;
       }
 
       code {
         font-family: "IBM Plex Mono", monospace;
       }
 
-      .tone-feature {
-        border-color: rgba(37, 193, 122, 0.24);
-        background: linear-gradient(180deg, rgba(37, 193, 122, 0.09), rgba(255, 255, 255, 0.02));
-      }
-
-      .tone-docs {
-        border-color: rgba(77, 163, 255, 0.22);
-      }
-
-      .tone-risk {
-        border-color: rgba(255, 107, 95, 0.24);
-        background: linear-gradient(180deg, rgba(255, 107, 95, 0.08), rgba(255, 255, 255, 0.02));
-      }
-
-      a {
-        color: #8bc0ff;
-      }
-
       @media (max-width: 720px) {
         main {
-          width: min(100%, calc(100% - 24px));
+          width: min(100%, calc(100% - 20px));
-          margin: 20px auto 32px;
+          margin: 18px auto 30px;
-        }
-
-        .hero,
-        section {
-          padding: 20px;
         }
       }
     </style>
@@ -283,56 +238,54 @@
     <main>
       <section class="hero">
         <span class="eyebrow">Daily Git Summary</span>
-        <h1>Standup summary for Monday, May 18, 2026</h1>
+        <h1>Standup summary for Monday, May 18, 2026 (after merge)</h1>
         <p>
-          Git history for May 18 shows four commits. One feature commit introduced an Alpaca-backed news wire across ingest,
+          This regenerated report uses merged history for the full May 18 local-day window
-          storage, API, and web surfaces; the other three commits updated workflow docs, beads state, and the previous
+          (<code>2026-05-18 00:00 -0400</code> through <code>2026-05-19 00:00 -0400</code>). It now includes eight commits,
-          standup summary.
+          including native deployment work and the merge commit that landed that line of work on <code>main</code>.
         </p>
-        <div class="meta-grid">
+        <div class="meta">
           <div class="meta-card">
             <span class="label">Commits</span>
-            <div class="metric">4</div>
+            <div class="metric">8</div>
           </div>
           <div class="meta-card">
-            <span class="label">Files Touched</span>
+            <span class="label">Unique Files</span>
-            <div class="metric">35</div>
+            <div class="metric">68</div>
           </div>
           <div class="meta-card">
             <span class="label">Insertions</span>
-            <div class="metric">1963</div>
+            <div class="metric">4244</div>
           </div>
           <div class="meta-card">
             <span class="label">Deletions</span>
-            <div class="metric">52</div>
+            <div class="metric">194</div>
           </div>
         </div>
       </section>
 
       <section>
         <h2>Summary</h2>
-        <div class="summary-grid">
+        <div class="cards">
-          <div class="summary-card tone-feature">
+          <div class="card feature">
-            <span class="label">Primary Delivery</span>
+            <span class="label">User-facing delivery</span>
             <p>
-              Commit <code>906fe411</code> added a new <code>services/ingest-news</code> service, news persistence in
+              Commit <code>906fe411</code> added Alpaca news wire support across ingest, storage, API, and web terminal/news
-              <code>packages/storage</code>, API endpoints in <code>services/api</code>, and a live news view in
+              route surfaces.
-              <code>apps/web/app/terminal.tsx</code> plus <code>apps/web/app/news/page.tsx</code>.
             </p>
           </div>
-          <div class="summary-card tone-docs">
+          <div class="card ops">
-            <span class="label">Docs And Workflow</span>
+            <span class="label">Platform and deployment delivery</span>
             <p>
-              Commits <code>62aae708</code>, <code>687a2170</code>, and <code>04baeceb</code> updated the previous standup
+              Commits <code>d589858c</code> and <code>bdb9d9a9</code> added native deployment workflow, infra/user units,
-              report, beads state, <code>deployment/docker/workspace-root/package.json</code>, and the repo-level
+              cutover, rollback, and health-check scripts, then merged via <code>8f0794dd</code> (PR #2).
-              <code>AGENTS.md</code> instructions.
             </p>
           </div>
-          <div class="summary-card">
+          <div class="card">
-            <span class="label">Standup Framing</span>
+            <span class="label">Workflow and docs updates</span>
             <p>
-              Yesterday’s visible product work centered on making live Alpaca news available end to end. The remaining
+              Commits <code>687a2170</code>, <code>62aae708</code>, <code>48095fce</code>, and <code>04baeceb</code> updated
-              activity was project hygiene and documentation.
+              beads/docs instructions and added turn/standup documentation.
             </p>
           </div>
         </div>
@@ -341,94 +294,99 @@
       <section>
         <h2>Changes Made</h2>
         <div class="timeline">
-          <article class="commit-card tone-docs">
+          <article class="entry">
-            <div class="timeline-meta">
+            <div class="entry-head">
               <strong>update beads</strong>
-              <span class="commit-id">687a2170</span>
+              <span class="commit">687a2170</span>
-              <span class="timestamp">2026-05-18 03:15 -0400</span>
+              <span class="time">2026-05-18 03:15 -0400</span>
               <span class="pill">1 file</span>
             </div>
-            <p>
+            <p>Touched <code>deployment/docker/workspace-root/package.json</code> with one-line change.</p>
-              Added one line to <code>deployment/docker/workspace-root/package.json</code>. The local git history does not
-              show more context beyond the file touch and commit subject.
-            </p>
           </article>
 
-          <article class="commit-card tone-docs">
+          <article class="entry">
-            <div class="timeline-meta">
+            <div class="entry-head">
-              <strong>docs(general): add 2026-05-17 standup summary</strong>
+              <strong>Implement native fast iterative deploy workflow</strong>
-              <span class="commit-id">62aae708</span>
+              <span class="commit">d589858c</span>
-              <span class="timestamp">2026-05-18 09:05 -0400</span>
+              <span class="time">2026-05-18 03:34 -0400</span>
+              <span class="pill">17 files</span>
+              <span class="pill">+873 / -110</span>
+            </div>
+            <ul>
+              <li>Expanded <code>scripts/deploy.ts</code> for native deploy runtime behavior.</li>
+              <li>Added native user-unit templates and rollback/health tooling in <code>deployment/native/</code>.</li>
+              <li>Added associated plan and turn documents in <code>docs/plans</code> and <code>docs/turns</code>.</li>
+            </ul>
+          </article>
+
+          <article class="entry">
+            <div class="entry-head">
+              <strong>fix(api): remove duplicate alert context import</strong>
+              <span class="commit">48095fce</span>
+              <span class="time">2026-05-18 09:04 -0400</span>
               <span class="pill">2 files</span>
             </div>
-            <p>
+            <p>Removed duplicate import in <code>services/api/src/index.ts</code> and added a turn doc.</p>
-              Added the prior day’s report at <code>docs/general/2026-05-18-standup-summary-2026-05-17.html</code> and
-              updated <code>.beads/issues.jsonl</code>.
-            </p>
-            <div class="file-list">
-              <span class="file-pill">docs/general/2026-05-18-standup-summary-2026-05-17.html</span>
-              <span class="file-pill">.beads/issues.jsonl</span>
-            </div>
           </article>
 
-          <article class="commit-card tone-feature">
+          <article class="entry">
-            <div class="timeline-meta">
+            <div class="entry-head">
+              <strong>docs(general): add 2026-05-17 standup summary</strong>
+              <span class="commit">62aae708</span>
+              <span class="time">2026-05-18 09:05 -0400</span>
+              <span class="pill">2 files</span>
+            </div>
+            <p>Added <code>docs/general/2026-05-18-standup-summary-2026-05-17.html</code> and updated beads state.</p>
+          </article>
+
+          <article class="entry">
+            <div class="entry-head">
               <strong>add alpaca news wire across ingest api and web</strong>
-              <span class="commit-id">906fe411</span>
+              <span class="commit">906fe411</span>
-              <span class="timestamp">2026-05-18 16:55 -0400</span>
+              <span class="time">2026-05-18 16:55 -0400</span>
               <span class="pill">31 files</span>
               <span class="pill">+1407 / -50</span>
             </div>
             <ul>
-              <li>
+              <li>Created <code>services/ingest-news</code> and wired Alpaca backfill/websocket ingestion.</li>
-                Added a new ingest service in <code>services/ingest-news/src/index.ts</code> that backfills Alpaca news,
+              <li>Added news types/storage contracts in <code>packages/types</code> and <code>packages/storage</code>.</li>
-                subscribes to the Alpaca news websocket, resolves symbols, and publishes <code>NewsStory</code> payloads to
+              <li>Extended API live/history endpoints and web terminal/news route rendering.</li>
-                NATS.
-              </li>
-              <li>
-                Extended shared contracts in <code>packages/types/src/events.ts</code> and
-                <code>packages/types/src/live.ts</code>, plus new storage support in
-                <code>packages/storage/src/news.ts</code> and <code>packages/storage/src/clickhouse.ts</code>.
-              </li>
-              <li>
-                Wired the API to store, fan out, and expose news via <code>/news</code> and <code>/history/news</code> in
-                <code>services/api/src/index.ts</code> and live-session updates in <code>services/api/src/live.ts</code>.
-              </li>
-              <li>
-                Added a web route in <code>apps/web/app/news/page.tsx</code>, a news pane and drawer in
-                <code>apps/web/app/terminal.tsx</code>, and related styling in <code>apps/web/app/globals.css</code>.
-              </li>
-              <li>
-                Updated runtime packaging and local/dev deployment surfaces, including
-                <code>deployment/docker/docker-compose.yml</code>, Dockerfiles, <code>scripts/dev.ts</code>, and
-                <code>scripts/deploy.ts</code>.
-              </li>
-              <li>
-                Added tests in <code>packages/storage/tests/news.test.ts</code>,
-                <code>services/ingest-news/tests/symbols.test.ts</code>, and adjusted
-                <code>apps/web/app/terminal.test.ts</code> plus <code>packages/types/tests/live.test.ts</code>.
-              </li>
             </ul>
-            <div class="file-list">
-              <span class="file-pill">services/ingest-news/src/index.ts</span>
-              <span class="file-pill">packages/storage/src/news.ts</span>
-              <span class="file-pill">services/api/src/index.ts</span>
-              <span class="file-pill">apps/web/app/terminal.tsx</span>
-              <span class="file-pill">apps/web/app/news/page.tsx</span>
-              <span class="file-pill">apps/web/app/globals.css</span>
-            </div>
           </article>
 
-          <article class="commit-card tone-docs">
+          <article class="entry">
-            <div class="timeline-meta">
+            <div class="entry-head">
+              <strong>Implement native public edge cutover</strong>
+              <span class="commit">bdb9d9a9</span>
+              <span class="time">2026-05-18 19:55 -0400</span>
+              <span class="pill">29 files</span>
+              <span class="pill">+1215 / -31</span>
+            </div>
+            <ul>
+              <li>Added native infra system units and scripts for bootstrap/start/stop/cutover/full rollback.</li>
+              <li>Updated deploy docs and runtime config files under <code>deployment/native/config</code>.</li>
+              <li>Added turn doc <code>docs/turns/2026-05-18-native-public-edge-cutover.html</code>.</li>
+            </ul>
+          </article>
+
+          <article class="entry">
+            <div class="entry-head">
+              <strong>Merge pull request 'Native public edge cutover with Docker rollback path' (#2)</strong>
+              <span class="commit">8f0794dd</span>
+              <span class="time">2026-05-19 00:09 +0000</span>
+              <span class="pill">merge commit</span>
+            </div>
+            <p>Merged <code>native-deploy</code> into <code>main</code> within the May 18 US/Eastern day window.</p>
+          </article>
+
+          <article class="entry">
+            <div class="entry-head">
               <strong>update turn docs and beads workflow</strong>
-              <span class="commit-id">04baeceb</span>
+              <span class="commit">04baeceb</span>
-              <span class="timestamp">2026-05-18 21:32 -0400</span>
+              <span class="time">2026-05-18 21:32 -0400</span>
               <span class="pill">1 file</span>
             </div>
-            <p>
+            <p>Updated repository-level instructions in <code>AGENTS.md</code>.</p>
-              Edited <code>AGENTS.md</code> to update turn-document and beads workflow guidance.
-            </p>
           </article>
         </div>
       </section>
@@ -436,92 +394,59 @@
       <section>
         <h2>Context</h2>
         <p>
-          This summary is based on local git history between <code>2026-05-18 00:00 -0400</code> and
+          The earlier report was generated before merged history included the native deployment branch on <code>main</code>.
-          <code>2026-05-19 00:00 -0400</code>. The repository uses Bun, TypeScript, NATS/JetStream, ClickHouse, and a Next.js
+          This recreation uses <code>git log --all</code> over the same date window, so it captures both feature work and
-          web app, so the main feature commit spans service ingestion, shared types, persistence, API delivery, and the UI.
+          merged operational/deployment work visible after PR merge.
         </p>
       </section>
 
       <section>
         <h2>Important Implementation Details</h2>
-        <div class="snippets">
+        <div class="cards">
-          <article class="snippet-card">
+          <div class="card">
-            <h3>News ingestion was introduced as a first-class service</h3>
+            <h3>News wire ingestion and delivery path</h3>
             <p>
-              <code>services/ingest-news/src/index.ts</code> authenticates against Alpaca, backfills recent news, subscribes
+              The news pipeline added a new ingest service and API fanout channel, then exposed UI surfaces in
-              to live updates, resolves symbols, validates payloads with <code>NewsStorySchema</code>, and publishes them onto
+              <code>/news</code> and terminal panes.
-              the repo’s bus layer.
-            </p>
-            <pre><code>const backfill = await fetchBackfill();
-for (const item of backfill.reverse()) {
-  await publishStory(item);
-}
-
-if (msg === "authenticated") {
-  ws.send(JSON.stringify({ action: "subscribe", news: ["*"] }));
-}</code></pre>
-          </article>
-
-          <article class="snippet-card">
-            <h3>API and live session support were expanded for news</h3>
-            <p>
-              <code>services/api/src/index.ts</code> now ensures the news table exists, subscribes to a news consumer, fans
-              out live updates, and exposes both recent and paginated history endpoints.
-            </p>
-            <pre><code>if (req.method === "GET" && url.pathname === "/news") {
-  const limit = parseLimit(url.searchParams.get("limit") ?? "100");
-  const data = await fetchRecentNews(clickhouse, limit);
-  return jsonResponse({ data });
-}</code></pre>
-          </article>
-
-          <article class="snippet-card">
-            <h3>The web terminal gained a dedicated news surface</h3>
-            <p>
-              <code>apps/web/app/terminal.tsx</code> added a live-only news pane, a per-story drawer, history loading, and a
-              new <code>/news</code> route entry point via <code>apps/web/app/news/page.tsx</code>.
             </p>
             <pre><code>if (features.news) {
   subscriptions.push({ channel: "news", snapshot_limit: LIVE_OPTIONS_HEAD_LIMIT });
-}
-
-export function NewsRoute() {
-  const state = useTerminal();
-  return (
-    &lt;PageFrame title="News"&gt;
-      &lt;div className="page-grid page-grid-news"&gt;
-        &lt;NewsPane state={state} className="news-pane-full" /&gt;
-      &lt;/div&gt;
-    &lt;/PageFrame&gt;
-  );
 }</code></pre>
-          </article>
+          </div>
+          <div class="card">
+            <h3>Native deployment hardening</h3>
+            <p>
+              Deployment scripts and unit templates now include direct scripts for cutover and rollback, with infra and
+              service checks under <code>deployment/native/</code>.
+            </p>
+            <pre><code>deployment/native/cutover.sh
+deployment/native/full-rollback.sh
+deployment/native/install-infra-units.sh</code></pre>
+          </div>
+          <div class="card">
+            <h3>Merged history effect on standup scope</h3>
+            <p>
+              The merged view increased the standup scope from 4 to 8 commits and from 35 to 68 unique files touched for the
+              same local-day window.
+            </p>
+          </div>
         </div>
       </section>
 
       <section>
         <h2>Expected Impact for End-Users</h2>
-        <div class="impact-grid">
+        <div class="impact-cards">
-          <div class="impact-card">
+          <div class="card">
-            <span class="label">Live Terminal</span>
+            <span class="label">Trading UI users</span>
-            <p>
+            <p>Live news wire data is now available in terminal surfaces alongside existing market/event feeds.</p>
-              Users now have a dedicated news wire surface in the web terminal, including summary rows, story details, and
-              a direct link to the source article.
-            </p>
           </div>
-          <div class="impact-card">
+          <div class="card">
-            <span class="label">Coverage</span>
+            <span class="label">Operators</span>
-            <p>
+            <p>Native deployment and rollback procedures now have first-class scripted and documented paths.</p>
-              News is now available alongside the repo’s existing live feeds, with shared symbol resolution and storage that
-              make the data retrievable through API history endpoints.
-            </p>
           </div>
-          <div class="impact-card tone-risk">
+          <div class="card">
-            <span class="label">Current Boundary</span>
+            <span class="label">Team reporting</span>
-            <p>
+            <p>This standup report now matches merged repository history instead of pre-merge branch-local history.</p>
-              The UI copy in the news pane explicitly marks news as live-only in v1, so replay users should not expect the
-              same behavior there yet.
-            </p>
           </div>
         </div>
       </section>
@@ -529,36 +454,27 @@ export function NewsRoute() {
       <section>
         <h2>Validation</h2>
         <ul>
-          <li>Reviewed local git history with <code>git log --since='2026-05-18 00:00' --until='2026-05-19 00:00'</code>.</li>
+          <li>Used <code>git fetch --all --prune</code> before recomputing history.</li>
-          <li>Used <code>git log --stat</code>, <code>git show</code>, and file-level history to anchor each summary item to specific commits and files.</li>
+          <li>Used <code>git log --all</code> over the May 18 ET window to include merged commits.</li>
-          <li>No builds or tests were run for this reporting task because the work product is a git summary document, not a behavior change.</li>
+          <li>Used <code>git log --stat --summary</code> and <code>--numstat</code> to ground file and line-count statements.</li>
+          <li>No build/test commands were run because this task only regenerates reporting documentation.</li>
         </ul>
       </section>
 
       <section>
         <h2>Issues, Limitations, and Mitigations</h2>
         <ul>
-          <li>
+          <li>This report describes commit history only and does not infer intent beyond commit messages and touched files.</li>
-            This report is grounded in local commit metadata only. No pull request identifiers were present in the inspected
+          <li>Commit <code>8f0794dd</code> is timestamped in UTC; it still falls on May 18 in US/Eastern, so it is included.</li>
-            git history, so the summary references commits and files instead of PR numbers.
+          <li>Metrics are based on local git history at regeneration time and can change if additional backdated commits appear.</li>
-          </li>
-          <li>
-            The <code>update beads</code> commit touched only <code>deployment/docker/workspace-root/package.json</code> in
-            visible git output, so this report does not infer intent beyond that recorded file change.
-          </li>
-          <li>
-            Counts here describe May 18 commits only and exclude any uncommitted work present after that date.
-          </li>
         </ul>
       </section>
 
       <section>
         <h2>Follow-up Work</h2>
         <ul>
-          <li>
+          <li>This regeneration is tracked by beads issue <code>islandflow-0ty</code>.</li>
-            No new product follow-up items were derived from this reporting pass. The only beads item created for this task
+          <li>No additional follow-up work was identified during this documentation-only task.</li>
-            is <code>islandflow-2df</code>, which tracks publication of this summary document.
-          </li>
         </ul>
       </section>
     </main>

docs/index.html

@@ -0,0 +1,638 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Islandflow Docs</title>
+    <style>
+      :root {
+        --bg: #f4f6f8;
+        --surface: #ffffff;
+        --surface-muted: #e8edf2;
+        --text: #1a2433;
+        --muted: #5b6a80;
+        --border: #ccd5df;
+        --accent: #0f766e;
+        --accent-soft: #d1fae5;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      body {
+        margin: 0;
+        font-family: "Avenir Next", "Segoe UI", sans-serif;
+        background: radial-gradient(circle at top right, #e2f8f2, var(--bg) 35%);
+        color: var(--text);
+      }
+
+      main {
+        max-width: 1120px;
+        margin: 0 auto;
+        padding: 32px 16px 48px;
+      }
+
+      .header {
+        display: grid;
+        gap: 12px;
+      }
+
+      h1 {
+        margin: 0;
+        font-size: clamp(1.8rem, 2.3vw, 2.4rem);
+        font-weight: 760;
+      }
+
+      .subtitle {
+        margin: 0;
+        color: var(--muted);
+        max-width: 60ch;
+      }
+
+      .toolbar {
+        margin-top: 10px;
+        padding: 14px;
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        background: var(--surface);
+        display: grid;
+        gap: 12px;
+      }
+
+      .stats {
+        font-size: 0.95rem;
+        color: var(--muted);
+      }
+
+      .search {
+        width: 100%;
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        font: inherit;
+        font-size: 1rem;
+        padding: 10px 12px;
+        background: #fff;
+      }
+
+      .search:focus {
+        outline: 2px solid color-mix(in srgb, var(--accent) 30%, white);
+        outline-offset: 0;
+        border-color: var(--accent);
+      }
+
+      .chips {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+      }
+
+      .chip {
+        text-decoration: none;
+        color: var(--text);
+        background: var(--surface-muted);
+        padding: 6px 10px;
+        border-radius: 999px;
+        font-size: 0.85rem;
+        border: 1px solid transparent;
+      }
+
+      .chip span {
+        color: var(--muted);
+      }
+
+      .chip:hover {
+        border-color: var(--accent);
+      }
+
+      .groups {
+        margin-top: 20px;
+        display: grid;
+        gap: 16px;
+      }
+
+      .group {
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        background: var(--surface);
+        padding: 14px;
+      }
+
+      .group.hidden {
+        display: none;
+      }
+
+      .group h2 {
+        margin: 0 0 10px;
+        font-size: 1.1rem;
+      }
+
+      .group h2 span {
+        color: var(--muted);
+        font-weight: 520;
+      }
+
+      .doc-list {
+        margin: 0;
+        padding: 0;
+        list-style: none;
+        display: grid;
+        gap: 6px;
+      }
+
+      .doc-item {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 10px;
+        padding: 8px 10px;
+        border-radius: 6px;
+      }
+
+      .doc-item.hidden {
+        display: none;
+      }
+
+      .doc-item:hover {
+        background: #f5faf8;
+      }
+
+      .doc-link {
+        color: var(--text);
+        text-decoration: none;
+        font-family: "IBM Plex Mono", "SFMono-Regular", Consolas, monospace;
+        font-size: 0.92rem;
+        overflow-wrap: anywhere;
+      }
+
+      .doc-link:hover {
+        color: var(--accent);
+        text-decoration: underline;
+      }
+
+      .meta {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+        color: var(--muted);
+        font-size: 0.82rem;
+        white-space: nowrap;
+      }
+
+      .tag {
+        background: var(--accent-soft);
+        color: #065f46;
+        border-radius: 999px;
+        padding: 3px 8px;
+        font-size: 0.78rem;
+      }
+
+      .empty {
+        margin-top: 20px;
+        border: 1px dashed var(--border);
+        border-radius: 8px;
+        background: var(--surface);
+        color: var(--muted);
+        padding: 20px;
+        text-align: center;
+        display: none;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header class="header">
+        <h1>Islandflow docs index</h1>
+        <p class="subtitle">A browsable index of files under <code>docs/</code> with filtering and grouped navigation.</p>
+      </header>
+
+      <section class="toolbar">
+        <div class="stats"><strong id="visible-count">35</strong> of <strong>35</strong> files shown</div>
+        <input id="doc-search" class="search" type="search" placeholder="Filter by filename or folder..." autocomplete="off" />
+        <nav class="chips"><a class="chip" href="#category-turns">turns <span>28</span></a>
+<a class="chip" href="#category-daily-git">daily-git <span>1</span></a>
+<a class="chip" href="#category-general">general <span>2</span></a>
+<a class="chip" href="#category-plans">plans <span>2</span></a>
+<a class="chip" href="#category-root">root <span>2</span></a></nav>
+      </section>
+
+      <section class="groups" id="groups">
+        <section class="group" id="category-turns">
+          <h2>turns <span>28</span></h2>
+          <ul class="doc-list">
+            
+            <li class="doc-item" data-search="turns/2026-05-19-publish-docs-pages-index.html turns">
+              <a class="doc-link" href="./turns/2026-05-19-publish-docs-pages-index.html">turns/2026-05-19-publish-docs-pages-index.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>6.7 KB</span>
+                <span>May 19, 2026, 2:59 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-18-native-public-edge-cutover.html turns">
+              <a class="doc-link" href="./turns/2026-05-18-native-public-edge-cutover.html">turns/2026-05-18-native-public-edge-cutover.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>19 KB</span>
+                <span>May 19, 2026, 2:48 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-19-reconcile-pr-conflicts.html turns">
+              <a class="doc-link" href="./turns/2026-05-19-reconcile-pr-conflicts.html">turns/2026-05-19-reconcile-pr-conflicts.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>9.8 KB</span>
+                <span>May 19, 2026, 2:48 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-18-native-fast-iterative-deploy.html turns">
+              <a class="doc-link" href="./turns/2026-05-18-native-fast-iterative-deploy.html">turns/2026-05-18-native-fast-iterative-deploy.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>9.0 KB</span>
+                <span>May 19, 2026, 2:48 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-19-0805-clarify-repo-turn-doc-rules.html turns">
+              <a class="doc-link" href="./turns/2026-05-19-0805-clarify-repo-turn-doc-rules.html">turns/2026-05-19-0805-clarify-repo-turn-doc-rules.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>6.4 KB</span>
+                <span>May 19, 2026, 8:05 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-19-0739-update-readme-current-state.html turns">
+              <a class="doc-link" href="./turns/2026-05-19-0739-update-readme-current-state.html">turns/2026-05-19-0739-update-readme-current-state.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>9.8 KB</span>
+                <span>May 19, 2026, 7:39 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-19-upgrade-nextjs-16.html turns">
+              <a class="doc-link" href="./turns/2026-05-19-upgrade-nextjs-16.html">turns/2026-05-19-upgrade-nextjs-16.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>9.0 KB</span>
+                <span>May 19, 2026, 7:31 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-18-news-wire-view.html turns">
+              <a class="doc-link" href="./turns/2026-05-18-news-wire-view.html">turns/2026-05-18-news-wire-view.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>7.0 KB</span>
+                <span>May 18, 2026, 4:54 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-17-forgejo-deploy-remote-resolution.html turns">
+              <a class="doc-link" href="./turns/2026-05-17-forgejo-deploy-remote-resolution.html">turns/2026-05-17-forgejo-deploy-remote-resolution.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>5.3 KB</span>
+                <span>May 17, 2026, 11:22 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-17-add-fast-deploy-mode.html turns">
+              <a class="doc-link" href="./turns/2026-05-17-add-fast-deploy-mode.html">turns/2026-05-17-add-fast-deploy-mode.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>5.5 KB</span>
+                <span>May 17, 2026, 10:53 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-17-1101-clickhouse-alert-context.html turns">
+              <a class="doc-link" href="./turns/2026-05-17-1101-clickhouse-alert-context.html">turns/2026-05-17-1101-clickhouse-alert-context.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>6.4 KB</span>
+                <span>May 17, 2026, 10:21 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-17-clickhouse-alert-context.html turns">
+              <a class="doc-link" href="./turns/2026-05-17-clickhouse-alert-context.html">turns/2026-05-17-clickhouse-alert-context.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>11 KB</span>
+                <span>May 17, 2026, 10:21 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-17-deploy-allowlist-pr-packaging.html turns">
+              <a class="doc-link" href="./turns/2026-05-17-deploy-allowlist-pr-packaging.html">turns/2026-05-17-deploy-allowlist-pr-packaging.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>5.2 KB</span>
+                <span>May 17, 2026, 10:21 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-17-configure-beads-dolt-remote.html turns">
+              <a class="doc-link" href="./turns/2026-05-17-configure-beads-dolt-remote.html">turns/2026-05-17-configure-beads-dolt-remote.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>7.7 KB</span>
+                <span>May 17, 2026, 10:07 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-16-live-tape-scroll-hold-history.html turns">
+              <a class="doc-link" href="./turns/2026-05-16-live-tape-scroll-hold-history.html">turns/2026-05-16-live-tape-scroll-hold-history.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>6.3 KB</span>
+                <span>May 17, 2026, 5:06 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-17-0331-fix-live-tape-scroll-stability.html turns">
+              <a class="doc-link" href="./turns/2026-05-17-0331-fix-live-tape-scroll-stability.html">turns/2026-05-17-0331-fix-live-tape-scroll-stability.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>5.6 KB</span>
+                <span>May 17, 2026, 5:06 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-16-1725-durable-options-tape-history.html turns">
+              <a class="doc-link" href="./turns/2026-05-16-1725-durable-options-tape-history.html">turns/2026-05-16-1725-durable-options-tape-history.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>7.5 KB</span>
+                <span>May 17, 2026, 5:06 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-16-1752-speed-up-docker-deploys.html turns">
+              <a class="doc-link" href="./turns/2026-05-16-1752-speed-up-docker-deploys.html">turns/2026-05-16-1752-speed-up-docker-deploys.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>7.9 KB</span>
+                <span>May 17, 2026, 5:06 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-16-2159-fix-durable-options-history-routing.html turns">
+              <a class="doc-link" href="./turns/2026-05-16-2159-fix-durable-options-history-routing.html">turns/2026-05-16-2159-fix-durable-options-history-routing.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>6.4 KB</span>
+                <span>May 17, 2026, 5:06 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-15-add-duplicate-vps-compose-warning.html turns">
+              <a class="doc-link" href="./turns/2026-05-15-add-duplicate-vps-compose-warning.html">turns/2026-05-15-add-duplicate-vps-compose-warning.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>7.2 KB</span>
+                <span>May 15, 2026, 9:28 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-15-clarify-docker-first-deploy-workflow.html turns">
+              <a class="doc-link" href="./turns/2026-05-15-clarify-docker-first-deploy-workflow.html">turns/2026-05-15-clarify-docker-first-deploy-workflow.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>6.5 KB</span>
+                <span>May 15, 2026, 9:12 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-15-dual-runtime-deploy-workflow.html turns">
+              <a class="doc-link" href="./turns/2026-05-15-dual-runtime-deploy-workflow.html">turns/2026-05-15-dual-runtime-deploy-workflow.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>7.9 KB</span>
+                <span>May 15, 2026, 8:52 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-15-deploy-preflight-docker-workspace-check.html turns">
+              <a class="doc-link" href="./turns/2026-05-15-deploy-preflight-docker-workspace-check.html">turns/2026-05-15-deploy-preflight-docker-workspace-check.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>3.6 KB</span>
+                <span>May 15, 2026, 7:03 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-15-fix-docker-workspace-lockfile-sync.html turns">
+              <a class="doc-link" href="./turns/2026-05-15-fix-docker-workspace-lockfile-sync.html">turns/2026-05-15-fix-docker-workspace-lockfile-sync.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>3.6 KB</span>
+                <span>May 15, 2026, 6:56 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-15-quiet-terminal-view.html turns">
+              <a class="doc-link" href="./turns/2026-05-15-quiet-terminal-view.html">turns/2026-05-15-quiet-terminal-view.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>5.3 KB</span>
+                <span>May 15, 2026, 6:55 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-14-1824-adapt-terminal-view.html turns">
+              <a class="doc-link" href="./turns/2026-05-14-1824-adapt-terminal-view.html">turns/2026-05-14-1824-adapt-terminal-view.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>6.6 KB</span>
+                <span>May 15, 2026, 6:55 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-14-1833-reconcile-pr-conflicts.html turns">
+              <a class="doc-link" href="./turns/2026-05-14-1833-reconcile-pr-conflicts.html">turns/2026-05-14-1833-reconcile-pr-conflicts.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>5.6 KB</span>
+                <span>May 15, 2026, 6:55 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="turns/2026-05-14-harden-terminal-view.html turns">
+              <a class="doc-link" href="./turns/2026-05-14-harden-terminal-view.html">turns/2026-05-14-harden-terminal-view.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>9.2 KB</span>
+                <span>May 15, 2026, 6:55 PM</span>
+              </div>
+            </li>
+          
+          </ul>
+        </section>
+      
+
+        <section class="group" id="category-daily-git">
+          <h2>daily-git <span>1</span></h2>
+          <ul class="doc-list">
+            
+            <li class="doc-item" data-search="daily-git/2026-05-19-standup-summary-2026-05-18.html daily-git">
+              <a class="doc-link" href="./daily-git/2026-05-19-standup-summary-2026-05-18.html">daily-git/2026-05-19-standup-summary-2026-05-18.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>16 KB</span>
+                <span>May 19, 2026, 2:55 PM</span>
+              </div>
+            </li>
+          
+          </ul>
+        </section>
+      
+
+        <section class="group" id="category-general">
+          <h2>general <span>2</span></h2>
+          <ul class="doc-list">
+            
+            <li class="doc-item" data-search="general/2026-05-18-standup-summary-2026-05-17.html general">
+              <a class="doc-link" href="./general/2026-05-18-standup-summary-2026-05-17.html">general/2026-05-18-standup-summary-2026-05-17.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>19 KB</span>
+                <span>May 18, 2026, 9:05 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="general/2026-05-17-standup-summary-2026-05-16.html general">
+              <a class="doc-link" href="./general/2026-05-17-standup-summary-2026-05-16.html">general/2026-05-17-standup-summary-2026-05-16.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>17 KB</span>
+                <span>May 17, 2026, 10:07 AM</span>
+              </div>
+            </li>
+          
+          </ul>
+        </section>
+      
+
+        <section class="group" id="category-plans">
+          <h2>plans <span>2</span></h2>
+          <ul class="doc-list">
+            
+            <li class="doc-item" data-search="plans/2026-05-18-native-fast-iterative-deploy-plan.html plans">
+              <a class="doc-link" href="./plans/2026-05-18-native-fast-iterative-deploy-plan.html">plans/2026-05-18-native-fast-iterative-deploy-plan.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>3.8 KB</span>
+                <span>May 19, 2026, 2:48 PM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="plans/2026-05-16-1711-durable-options-tape-history.html plans">
+              <a class="doc-link" href="./plans/2026-05-16-1711-durable-options-tape-history.html">plans/2026-05-16-1711-durable-options-tape-history.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>12 KB</span>
+                <span>May 17, 2026, 5:06 AM</span>
+              </div>
+            </li>
+          
+          </ul>
+        </section>
+      
+
+        <section class="group" id="category-root">
+          <h2>root <span>2</span></h2>
+          <ul class="doc-list">
+            
+            <li class="doc-item" data-search="clickhouse-reset-runbook.md root">
+              <a class="doc-link" href="./clickhouse-reset-runbook.md">clickhouse-reset-runbook.md</a>
+              <div class="meta">
+                <span class="tag">md</span>
+                <span>3.0 KB</span>
+                <span>May 17, 2026, 5:06 AM</span>
+              </div>
+            </li>
+          
+
+            <li class="doc-item" data-search="terminal-audit-2026-05-14-0432.html root">
+              <a class="doc-link" href="./terminal-audit-2026-05-14-0432.html">terminal-audit-2026-05-14-0432.html</a>
+              <div class="meta">
+                <span class="tag">html</span>
+                <span>22 KB</span>
+                <span>May 15, 2026, 6:55 PM</span>
+              </div>
+            </li>
+          
+          </ul>
+        </section>
+      </section>
+      <p class="empty" id="empty-state">No files match that filter.</p>
+    </main>
+
+    <script>
+      const searchInput = document.getElementById("doc-search");
+      const items = Array.from(document.querySelectorAll(".doc-item"));
+      const groups = Array.from(document.querySelectorAll(".group"));
+      const visibleCount = document.getElementById("visible-count");
+      const emptyState = document.getElementById("empty-state");
+
+      function applyFilter(query) {
+        const normalized = query.trim().toLowerCase();
+        let shown = 0;
+
+        for (const item of items) {
+          const searchable = item.dataset.search || "";
+          const isVisible = normalized.length === 0 || searchable.includes(normalized);
+          item.classList.toggle("hidden", !isVisible);
+          if (isVisible) shown += 1;
+        }
+
+        for (const group of groups) {
+          const hasVisibleItems = group.querySelector(".doc-item:not(.hidden)") !== null;
+          group.classList.toggle("hidden", !hasVisibleItems);
+        }
+
+        visibleCount.textContent = String(shown);
+        emptyState.style.display = shown === 0 ? "block" : "none";
+      }
+
+      searchInput.addEventListener("input", () => applyFilter(searchInput.value));
+      applyFilter("");
+    </script>
+  </body>
+</html>

docs/turns/2026-05-19-harden-native-ssh-deploy-checks.html

@@ -0,0 +1,191 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>2026-05-19 Harden Native SSH Deploy Checks</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --bg: #f6f4f8;
+        --surface: #ffffff;
+        --ink: #1f1726;
+        --muted: #5f536d;
+        --line: #ddd4e6;
+        --accent: #7c4dff;
+        --accent-soft: #efe7ff;
+        --code-bg: #17131d;
+        --code-ink: #f7f2ff;
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+        background: var(--bg);
+        color: var(--ink);
+        line-height: 1.55;
+      }
+      main {
+        max-width: 980px;
+        margin: 0 auto;
+        padding: 40px 24px 72px;
+      }
+      header, section {
+        background: var(--surface);
+        border: 1px solid var(--line);
+        border-radius: 14px;
+        padding: 24px;
+        margin-bottom: 18px;
+      }
+      h1, h2 {
+        margin: 0 0 12px;
+        line-height: 1.15;
+      }
+      h1 { font-size: 2rem; }
+      h2 { font-size: 1.15rem; }
+      .lede {
+        font-size: 1.05rem;
+        color: var(--muted);
+      }
+      .meta {
+        display: inline-block;
+        margin-top: 10px;
+        padding: 6px 10px;
+        border-radius: 999px;
+        background: var(--accent-soft);
+        color: var(--accent);
+        font-size: 0.9rem;
+        font-weight: 600;
+      }
+      ul {
+        margin: 0;
+        padding-left: 18px;
+      }
+      pre {
+        margin: 0;
+        padding: 16px;
+        overflow: auto;
+        border-radius: 10px;
+        background: var(--code-bg);
+        color: var(--code-ink);
+      }
+      code {
+        font-family: "SFMono-Regular", ui-monospace, monospace;
+        font-size: 0.94rem;
+      }
+      .note {
+        margin-top: 10px;
+        color: var(--muted);
+        font-size: 0.92rem;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Harden Native SSH Deploy Checks</h1>
+        <p class="lede">
+          Native deploys over SSH were failing for avoidable operator reasons: the remote shell did not inherit Bun's install path, and native verification assumed it was already running from the repository root before it called checked-in health scripts. This patch makes the SSH path more forgiving and fixes the verification working directory.
+        </p>
+        <div class="meta">Generated 2026-05-19 19:38 EDT</div>
+      </header>
+
+      <section>
+        <h2>Summary</h2>
+        <p>
+          Updated <code>scripts/deploy.ts</code> so native SSH deploys prepend <code>$HOME/.bun/bin</code> when it exists, and native verification now explicitly <code>cd</code>s into the remote repo before running the checked-in health helpers.
+        </p>
+      </section>
+
+      <section>
+        <h2>Changes Made</h2>
+        <ul>
+          <li>Prepended <code>$HOME/.bun/bin</code> during native remote precheck when available.</li>
+          <li>Prepended <code>$HOME/.bun/bin</code> during native remote rollout when available.</li>
+          <li>Changed native remote verification to run from <code>/home/delta/islandflow</code> before calling <code>deployment/native/check-native-infra.sh</code>.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Context</h2>
+        <p>
+          During a live native rollout, the deploy helper failed first because the non-login SSH shell could not find <code>bun</code> even though it was installed under the deploy user's home directory. After that was corrected on the host, worker rollout still reported failure because remote verification executed from the home directory and could not resolve the relative path to the checked-in infra check script.
+        </p>
+      </section>
+
+      <section>
+        <h2>Important Implementation Details</h2>
+        <ul>
+          <li>The fallback only adjusts <code>PATH</code> when <code>$HOME/.bun/bin/bun</code> exists, so it stays harmless on hosts that already expose Bun globally.</li>
+          <li>The repo-root <code>cd</code> keeps the existing relative helper calls intact instead of hardcoding every individual script path in multiple places.</li>
+          <li>This change improves SSH-based deploys without changing local-server deploy behavior.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Relevant Diff Snippets</h2>
+        <p class="note">Unified diff blocks below are formatted for diffs-compatible rendering.</p>
+        <pre><code class="language-diff">diff --git a/scripts/deploy.ts b/scripts/deploy.ts
+@@ -754,6 +754,10 @@ set -euo pipefail
+ 
+ cd ${shellEscape(REMOTE_REPO)}
+ 
++if [[ -x "$HOME/.bun/bin/bun" ]]; then
++  export PATH="$HOME/.bun/bin:$PATH"
++fi
++
+ if ! command -v bun >/dev/null 2>&1; then
+
+@@ -855,6 +859,10 @@ set -euo pipefail
+ 
++if [[ -x "$HOME/.bun/bin/bun" ]]; then
++  export PATH="$HOME/.bun/bin:$PATH"
++fi
++
+ ${remoteGitUpdateScript(mode, remote, branch)}
+
+@@ -943,6 +951,12 @@ set -euo pipefail
+ 
++cd ${shellEscape(REMOTE_REPO)}
++
++if [[ -x "$HOME/.bun/bin/bun" ]]; then
++  export PATH="$HOME/.bun/bin:$PATH"
++fi
++
+ declare -a units=(${units})</code></pre>
+      </section>
+
+      <section>
+        <h2>Expected Impact for End-Users</h2>
+        <p>
+          End users should see fewer failed native deploy attempts and fewer partial restarts caused by tooling assumptions rather than application health. This lowers the odds of avoidable downtime during native rollouts.
+        </p>
+      </section>
+
+      <section>
+        <h2>Validation</h2>
+        <ul>
+          <li>Observed the original failures during live rollout: missing <code>bun</code> in SSH PATH and missing <code>deployment/native/check-native-infra.sh</code> during remote verification.</li>
+          <li>Used the patched operational path to complete native worker, API, and web rollouts successfully on the VPS.</li>
+          <li>Verified API health at <code>http://127.0.0.1:4000/health</code> and web health at both <code>http://127.0.0.1:3000/</code> and <code>https://flow.deltaisland.io</code>.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Issues, Limitations, and Mitigations</h2>
+        <ul>
+          <li>This patch does not solve the separate <code>ingest-news</code> credential problem. Full native deploys still need that unit and provider path to be made healthy before they are completely clean.</li>
+          <li>The VPS also needed a host-level Bun symlink during this recovery. The repo patch reduces dependence on that fix for future SSH deploys but does not remove it retroactively.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Follow-up Work</h2>
+        <ul>
+          <li><code>islandflow-fmg</code>: Keep the deploy helper aligned with the actual VPS runtime assumptions and add regression checks around native verification paths.</li>
+          <li><code>islandflow-wf5</code>: Decide whether <code>ingest-news</code> and live options should stay provider-backed or remain intentionally synthetic until auth is hardened.</li>
+        </ul>
+      </section>
+    </main>
+  </body>
+</html>

docs/turns/2026-05-19-native-options-recovery-guardrails.html

@@ -0,0 +1,183 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>2026-05-19 Native Options Recovery Guardrails</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --bg: #f6f4f8;
+        --surface: #ffffff;
+        --ink: #1f1726;
+        --muted: #5f536d;
+        --line: #ddd4e6;
+        --accent: #7c4dff;
+        --accent-soft: #efe7ff;
+        --code-bg: #17131d;
+        --code-ink: #f7f2ff;
+      }
+
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+        background: var(--bg);
+        color: var(--ink);
+        line-height: 1.55;
+      }
+      main {
+        max-width: 980px;
+        margin: 0 auto;
+        padding: 40px 24px 72px;
+      }
+      header, section {
+        background: var(--surface);
+        border: 1px solid var(--line);
+        border-radius: 14px;
+        padding: 24px;
+        margin-bottom: 18px;
+      }
+      h1, h2 {
+        margin: 0 0 12px;
+        line-height: 1.15;
+      }
+      h1 { font-size: 2rem; }
+      h2 { font-size: 1.15rem; }
+      p, li { color: var(--ink); }
+      .lede {
+        font-size: 1.05rem;
+        color: var(--muted);
+      }
+      .meta {
+        display: inline-block;
+        margin-top: 10px;
+        padding: 6px 10px;
+        border-radius: 999px;
+        background: var(--accent-soft);
+        color: var(--accent);
+        font-size: 0.9rem;
+        font-weight: 600;
+      }
+      ul {
+        margin: 0;
+        padding-left: 18px;
+      }
+      pre {
+        margin: 0;
+        padding: 16px;
+        overflow: auto;
+        border-radius: 10px;
+        background: var(--code-bg);
+        color: var(--code-ink);
+      }
+      code {
+        font-family: "SFMono-Regular", ui-monospace, monospace;
+        font-size: 0.94rem;
+      }
+      .note {
+        margin-top: 10px;
+        color: var(--muted);
+        font-size: 0.92rem;
+      }
+      a { color: var(--accent); }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Native Options Recovery Guardrails</h1>
+        <p class="lede">
+          The production outage turned out to be a native deployment config mismatch, not a data-pipeline code failure. I restored the VPS to the last known-good synthetic options adapter, then tightened the checked-in native deployment assets so they no longer imply a systemd override will beat the repo <code>.env</code>.
+        </p>
+        <div class="meta">Generated 2026-05-19 19:24 EDT</div>
+      </header>
+
+      <section>
+        <h2>Summary</h2>
+        <p>
+          The repo-side change is small and targeted: remove the misleading <code>Environment=OPTIONS_INGEST_ADAPTER=synthetic</code> line from the checked-in native <code>ingest-options</code> unit, and document that Bun-launched services effectively take adapter selection from <code>/home/delta/islandflow/.env</code>.
+        </p>
+      </section>
+
+      <section>
+        <h2>Changes Made</h2>
+        <ul>
+          <li>Removed the checked-in systemd override from <code>deployment/native/systemd/user/islandflow-ingest-options.service</code>.</li>
+          <li>Added an explicit env-precedence warning to <code>deployment/native/README.md</code>.</li>
+          <li>Captured the live diagnosis that the native server had drifted to <code>OPTIONS_INGEST_ADAPTER=alpaca</code> while the prior Docker deployment was running synthetic options.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Context</h2>
+        <p>
+          On the VPS, <code>islandflow-ingest-options.service</code> was crash-looping with repeated <code>401 Unauthorized</code> responses from Alpaca while the rest of the native stack stayed healthy. The previous Docker-owned <code>islandflow-vps-ingest-options-1</code> container showed <code>OPTIONS_INGEST_ADAPTER=synthetic</code>, which explains why the UI had been healthy before the runtime transition.
+        </p>
+      </section>
+
+      <section>
+        <h2>Important Implementation Details</h2>
+        <ul>
+          <li>The checked-in unit already referenced <code>/home/delta/islandflow/.env</code>, and Bun's runtime env loading meant a conflicting adapter value there still won in practice.</li>
+          <li>The static key currently stored as <code>ALPACA_API_KEY</code> does not authenticate the failing market-data snapshot request as a Bearer token.</li>
+          <li>Because the real outage fix required a server-side <code>.env</code> correction, this repo patch focuses on preventing operator confusion during the next native cutover.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Relevant Diff Snippets</h2>
+        <p class="note">Unified diff blocks below are formatted for diffs-compatible rendering.</p>
+        <pre><code class="language-diff">diff --git a/deployment/native/README.md b/deployment/native/README.md
+@@ -98,6 +98,8 @@ These are written for the current VPS layout:
+ - Bun binary: `/home/delta/.bun/bin/bun`
+ - env file: `/home/delta/islandflow/.env`
+ 
++Important: treat `/home/delta/islandflow/.env` as the effective source of truth for adapter selection. The Bun-launched services read that file directly at runtime, so a conflicting `OPTIONS_INGEST_ADAPTER` value in `.env` can still win over a systemd-only override and push `ingest-options` onto the wrong provider path.
++
+ ### Install the units
+
+diff --git a/deployment/native/systemd/user/islandflow-ingest-options.service b/deployment/native/systemd/user/islandflow-ingest-options.service
+@@ -7,7 +7,6 @@ Wants=network-online.target
+ Type=simple
+ WorkingDirectory=/home/delta/islandflow
+ EnvironmentFile=/home/delta/islandflow/.env
+-Environment=OPTIONS_INGEST_ADAPTER=synthetic
+ ExecStart=/home/delta/.bun/bin/bun services/ingest-options/src/index.ts</code></pre>
+      </section>
+
+      <section>
+        <h2>Expected Impact for End-Users</h2>
+        <p>
+          End users should not see the options tape stall the next time native units are installed or audited by following the checked-in assets. Operators now have a clearer paper trail that the actual runtime adapter comes from the deployment env file.
+        </p>
+      </section>
+
+      <section>
+        <h2>Validation</h2>
+        <ul>
+          <li>Verified the native outage mode on the VPS: <code>islandflow-ingest-options.service</code> crash-looped on Alpaca <code>401</code> responses.</li>
+          <li>Confirmed the previous Docker container had been running <code>OPTIONS_INGEST_ADAPTER=synthetic</code>.</li>
+          <li>After the server-side env fix, confirmed fresh rows in <code>default.option_prints</code> and new compute emissions in the native logs.</li>
+          <li>Ran <code>git diff</code> to verify the repo change stayed scoped to the deployment README and the checked-in user unit.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Issues, Limitations, and Mitigations</h2>
+        <ul>
+          <li>The repo patch does not add new credential support for Alpaca. It only documents the current env-precedence behavior and removes a misleading override.</li>
+          <li>The live server is restored with synthetic options, which matches the last known-good Docker behavior, but it is not a true live Alpaca ingest path.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Follow-up Work</h2>
+        <ul>
+          <li><code>islandflow-wf5</code>: Decide whether production options should remain synthetic or move to a fully supported live provider configuration.</li>
+          <li><code>islandflow-wf5</code>: If Alpaca live data is still desired, add a validated auth flow and a deploy-time smoke test that catches provider auth failures before cutover.</li>
+        </ul>
+      </section>
+    </main>
+  </body>
+</html>

docs/turns/2026-05-19-publish-docs-pages-index.html

@@ -0,0 +1,195 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Turn Report - Publish Docs to GitHub Pages</title>
+    <style>
+      :root {
+        --bg: #f6f8fb;
+        --surface: #ffffff;
+        --text: #172133;
+        --muted: #56637a;
+        --border: #d5dde8;
+        --accent: #0b7a75;
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        background: var(--bg);
+        color: var(--text);
+        font-family: "Inter", "Segoe UI", sans-serif;
+        line-height: 1.5;
+      }
+      main {
+        max-width: 980px;
+        margin: 0 auto;
+        padding: 28px 16px 44px;
+      }
+      h1, h2 { line-height: 1.2; }
+      h1 { margin: 0 0 8px; font-size: clamp(1.6rem, 2.2vw, 2.1rem); }
+      h2 {
+        margin: 0;
+        font-size: 1.18rem;
+      }
+      .meta {
+        margin: 0 0 20px;
+        color: var(--muted);
+      }
+      section {
+        background: var(--surface);
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        padding: 14px 16px;
+        margin-bottom: 12px;
+      }
+      p, li { margin: 0; }
+      p + p { margin-top: 8px; }
+      ul {
+        margin: 10px 0 0;
+        padding-left: 18px;
+      }
+      li + li { margin-top: 6px; }
+      code {
+        font-family: "IBM Plex Mono", "SFMono-Regular", Consolas, monospace;
+        font-size: 0.92em;
+      }
+      pre {
+        margin: 10px 0 0;
+        overflow-x: auto;
+        padding: 12px;
+        border-radius: 8px;
+        background: #0f172a;
+        color: #e2e8f0;
+        border: 1px solid #1e293b;
+      }
+      .note {
+        margin-top: 10px;
+        color: var(--muted);
+        font-size: 0.95rem;
+      }
+      a { color: var(--accent); }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Publish docs/ to GitHub Pages with navigable index</h1>
+      <p class="meta">Completed on May 19, 2026 at 9:38 AM ET.</p>
+
+      <section>
+        <h2>Summary</h2>
+        <p>
+          Added an automated docs publishing flow to GitHub Pages and generated a new
+          <code>docs/index.html</code> browsing experience so docs are easy to navigate at
+          <code>/islandflow/docs/</code>.
+        </p>
+      </section>
+
+      <section>
+        <h2>Changes Made</h2>
+        <ul>
+          <li>Added <code>scripts/generate-docs-index.mjs</code> to build a browsable index of files under <code>docs/</code>.</li>
+          <li>Added <code>.github/workflows/docs-pages.yml</code> to publish docs to GitHub Pages on pushes to <code>main</code>.</li>
+          <li>Generated <code>docs/index.html</code> from current docs content.</li>
+          <li>Configured deployment artifact layout so docs are available at <code>/docs/</code> under the project Pages site.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Context</h2>
+        <p>
+          The repository already stores operational and implementation documentation under
+          <code>docs/</code>, but there was no dedicated GitHub Pages pipeline and no curated
+          index page for discovery. This task focused on syncing that folder to Pages and
+          making it easy to browse by category and filename.
+        </p>
+      </section>
+
+      <section>
+        <h2>Important Implementation Details</h2>
+        <ul>
+          <li>The index generator excludes hidden files and avoids self-including <code>docs/index.html</code>.</li>
+          <li>Files are grouped by first path segment (<code>turns</code>, <code>general</code>, <code>plans</code>, and others) with quick category chips.</li>
+          <li>The index includes client-side filtering so users can search docs by path text in-browser.</li>
+          <li>Pages deployment packages a <code>site/</code> payload where docs are copied into <code>site/docs</code> and root redirects to <code>./docs/</code>.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Relevant Diff Snippets</h2>
+        <p class="note">
+          Snippets are shown in a compact style aligned with <a href="https://diffs.com/docs">diffs.com</a> presentation patterns.
+        </p>
+        <pre><code class="language-diff">+++ .github/workflows/docs-pages.yml
+name: Publish Docs
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "scripts/generate-docs-index.mjs"
+      - ".github/workflows/docs-pages.yml"
+  workflow_dispatch:
+
+jobs:
+  build:
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - run: node scripts/generate-docs-index.mjs
+      - run: cp -R docs/. site/docs/
+      - uses: actions/upload-pages-artifact@v3
+  deploy:
+    needs: build
+    steps:
+      - uses: actions/deploy-pages@v4</code></pre>
+        <pre><code class="language-diff">+++ scripts/generate-docs-index.mjs
+const files = await collectDocsFiles(docsDir);
+const html = renderDocument(files);
+await fs.writeFile(outputFile, html, "utf8");
+
+// Generated index features:
+// - grouped sections
+// - search filter
+// - file size and modified time metadata
+// - links preserving docs folder structure</code></pre>
+      </section>
+
+      <section>
+        <h2>Expected Impact for End-Users</h2>
+        <ul>
+          <li>Docs are reachable via a stable Pages URL path: <code>dirtydishes.github.io/islandflow/docs/</code>.</li>
+          <li>Readers can quickly scan categories and search by filename instead of relying on raw directory browsing.</li>
+          <li>New docs added to the repository are published automatically on <code>main</code> pushes.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Validation</h2>
+        <ul>
+          <li>Ran <code>node scripts/generate-docs-index.mjs</code> successfully.</li>
+          <li>Ran <code>node --check scripts/generate-docs-index.mjs</code> for syntax validation.</li>
+          <li>Confirmed generated index contains expected navigation/search markers and category anchors.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Issues, Limitations, and Mitigations</h2>
+        <ul>
+          <li>GitHub Pages must be enabled for this repository and set to GitHub Actions deployment.</li>
+          <li>The index reflects files present at build time and does not include full-text search inside documents.</li>
+          <li>Markdown files are linked as-is; rendering behavior depends on GitHub Pages static hosting behavior.</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Follow-up Work</h2>
+        <ul>
+          <li>Add a docs landing page summary for key collections (turn docs, runbooks, daily notes).</li>
+          <li>Optionally add link-checking in CI for docs URLs and local references.</li>
+          <li>Consider tagging docs with metadata for richer filtering by date, topic, and type.</li>
+        </ul>
+      </section>
+    </main>
+  </body>
+</html>

scripts/deploy.ts

@@ -754,6 +754,10 @@ set -euo pipefail
 
 cd ${shellEscape(REMOTE_REPO)}
 
+if [[ -x "$HOME/.bun/bin/bun" ]]; then
+  export PATH="$HOME/.bun/bin:$PATH"
+fi
+
 if ! command -v bun >/dev/null 2>&1; then
   echo "Refusing native rollout: bun is not installed on the server." >&2
   echo "The current supported VPS path remains --runtime docker." >&2
@@ -855,6 +859,10 @@ function remoteNativeRollout(
     `#!/usr/bin/env bash
 set -euo pipefail
 
+if [[ -x "$HOME/.bun/bin/bun" ]]; then
+  export PATH="$HOME/.bun/bin:$PATH"
+fi
+
 ${remoteGitUpdateScript(mode, remote, branch)}
 
 cd ${shellEscape(REMOTE_REPO)}
@@ -943,6 +951,12 @@ function remoteNativeVerification(scope: DeployScope, fast: boolean): void {
     `#!/usr/bin/env bash
 set -euo pipefail
 
+cd ${shellEscape(REMOTE_REPO)}
+
+if [[ -x "$HOME/.bun/bin/bun" ]]; then
+  export PATH="$HOME/.bun/bin:$PATH"
+fi
+
 declare -a units=(${units})
 for unit in "\${units[@]}"; do
   ${NATIVE_SYSTEMCTL_PREFIX} is-active --quiet "$unit"

scripts/generate-docs-index.mjs

@@ -0,0 +1,421 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+const docsDir = path.resolve(process.cwd(), "docs");
+const outputFile = path.join(docsDir, "index.html");
+
+const dateFormatter = new Intl.DateTimeFormat("en-US", {
+  dateStyle: "medium",
+  timeStyle: "short",
+});
+
+function escapeHtml(value) {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+
+  const units = ["KB", "MB", "GB"];
+  let size = bytes / 1024;
+  let unitIndex = 0;
+
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex += 1;
+  }
+
+  return `${size.toFixed(size >= 10 ? 0 : 1)} ${units[unitIndex]}`;
+}
+
+function docsHref(relativePath) {
+  const encoded = relativePath
+    .split("/")
+    .map((part) => encodeURIComponent(part))
+    .join("/");
+  return `./${encoded}`;
+}
+
+async function collectDocsFiles(rootDir, currentDir = rootDir, acc = []) {
+  const entries = await fs.readdir(currentDir, { withFileTypes: true });
+  const sortedEntries = entries.sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const entry of sortedEntries) {
+    if (entry.name.startsWith(".")) {
+      continue;
+    }
+
+    const absolutePath = path.join(currentDir, entry.name);
+    const relativePath = path.relative(rootDir, absolutePath).replaceAll(path.sep, "/");
+
+    if (relativePath === "index.html") {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      await collectDocsFiles(rootDir, absolutePath, acc);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      const stats = await fs.stat(absolutePath);
+
+      acc.push({
+        relativePath,
+        category: relativePath.includes("/") ? relativePath.split("/")[0] : "root",
+        sizeBytes: stats.size,
+        modifiedAt: stats.mtime,
+      });
+    }
+  }
+
+  return acc;
+}
+
+function groupByCategory(items) {
+  const groups = new Map();
+  for (const item of items) {
+    if (!groups.has(item.category)) {
+      groups.set(item.category, []);
+    }
+    groups.get(item.category).push(item);
+  }
+  return groups;
+}
+
+function sortedCategories(groups) {
+  const preferredOrder = ["turns", "daily-git", "general", "plans", "root"];
+  const groupNames = [...groups.keys()];
+  return groupNames.sort((a, b) => {
+    const aIndex = preferredOrder.indexOf(a);
+    const bIndex = preferredOrder.indexOf(b);
+
+    if (aIndex !== -1 || bIndex !== -1) {
+      if (aIndex === -1) return 1;
+      if (bIndex === -1) return -1;
+      return aIndex - bIndex;
+    }
+
+    return a.localeCompare(b);
+  });
+}
+
+function renderDocument(items) {
+  const sortedItems = [...items].sort((a, b) => b.modifiedAt.getTime() - a.modifiedAt.getTime());
+  const groups = groupByCategory(sortedItems);
+  const categories = sortedCategories(groups);
+  const totalCount = sortedItems.length;
+
+  const categoryChips = categories
+    .map((category) => {
+      const count = groups.get(category).length;
+      return `<a class="chip" href="#category-${escapeHtml(category)}">${escapeHtml(
+        category
+      )} <span>${count}</span></a>`;
+    })
+    .join("\n");
+
+  const groupsMarkup = categories
+    .map((category) => {
+      const entries = groups.get(category);
+      const entryMarkup = entries
+        .map((entry) => {
+          const extension = path.extname(entry.relativePath).replace(".", "") || "file";
+          const searchable = `${entry.relativePath} ${category}`.toLowerCase();
+          return `
+            <li class="doc-item" data-search="${escapeHtml(searchable)}">
+              <a class="doc-link" href="${docsHref(entry.relativePath)}">${escapeHtml(
+                entry.relativePath
+              )}</a>
+              <div class="meta">
+                <span class="tag">${escapeHtml(extension)}</span>
+                <span>${escapeHtml(formatBytes(entry.sizeBytes))}</span>
+                <span>${escapeHtml(dateFormatter.format(entry.modifiedAt))}</span>
+              </div>
+            </li>
+          `;
+        })
+        .join("\n");
+
+      return `
+        <section class="group" id="category-${escapeHtml(category)}">
+          <h2>${escapeHtml(category)} <span>${entries.length}</span></h2>
+          <ul class="doc-list">
+            ${entryMarkup}
+          </ul>
+        </section>
+      `;
+    })
+    .join("\n");
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Islandflow Docs</title>
+    <style>
+      :root {
+        --bg: #f4f6f8;
+        --surface: #ffffff;
+        --surface-muted: #e8edf2;
+        --text: #1a2433;
+        --muted: #5b6a80;
+        --border: #ccd5df;
+        --accent: #0f766e;
+        --accent-soft: #d1fae5;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      body {
+        margin: 0;
+        font-family: "Avenir Next", "Segoe UI", sans-serif;
+        background: radial-gradient(circle at top right, #e2f8f2, var(--bg) 35%);
+        color: var(--text);
+      }
+
+      main {
+        max-width: 1120px;
+        margin: 0 auto;
+        padding: 32px 16px 48px;
+      }
+
+      .header {
+        display: grid;
+        gap: 12px;
+      }
+
+      h1 {
+        margin: 0;
+        font-size: clamp(1.8rem, 2.3vw, 2.4rem);
+        font-weight: 760;
+      }
+
+      .subtitle {
+        margin: 0;
+        color: var(--muted);
+        max-width: 60ch;
+      }
+
+      .toolbar {
+        margin-top: 10px;
+        padding: 14px;
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        background: var(--surface);
+        display: grid;
+        gap: 12px;
+      }
+
+      .stats {
+        font-size: 0.95rem;
+        color: var(--muted);
+      }
+
+      .search {
+        width: 100%;
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        font: inherit;
+        font-size: 1rem;
+        padding: 10px 12px;
+        background: #fff;
+      }
+
+      .search:focus {
+        outline: 2px solid color-mix(in srgb, var(--accent) 30%, white);
+        outline-offset: 0;
+        border-color: var(--accent);
+      }
+
+      .chips {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+      }
+
+      .chip {
+        text-decoration: none;
+        color: var(--text);
+        background: var(--surface-muted);
+        padding: 6px 10px;
+        border-radius: 999px;
+        font-size: 0.85rem;
+        border: 1px solid transparent;
+      }
+
+      .chip span {
+        color: var(--muted);
+      }
+
+      .chip:hover {
+        border-color: var(--accent);
+      }
+
+      .groups {
+        margin-top: 20px;
+        display: grid;
+        gap: 16px;
+      }
+
+      .group {
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        background: var(--surface);
+        padding: 14px;
+      }
+
+      .group.hidden {
+        display: none;
+      }
+
+      .group h2 {
+        margin: 0 0 10px;
+        font-size: 1.1rem;
+      }
+
+      .group h2 span {
+        color: var(--muted);
+        font-weight: 520;
+      }
+
+      .doc-list {
+        margin: 0;
+        padding: 0;
+        list-style: none;
+        display: grid;
+        gap: 6px;
+      }
+
+      .doc-item {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 10px;
+        padding: 8px 10px;
+        border-radius: 6px;
+      }
+
+      .doc-item.hidden {
+        display: none;
+      }
+
+      .doc-item:hover {
+        background: #f5faf8;
+      }
+
+      .doc-link {
+        color: var(--text);
+        text-decoration: none;
+        font-family: "IBM Plex Mono", "SFMono-Regular", Consolas, monospace;
+        font-size: 0.92rem;
+        overflow-wrap: anywhere;
+      }
+
+      .doc-link:hover {
+        color: var(--accent);
+        text-decoration: underline;
+      }
+
+      .meta {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+        color: var(--muted);
+        font-size: 0.82rem;
+        white-space: nowrap;
+      }
+
+      .tag {
+        background: var(--accent-soft);
+        color: #065f46;
+        border-radius: 999px;
+        padding: 3px 8px;
+        font-size: 0.78rem;
+      }
+
+      .empty {
+        margin-top: 20px;
+        border: 1px dashed var(--border);
+        border-radius: 8px;
+        background: var(--surface);
+        color: var(--muted);
+        padding: 20px;
+        text-align: center;
+        display: none;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header class="header">
+        <h1>Islandflow docs index</h1>
+        <p class="subtitle">A browsable index of files under <code>docs/</code> with filtering and grouped navigation.</p>
+      </header>
+
+      <section class="toolbar">
+        <div class="stats"><strong id="visible-count">${totalCount}</strong> of <strong>${totalCount}</strong> files shown</div>
+        <input id="doc-search" class="search" type="search" placeholder="Filter by filename or folder..." autocomplete="off" />
+        <nav class="chips">${categoryChips}</nav>
+      </section>
+
+      <section class="groups" id="groups">${groupsMarkup}</section>
+      <p class="empty" id="empty-state">No files match that filter.</p>
+    </main>
+
+    <script>
+      const searchInput = document.getElementById("doc-search");
+      const items = Array.from(document.querySelectorAll(".doc-item"));
+      const groups = Array.from(document.querySelectorAll(".group"));
+      const visibleCount = document.getElementById("visible-count");
+      const emptyState = document.getElementById("empty-state");
+
+      function applyFilter(query) {
+        const normalized = query.trim().toLowerCase();
+        let shown = 0;
+
+        for (const item of items) {
+          const searchable = item.dataset.search || "";
+          const isVisible = normalized.length === 0 || searchable.includes(normalized);
+          item.classList.toggle("hidden", !isVisible);
+          if (isVisible) shown += 1;
+        }
+
+        for (const group of groups) {
+          const hasVisibleItems = group.querySelector(".doc-item:not(.hidden)") !== null;
+          group.classList.toggle("hidden", !hasVisibleItems);
+        }
+
+        visibleCount.textContent = String(shown);
+        emptyState.style.display = shown === 0 ? "block" : "none";
+      }
+
+      searchInput.addEventListener("input", () => applyFilter(searchInput.value));
+      applyFilter("");
+    </script>
+  </body>
+</html>
+`;
+}
+
+async function main() {
+  const files = await collectDocsFiles(docsDir);
+  const html = renderDocument(files);
+  await fs.writeFile(outputFile, html, "utf8");
+  console.log(`Generated ${outputFile} with ${files.length} entries.`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});