docs: record capture token schema repair

Author: rohans0509

docs/codealmanac-launch/decisions.md

@@ -115,6 +115,24 @@ Status: active.
   machinery is written.
 - The first overnight execution priority is infrastructure and deployment, so
   the renamed cloud product exists on real providers before deeper feature work.
+- The overnight run has two large halves: first build the CLI/API/frontend/
+  backend product spine until it works together, then deliberately sharpen the
+  codebase organization and naming around the settled product model.
+- Codebase reorganization is in scope after the product spine works. Services,
+  stores, DTOs, API routes, frontend modules, migrations, and package structure
+  may be renamed or moved when the new shape is simpler and more truthful.
+- Code quality is a first-class launch objective. Refactors should be done when
+  they remove split-brain concepts, provider leakage, stale compatibility, or
+  unclear ownership; they should not be done for motion alone.
+- The README should preserve the old README's banner, feel, and core language
+  while updating launch commands and product facts. Do not replace it with a
+  generic marketing README.
+- Public install UX should prefer a curl one-liner backed by the Python/PyPI
+  package path. `uv tool install --python 3.12 codealmanac` remains the explicit
+  manual path.
+- Every coherent chunk must leave a testing record: commands, URLs, provider
+  surfaces, results, deploy/run ids, and any surfaces that could not be tested
+  without user action.
 - Provider CLIs/APIs should be used where available for Vercel, Render,
   Supabase, Modal, Doppler, PostHog, Autumn, and GitHub.
 - CodeAlmanac PyPI publishing uses PyPI Trusted Publishing through GitHub

docs/codealmanac-launch/next-agent-brief.md

@@ -130,6 +130,20 @@ Slice 59 fixes the CLI auth/setup contract:
 - GitHub Actions publish run `28640955934` published `codealmanac` `0.1.1` to
   PyPI, and a fresh PyPI install verified the released CLI
 
+Slice 60 repairs capture-token schema drift in production:
+
+- production repository settings failed because the page called
+  `GET /api/capture/status`, and production Supabase lacked
+  `public.capture_tokens`
+- hosted migration `20260703010000_capture_tokens.sql` creates the table,
+  indexes, grants, forced RLS, and backend policy
+- the clean-slate init migration also includes `capture_tokens`
+- the migration was applied through Doppler-backed `psql` and marked applied in
+  Supabase migration history
+- browser-harness verified signed-in production repository settings now loads
+  and Render logs show fresh `/api/capture/status` `200 OK` entries
+- hosted focused tests and ruff passed for the slice
+
 ## Current Repo State
 
 CodeAlmanac:
@@ -153,8 +167,8 @@ Hosted:
 
 - repo: `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence`
 - branch: `codex/workos-authkit-api-foundation`
-- current Slice 58 commit:
-  `01c84637e082945f22c71e09dfb7216c49c7769d`
+- current Slice 60 working tree has the capture-token migration and schema
+  guard before commit
 - `origin/codex/workos-authkit-api-foundation` and `origin/main` both point at
   `01c84637e082945f22c71e09dfb7216c49c7769d`
 - production frontend: `https://www.codealmanac.com`
@@ -233,12 +247,16 @@ repaired.
   succeeded, PyPI JSON/simple index exposed `0.1.1`, and
   `uv tool install --python 3.12 --no-cache codealmanac==0.1.1` installed a
   CLI whose root setup JSON still showed `automation_mode: "none"`.
+- Slice 60 hosted verification passed: production DB has
+  `public.capture_tokens`, Supabase migration history includes
+  `20260703010000`, signed-in production repository settings loads in Chrome,
+  Render logs show fresh `/api/capture/status` `200 OK`, hosted focused tests
+  reported `76 passed`, and hosted ruff passed.
 
 ## Next Pressure Tests
 
-- Continue the real signed-in production browser pass from the verified
-  `/setup` state into repository settings, branch trigger configuration,
-  capture consent, and run visibility.
+- Continue the real signed-in production browser pass from repository settings
+  into branch trigger configuration, capture consent, and run visibility.
 - Add `GITHUB_TOKEN_ENCRYPTION_KEYS` to Doppler `codealmanac/dev_personal` if a
   local signed-in setup walkthrough is needed; the backend currently refuses to
   start without it.

docs/codealmanac-launch/overnight-run-contract.md

@@ -1,14 +1,41 @@
 # Overnight Run Contract
 
 Status: active.
-Date: 2026-07-02.
+Date: 2026-07-03.
 
 This file records the execution order for the long autonomous launch run.
 
+## Operating Authority
+
+This launch has no external customer compatibility constraint. If a database
+shape, migration history, URL, package name, CLI command, frontend route, or
+code organization choice is wrong for the launch product, change it instead of
+protecting it.
+
+Use provider-owned concepts where they exist:
+
+- WorkOS owns human identity, AuthKit sessions, and any WorkOS-backed machine
+  credentials.
+- GitHub owns accounts, installations, repositories, branches, pull requests,
+  commits, and webhook event shapes.
+- Supabase/Postgres owns CodeAlmanac product state, but not identity.
+- Vercel, Render, GitHub Actions, PyPI, Doppler, PostHog, Autumn, and provider
+  CLIs/APIs should be used directly where they are the real control plane.
+
+Do not invent parallel product-owned systems unless a provider gap forces a
+small named adapter.
+
 ## Priority Order
 
-The first major objective is infrastructure and deployment, before deep product
-implementation.
+The run has two large halves:
+
+1. Build the product spine until CLI, API, frontend, backend, and deployables
+   work together.
+2. Sharpen the codebase so it reads like it was designed after the product
+   model became clear.
+
+The first major objective remains infrastructure and deployment, before deep
+product implementation.
 
 Order:
 
@@ -25,6 +52,78 @@ Order:
 The intended wake-up state is: there is something deployed, not only a local
 refactor.
 
+## Product Spine
+
+Finish the concrete product path first:
+
+- root `codealmanac setup` is cloud setup, not local automation setup
+- CLI setup/login use the final WorkOS-backed auth contract through
+  CodeAlmanac API endpoints
+- API exposes the nouns the frontend and CLI actually need
+- hosted repo list, repo setup, repo settings, trigger policy, delivery policy,
+  and runs surfaces work in production
+- GitHub App webhooks create or update parent records before child records
+- PR/merge events on maintained branches create runs
+- delivery defaults to commit and is configurable per maintained branch
+- run records and run events are stored with the same conceptual shape in cloud
+  and local, even when persistence differs
+- CLI, frontend, backend, and migrations are deployed after coherent chunks
+
+## Codebase Sharpening
+
+After the spine works, the run should spend serious time improving code quality.
+This is not cosmetic cleanup. The goal is that a new engineer or agent can read
+the names and infer the product.
+
+Allowed and encouraged:
+
+- reorganize packages and folders around stable product/provider domains
+- rename services, stores, DTOs, routes, and tables to match GitHub, WorkOS, and
+  CodeAlmanac nouns
+- collapse, rewrite, or repair Supabase migrations because launch has no
+  external users
+- remove stale local/cloud split-brain
+- remove compatibility husks once callers have moved
+- simplify DTOs and API names so frontend, CLI, API, and core use the same
+  vocabulary
+- break large files by responsibility
+- introduce a consistent project-wide error/result approach if current error
+  handling is scattered
+- add architecture tests when boundaries become important enough to protect
+- mirror cloud/local concepts only where the parallel is real
+
+Do not refactor for motion. Every reorganization should make one of these true:
+
+- a product noun has one obvious home
+- a provider boundary stops leaking raw provider details
+- a future SDK/API method becomes easier to name
+- a test can enforce an architectural rule
+- deleted code removes a real source of confusion
+
+## README And Install UX
+
+Restore the old README's feel rather than replacing it with a new marketing
+document. Keep the original banner, cadence, and most of the language where it
+still describes the product correctly. Update only the launch facts and command
+surface.
+
+Public install should prefer a product-grade one-liner:
+
+```bash
+curl -fsSL https://codealmanac.com/install.sh | sh
+codealmanac setup
+```
+
+The install script can use `uv tool install` internally. Keep the manual path in
+docs for transparency:
+
+```bash
+uv tool install --python 3.12 codealmanac
+codealmanac setup
+```
+
+Do not reintroduce npm/npx instructions for the Python CLI.
+
 ## Provider CLI Check
 
 Initial local CLI availability:
@@ -113,6 +212,34 @@ local setup/update path works
 Refactors are allowed inside these chunks when they make the chunk fit cleanly.
 Refactors that do not affect the launch path should wait.
 
+## Testing And Evidence
+
+Test as much as possible. Prefer real provider/browser verification at the end
+of coherent chunks, not only unit tests.
+
+Maintain a running testing record in `worklog.md` or `verification-matrix.md`
+with:
+
+- what was tested
+- exact command or provider surface used
+- production or local URL when relevant
+- result
+- commit/deploy/run id when relevant
+- anything not testable without user action
+
+At minimum, keep checking:
+
+- full Python tests and lint for `codealmanac`
+- hosted route/frontend/backend tests where touched
+- browser login/setup/repo/settings flows in production
+- backend health and relevant API endpoints
+- GitHub webhook behavior or replayed webhook payloads
+- PyPI install and `codealmanac setup` smoke after CLI releases
+- Vercel and Render deploy status after provider changes
+
+If blocked, record the block instead of silently skipping the surface. The
+wake-up handoff should say exactly what remains human-testable.
+
 ## Supabase
 
 No external customers are using the product yet. Supabase migrations can be

docs/codealmanac-launch/progress.md

@@ -8,7 +8,7 @@ Percentages are planning estimates, not accounting metrics.
 
 ## Latest RelayForge Update
 
-Sent: 2026-07-03 after Slice 58 AuthKit production schema repair.
+Sent: 2026-07-03 after Slice 60 capture-token schema repair.
 
 Route:
 
@@ -19,22 +19,21 @@ doppler run --project almanac --config dev -- \
   --binding rohan-almanac-main "..."
 ```
 
-Note: rate limits were postponed. PyPI Trusted Publishing is working for
-CodeAlmanac `0.1.0`. Hosted sign-in reached production `/setup` after the
-schema repair, then production identity/data state was intentionally reset for a
-fresh first-login path. The root cause was production Supabase schema drift:
-backend code expected WorkOS-shaped `users` rows, while production still had the
-old Supabase Auth-shaped `users.supabase_user_id` table shape.
+Note: production repository settings now loads. The root cause was a missing
+`public.capture_tokens` table while backend code already queried
+`CaptureTokenRow`. Migration `20260703010000` was applied and marked applied in
+Supabase history. Signed-in Chrome verification reached repository settings, and
+Render logs showed fresh `/api/capture/status` `200 OK`.
 
 ## Percentages
 
 | Area | Latest | Previous | Basis |
 | --- | ---: | ---: | --- |
-| CodeAlmanac backend/local | 96% | 96% | CodeAlmanac local/backend unchanged in Slice 58. |
-| CodeAlmanac CLI/public UX | 98% | 98% | PyPI `0.1.0` remains published and install-smoked; no CLI code changed in Slice 58. |
-| CodeAlmanac-hosted backend/auth/API | 98% | 97% | Production DB now matches the WorkOS/AuthKit identity schema and stores encrypted GitHub access plus refresh tokens. |
-| Hosted frontend/onboarding | 88% | 84% | Signed-in production `/setup` now renders `rohans0509` and connected GitHub accounts after the fixed auth/session write. |
-| Infra/deploy rename | 99% | 98% | Hosted `main` and branch point at the schema-repair commit; Render deployed it live and Vercel remains Ready. |
+| CodeAlmanac backend/local | 96% | 96% | CodeAlmanac local/backend unchanged in Slice 60. |
+| CodeAlmanac CLI/public UX | 98% | 98% | PyPI `0.1.1` remains published and install-smoked; no CLI code changed in Slice 60. |
+| CodeAlmanac-hosted backend/auth/API | 99% | 98% | Production DB now includes capture credential storage and `/api/capture/status` returns 200 for signed-in settings loads. |
+| Hosted frontend/onboarding | 92% | 88% | Signed-in production repository settings now renders readiness, branch, and delivery surfaces. |
+| Infra/deploy rename | 99% | 99% | Production Supabase migration history includes `20260703010000`; Render and Vercel surfaces remain live. |
 
 ## Update Rule
 

docs/codealmanac-launch/verification-matrix.md

@@ -193,6 +193,27 @@ Current evidence:
   `01c8463`, backend health `{"status":"ok"}`, Vercel production Ready, and
   browser-harness signed-in `/setup` rendering `rohans0509`, `ReverieOne`, and
   `AlmanacCode`.
+- Slice 60 repaired capture credential schema drift. The backend already
+  queried `CaptureTokenRow`, but production Supabase lacked
+  `public.capture_tokens`, causing signed-in repository settings to fail at
+  `GET /api/capture/status`.
+- Hosted migration
+  `supabase/migrations/20260703010000_capture_tokens.sql` creates
+  `public.capture_tokens`, grants service-role access, enables forced RLS, and
+  creates `capture_tokens_backend_access`.
+- The clean-slate init migration now includes `capture_tokens`, so fresh
+  environments and repaired production use the same table shape.
+- Production DB verification proved `to_regclass('public.capture_tokens')`
+  resolves and `pg_policies` includes `capture_tokens_backend_access` for
+  `{postgres,service_role}`.
+- Browser-harness verified signed-in production repository settings loads at
+  `/dashboard/accounts/264516179/repositories/1212149375/settings` and renders
+  GitHub access, capture status, maintained branches, and delivery settings.
+- Render logs after the repair show fresh signed-in
+  `GET /api/capture/status` requests returning `200 OK`.
+- Slice 60 hosted verification passed:
+  `uv run pytest tests/test_architecture_contract.py tests/test_capture_tokens_api_contract.py`
+  (`76 passed, 1 warning`) and `uv run ruff check .`.
 
 ## CodeAlmanac Local Repo
 

docs/codealmanac-launch/worklog.md

@@ -1641,3 +1641,29 @@
   `UV_TOOL_DIR=<tmp> UV_TOOL_BIN_DIR=<tmp> uv tool install --python 3.12 --no-cache codealmanac==0.1.1`;
   the installed executable returned `0.1.1`, and installed setup JSON showed
   `automation_mode: "none"` with `automation: []`.
+- Repaired production repository settings after the page failed at
+  `/api/capture/status`.
+- Root cause: backend code already had `CaptureTokenRow` and
+  `CaptureTokensStore.active_for_user()`, but production Supabase did not have
+  `public.capture_tokens`.
+- Added hosted migration
+  `supabase/migrations/20260703010000_capture_tokens.sql` and added
+  `capture_tokens` to the clean-slate init schema.
+- Applied the migration to production through Doppler-backed `psql`, then
+  marked migration `20260703010000` as applied with
+  `supabase migration repair --linked --status applied 20260703010000`.
+- Verified production DB has `public.capture_tokens` and policy
+  `capture_tokens_backend_access` for `{postgres,service_role}`.
+- Verified unauthenticated `GET https://api.codealmanac.com/api/capture/status`
+  returns `401 not_authenticated`, not a server error.
+- Verified signed-in Chrome production settings page loads:
+  `https://www.codealmanac.com/dashboard/accounts/264516179/repositories/1212149375/settings`.
+- Verified page text shows repository readiness, GitHub App connected, write
+  repository access, capture not installed, maintained branches, and delivery
+  settings.
+- Verified Render logs after the fix include fresh
+  `GET /api/capture/status HTTP/1.1" 200 OK` entries at
+  `2026-07-03T06:47:13Z`, `06:47:16Z`, and `06:47:33Z`.
+- Hosted tests for the repair passed:
+  `uv run pytest tests/test_architecture_contract.py tests/test_capture_tokens_api_contract.py`
+  (`76 passed, 1 warning`) and `uv run ruff check .`.