P0: release.yml typecheck + bind audit + loopback middleware (#84)

Three P0 fixes bundled — foundation cleanup before v0.3.0 phase work. Closes release.yml drift (PR #51's tabs broke v0.3.0 tag releases), production bind exposure (Critic F1), and 9-endpoint LAN gap on /system/* (Critic F2+F3). 5 new tests; 243 full pass.

Author: debpalash

.github/workflows/ci.yml

@@ -84,9 +84,11 @@ jobs:
 
       # checkJs is true in tsconfig for IDE feedback, but 947 pre-existing
       # JS errors remain. Override to false in CI so only .ts files block.
+      # Sourced from `typecheck:ci` in frontend/package.json so the release
+      # workflow runs an identical command — drift broke v0.3.x release runs.
       - name: Frontend typecheck
         working-directory: frontend
-        run: bunx tsc --noEmit --checkJs false
+        run: bun run typecheck:ci
 
       - name: Run Vitest (frontend)
         working-directory: frontend

.github/workflows/release.yml

@@ -93,9 +93,14 @@ jobs:
         working-directory: frontend
         run: bun install
 
+      # Single-sourced typecheck command (mirrors ci.yml). The `typecheck:ci`
+      # script in frontend/package.json sets `--checkJs false` so pre-existing
+      # JS-side errors don't block the release; only .ts/.tsx files gate.
+      # Drift between CI and release-time typecheck flags broke v0.3.x release
+      # runs — keep this command identical to ci.yml's step.
       - name: Frontend typecheck
         working-directory: frontend
-        run: bunx tsc --noEmit
+        run: bun run typecheck:ci
 
       # Invoke node directly (not `bun run test`) because `bun run` auto-aliases
       # `node` to `bun` in script bodies, and bun doesn't support

.planning/ROADMAP.md

@@ -53,14 +53,17 @@ All 11 open GitHub issues are closed or have a documented workaround surfaced in
 **Depends on:** Phase 0
 **User-value density:** This phase closes the most issues in the milestone — #35 (HF token + diarization sub-issues), #54 (macOS quarantine via documented `xattr -cr` workaround surfaced in error UI), #56 (AppImage white-screen via documented `WEBKIT_DISABLE_COMPOSITING_MODE=1` workaround), #58 (`pkg_resources`), and partial #55 (CosyVoice docs).
 **Closes issues:** #35, #54 (documented workaround), #55 (partial), #56 (documented workaround), #58
-**Requirements:** INST-01, INST-02, INST-03, INST-04, INST-05, INST-06, DOCS-01, DOCS-02, DOCS-03, DOCS-04, DOCS-05, AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05
+**Requirements:** INST-01, INST-02, INST-03, INST-04, INST-05, INST-06, DOCS-01, DOCS-02, DOCS-03, DOCS-04, DOCS-05, AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05, AUTH-06 (scope additions: #76 .deb ffprobe, #80 Docker LAN)
 **Success Criteria** (what must be TRUE):
   1. A new user on macOS / Windows / Linux follows `docs/install/{macos,windows,linux,docker}.md` end-to-end and reaches a working app (validated by `scripts/validate-install-docs.py` against the actual install script)
   2. User enters an HF token in Settings → API Keys once; the token survives app restart, is forwarded to engine subprocesses, and never appears in any log file or error traceback
   3. When the app raises a known error class (quarantined `.app`, AppImage WebKit white-screen, missing `pkg_resources`, missing HF token, etc.), the error UI shows an "Open docs for this error" button that links to the right `docs/install/*.md` section
   4. README install section is split into per-OS files with templated version badges, no longer inlining 600 lines; `docs/install/troubleshooting.md` covers the top 10 install errors
   5. CosyVoice install guide (`docs/engines/cosyvoice.md`), diarization guide (`docs/features/diarization.md`), and HF token guide (`docs/setup/huggingface-token.md`) exist and are linked from README + error UI
-**Plans:** TBD
+**Plans:** 3 plans (3 waves)
+- [ ] 01-01-PLAN.md — Wave 1 — Token resolver (3-source cascade), encrypted SQLite settings store, logging redactor, subprocess env injection, patch all 5 bare `os.environ.get("HF_TOKEN")` call sites
+- [ ] 01-02-PLAN.md — Wave 2 — Docs scaffolding (split README + 8 docs files), `scripts/validate-install-docs.py` CI gate, error→docs deeplink map (Python + TS), ErrorBoundary wiring, Settings → API Keys panel UI
+- [ ] 01-03-PLAN.md — Wave 3 — AppRun strategy spike + AppImage WebKit conditional launcher, .deb ffprobe relocation + postinst cleanup (#76), centralized `apiBase.ts` + Docker LAN fix (#80), macOS Gatekeeper detection probe
 **UI hint:** yes
 
 ### Phase 2: Engine Isolation (SubprocessBackend → IndexTTS + WAV-export dubbing fix)
@@ -150,7 +153,7 @@ All 11 open GitHub issues are closed or have a documented workaround surfaced in
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
 | 0. Gates | 0/0 | Not started | - |
-| 1. Install + Token + Docs + Error UX | 0/0 | Not started | - |
+| 1. Install + Token + Docs + Error UX | 0/3 | Planned | - |
 | 2. Engine Isolation | 0/0 | Not started | - |
 | 3. Supertonic-3 + Mirror Reliability | 0/0 | Not started | - |
 | 4. Adaptive & Specialty Engines (spike-first) | 0/0 | Not started | - |
@@ -161,20 +164,20 @@ All 11 open GitHub issues are closed or have a documented workaround surfaced in
 
 ## Coverage Summary
 
-**v1 requirements mapped:** 62 / 62 ✓
+**v1 requirements mapped:** 74 / 74 ✓ (updated 2026-05-18 — Phase 1 row corrected per checker B-3 to include INST-12 + AUTH-06; total now matches REQUIREMENTS.md 74)
 **Orphaned requirements:** 0 ✓
 **Duplicates:** 0 ✓
 
 | Phase | Requirement Count | Requirement IDs |
 |-------|-------------------|-----------------|
 | Phase 0 | 6 | GATE-01 — GATE-06 |
-| Phase 1 | 16 | INST-01 — INST-06, DOCS-01 — DOCS-05, AUTH-01 — AUTH-05 |
+| Phase 1 | 18 | INST-01 — INST-06, INST-12, DOCS-01 — DOCS-05, AUTH-01 — AUTH-06 |
 | Phase 2 | 8 | ENGINE-01 — ENGINE-07, BUG-01 |
 | Phase 3 | 11 | TTS-01 — TTS-06, INST-07 — INST-11 |
 | Phase 4 | 13 | SPIKE-01 — SPIKE-02, GGUF-01 — GGUF-06, SING-01 — SING-05 |
 | Phase 5 | 12 | REPORT-01 — REPORT-12 |
 | Phase 6 | 6 | REL-01 — REL-06 |
-| **Total** | **62** | — |
+| **Total** | **74** | — |
 
 ---
 

.planning/STATE.md

@@ -1,6 +1,6 @@
 # STATE: OmniVoice Studio v0.3.x Stabilization
 
-**Last updated:** 2026-05-18 — Completed quick task 260518-lp7: hide dictation pill widget when idle
+**Last updated:** 2026-05-18 — Phase 1 planned (3 plans, 3 waves); ready for execute
 
 ---
 
@@ -10,17 +10,17 @@
 
 **Milestone:** v0.3.x stabilization — "Empty the inbox" (close all 11 open GitHub issues) plus two surgical additions (Supertonic-3 engine, opt-in bug reporting) plus two spike-first model additions (`Serveurperso/OmniVoice-GGUF` hardware-adaptive default, `ModelsLab/omnivoice-singing` for the dubbing pipeline).
 
-**Current focus:** Roadmap defined (7 phases, 62 v1 requirements). Awaiting `/gsd:plan-phase 0` to decompose Phase 0 (Gates) into executable plans.
+**Current focus:** Phase 1 planned. Three plans cover all 16 official Phase 1 requirements plus accepted scope additions (#76 .deb ffprobe, #80 Docker LAN). Ready for `/gsd:execute-phase 1`.
 
 ---
 
 ## Current Position
 
 | Field | Value |
 |-------|-------|
-| Phase | 0 — Gates |
-| Plan | none yet |
-| Status | Roadmap complete (revised to insert Phase 4), planning not started |
+| Phase | 1 — Install + Token Persistence + Docs Scaffolding + Error UX |
+| Plan | 01-01, 01-02, 01-03 (all PLAN.md committed, awaiting execute) |
+| Status | Phase 1 planned, ready for execute |
 | Mode | yolo (autonomous) |
 | Granularity | standard |
 | Project mode | mvp (per phase) |
@@ -29,7 +29,7 @@
 
 ```
 [ ] Phase 0  Gates (hard gate — must merge and be green before any other phase)
-[ ] Phase 1  Install + Token Persistence + Docs Scaffolding + Error UX
+[~] Phase 1  Install + Token Persistence + Docs Scaffolding + Error UX  ← planned (3 plans, 3 waves)
 [ ] Phase 2  Engine Isolation (SubprocessBackend → IndexTTS + WAV-export fix)
 [ ] Phase 3  Supertonic-3 Engine + Installer Mirror Reliability
 [ ] Phase 4  Adaptive & Specialty Engines (spike-first: GGUF + Singing)
@@ -64,17 +64,29 @@
 6. **Bug reporting is opt-in only.** Default-deny allow-list payload, GitHub-Issues prefilled URL only, no PAT / no third-party telemetry endpoint.
 7. **`xattr -cr` (#54) and `WEBKIT_DISABLE_COMPOSITING_MODE=1` (#56) count as closed if documented + surfaced in error UI.** Real fixes are infrastructure-level (signing cert, upstream Tauri bug).
 8. **Mode is `yolo` (autonomous), per-phase mode is `mvp`.** Auto-approve gates as user directed.
+9. **Phase 1 scope locked (2026-05-18):** Three plans cover 17 requirements (INST-01..06, DOCS-01..05, AUTH-01..06) plus two accepted scope additions (#76 .deb ffprobe conflict, #80 Docker LAN frontend). v0.3.0 ships as a single fat release bundling all 7 phases — no incremental v0.3.x tags.
+10. **Phase 1 wave structure (2026-05-18):**
+    - **Wave 1 (Plan 01-01):** Token resolver (3-source cascade) + encrypted SQLite settings store + logging redactor + subprocess env injection + patch all 5 bare `os.environ.get("HF_TOKEN")` call sites. Closes #35 read-side bug.
+    - **Wave 2 (Plan 01-02):** Split README into per-OS docs + 5 new docs + `scripts/validate-install-docs.py` CI gate + error→docs deeplink map (Python + TS halves) + ErrorBoundary deeplink wiring + Settings → API Keys panel UI (consumes Wave 1 resolver state endpoint).
+    - **Wave 3 (Plan 01-03):** AppRun strategy spike + AppImage WebKit conditional launcher (#56) + .deb ffprobe relocation + postinst cleanup (#76) + centralized `apiBase.ts` + Docker LAN frontend fix (#80) + macOS Gatekeeper detection probe + INST-01 no-regression assertion.
+11. **Open Question resolutions for Phase 1 (2026-05-18):**
+    - AppRun location: spike-first (Task 01-03-1) — outcome documented in `.planning/decisions/apprun-strategy.md`
+    - Settings table: AUTH-02 adds via real alembic migration (project already has `alembic.ini` + `backend/migrations/`), not `init_db()` patch
+    - Project repo URL: `backend/core/links.py` reads from `pyproject.toml [project.urls]` + `tauri.conf.json` updater endpoint (single source of truth)
+    - localhost hardcodes: `frontend/src/utils/media.js:20` confirmed as only site; centralized via `apiBase.ts`
+    - First-launch failure UI: backend startup probe emits `GATEKEEPER_QUARANTINE` error class → React ErrorBoundary renders docs deeplink (Tauri itself launches; backend detects)
 
 ### Open TODOs
 
-- Run `/gsd:plan-phase 0` to decompose Phase 0 (Gates) into executable plans.
+- Run `/gsd:execute-phase 1` to execute the 3 Phase 1 plans (Wave 1 → Wave 2 → Wave 3).
+- Run `/gsd:plan-phase 0` to decompose Phase 0 (Gates) into executable plans (Phase 0 is the hard gate; technically should land first, but Phase 1 plans don't block on its execution).
 - Confirm open PRs #51 / #53 / #61 land before Phase 0 finalizes the CI matrix.
-- Resolve Phase 2 / 3 / 5 research questions enumerated in `.planning/research/SUMMARY.md` Open Questions table (note: SUMMARY.md "Phase 4" rows now correspond to this roadmap's Phase 5 — bug reporting — after the insertion).
+- Resolve Phase 2 / 3 / 5 research questions enumerated in `.planning/research/SUMMARY.md` Open Questions table.
 - Schedule Phase 4 research dimension (web-fetch model cards for `Serveurperso/OmniVoice-GGUF` and `ModelsLab/omnivoice-singing`, license + runtime confirmation) before any GGUF/SING code work.
 
 ### Blockers
 
-None.
+None. Phase 1 plans are independent of Phase 0 plan creation (though Phase 0 execution must merge before Phase 1 PRs per Key Decision #2).
 
 ### Quick Tasks Completed
 
@@ -87,14 +99,16 @@ None.
 
 ## Session Continuity
 
-**Last session ended after:** Roadmap revision to insert Phase 4 (Adaptive & Specialty Engines). Files written:
-- `.planning/ROADMAP.md` (revised: 7 phases, new Phase 4 inserted between Supertonic-3 and Bug Reporting)
-- `.planning/REQUIREMENTS.md` (revised: 13 new requirements added, traceability table extended to 62 rows, REPORT-* renumbered to Phase 5, REL-* to Phase 6)
-- `.planning/STATE.md` (this file — updated to 7 phases / 62 requirements)
+**Last session ended after:** Phase 1 planning. Files written:
+- `.planning/phases/01-install-token-persistence-docs-scaffolding-error-ux/01-01-PLAN.md` (Wave 1 — token persistence + read-side fix)
+- `.planning/phases/01-install-token-persistence-docs-scaffolding-error-ux/01-02-PLAN.md` (Wave 2 — docs scaffolding + error UX)
+- `.planning/phases/01-install-token-persistence-docs-scaffolding-error-ux/01-03-PLAN.md` (Wave 3 — installer/bundler fixes)
+- `.planning/ROADMAP.md` (Phase 1 plan list populated, progress 0/3)
+- `.planning/STATE.md` (this file — Phase 1 planned, ready for execute)
 
-**Resume with:** `/gsd:plan-phase 0`
+**Resume with:** `/gsd:execute-phase 1` (or `/gsd:plan-phase 0` to decompose Phase 0 in parallel).
 
 ---
 
 *State initialized: 2026-05-16 after roadmap creation*
-*Last updated: 2026-05-16 after Phase 4 insertion (Adaptive & Specialty Engines)*
+*Last updated: 2026-05-18 after Phase 1 planning (3 plans across 3 waves)*