docs: record authkit production schema repair

Author: rohans0509

docs/codealmanac-launch/auth-api-contract.md

@@ -191,6 +191,61 @@ persist upstream `oauthTokens` from `handleAuth({ onSuccess })` when present.
 This replaces the old Supabase callback behavior where `provider_token` and
 `provider_refresh_token` were sent to the backend.
 
+Docs-backed setup contract:
+
+```text
+browser -> /sign-in
+/sign-in -> AuthKit getSignInUrl()
+AuthKit -> GitHub OAuth provider
+GitHub -> WorkOS GitHub OAuth Redirect URI
+WorkOS -> /auth/callback
+/auth/callback -> handleAuth({ onSuccess })
+onSuccess -> send WorkOS accessToken + GitHub oauthTokens to backend
+backend -> verify WorkOS AuthKit access token, then store GitHub token pair
+```
+
+The frontend should use WorkOS' standard Next.js SDK helpers:
+
+```text
+getSignInUrl() in the sign-in route
+handleAuth() in the callback route
+AuthKitProvider in the app layout
+authkitProxy/authkit middleware or proxy for session handling
+```
+
+Do not hand-roll the OAuth callback, state verifier, or PKCE cookie. If the
+provider setup is correct, the callback should be boring.
+
+The backend should verify the WorkOS/AuthKit bearer as an AuthKit session token:
+
+```text
+verify JWT signature against WorkOS JWKS
+require normal session claims such as subject, issuer, issued-at, and expiry
+accept the WorkOS/AuthKit issuer shape used by the SDK/runtime
+do not require GitHub oauthTokens to be embedded in the WorkOS access token
+do not require a non-documented `client_id` claim as a hard auth condition
+reject wrong client_id if WorkOS includes one
+```
+
+GitHub provider tokens are not the browser session. They are upstream provider
+tokens returned during the AuthKit callback and stored only after the WorkOS
+session bearer verifies.
+
+Production schema drift note from Slice 58:
+
+```text
+symptom: /login?error=github_required after GitHub OAuth
+actual failing hop: POST /api/auth/github-app/session
+root cause: production users table still had supabase_user_id
+fix: repair production DB to workos_user_id plus encrypted token columns
+tracking migration: 20260703000000_repair_workos_identity_schema.sql
+```
+
+If sign-in fails after WorkOS/GitHub redirects have succeeded, check backend
+logs and the production `users` schema before adding AuthKit retry machinery.
+The simplest correct path is the documented SDK callback plus a matching
+database schema.
+
 Default GitHub OAuth scope:
 
 ```text
@@ -208,6 +263,67 @@ Repository reads, writes, PRs, branch checks, and delivery should use GitHub App
 installation tokens and GitHub App permissions. Add user OAuth scopes only for a
 specific user-on-behalf-of-user feature that cannot be served by the GitHub App.
 
+When using a GitHub App as the WorkOS GitHub OAuth credential, GitHub App user
+access tokens do not use OAuth scopes in the classic OAuth App sense. They are
+bounded by the intersection of the GitHub App permissions and the user's own
+permissions. Keep the WorkOS scope field simple unless a concrete user-token
+feature requires more.
+
+GitHub App optional feature:
+
+```text
+User-to-server token expiration: enabled
+```
+
+Reason:
+
+```text
+GitHub returns ghu_ access tokens that expire after 8 hours and ghr_ refresh
+tokens that can refresh them. CodeAlmanac needs the refresh token path for
+stable user-linked GitHub identity and repository visibility.
+```
+
+GitHub App installation OAuth prompt:
+
+```text
+Request user authorization during installation: off by default
+```
+
+Reason:
+
+```text
+The normal user identity path is WorkOS/AuthKit sign-in. Installation is the
+repo permission path. If we enable OAuth during installation, GitHub starts a
+separate web application flow and chooses the first app callback unless the full
+flow controls redirect_uri. Keep identity and installation separate unless we
+intentionally redesign onboarding around installation-first auth.
+```
+
+Provider config that should stay simple:
+
+```text
+WorkOS GitHub provider enabled
+WorkOS GitHub provider uses GitHub App client id and client secret
+Return GitHub OAuth tokens enabled
+scope user:email
+GitHub App callback URL is the WorkOS GitHub OAuth Redirect URI
+GitHub App setup URL is https://www.codealmanac.com/setup
+GitHub App webhook URL is https://api.codealmanac.com/api/webhooks/github
+```
+
+Production environment contract:
+
+```text
+WORKOS_API_KEY
+WORKOS_CLIENT_ID
+WORKOS_COOKIE_PASSWORD
+NEXT_PUBLIC_WORKOS_REDIRECT_URI
+```
+
+`WORKOS_COOKIE_PASSWORD` must be at least 32 characters because the AuthKit
+Next.js SDK uses it to encrypt the session cookie. An empty value is a broken
+deployment even when the WorkOS and GitHub dashboards are otherwise correct.
+
 Empirical check on 2026-07-02 against `codealmanac/prd`: after refreshing the
 stored GitHub App user token for `rohans0509`, GitHub returned an empty
 `X-OAuth-Scopes` header and still allowed:

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

@@ -1,7 +1,7 @@
 # Next Agent Brief
 
 Status: active.
-Updated: 2026-07-02.
+Updated: 2026-07-03.
 
 ## Current Hypothesis
 
@@ -98,30 +98,48 @@ Slice 57 hardens GitHub-only hosted sign-in:
   `https://codealmanac-hosted-jaxnxk6oq-thealmanac.vercel.app` is aliased to
   `https://www.codealmanac.com`
 
+Slice 58 repairs production AuthKit schema drift:
+
+- WorkOS/GitHub OAuth was configured correctly; the failing production request
+  was backend persistence after the callback.
+- Production Supabase still had the old Supabase Auth-era `users.supabase_user_id`
+  table shape, while deployed backend code expected `users.workos_user_id` plus
+  encrypted GitHub token columns.
+- Hosted migration
+  `supabase/migrations/20260703000000_repair_workos_identity_schema.sql`
+  records the repair path.
+- Production now has an active `rohans0509` WorkOS user row with encrypted
+  GitHub access and refresh tokens.
+- Hosted commit `01c84637e082945f22c71e09dfb7216c49c7769d` is on hosted
+  `origin/codex/workos-authkit-api-foundation` and hosted `origin/main`.
+- Render deploy `dep-d93h21h9rddc73a2q0g0` is live for commit `01c8463`.
+- Browser-harness verified signed-in production `/setup` with `rohans0509`,
+  `ReverieOne`, and `AlmanacCode`.
+
 ## Current Repo State
 
 CodeAlmanac:
 
 - repo: `/Users/rohan/Desktop/Projects/codealmanac`
 - branch: `dev`
-- current launch-docs commit before Slice 57 docs:
-  `deda8a4faf336b98431d95719978f72719ad88da`
+- current launch-docs commit before Slice 58 docs:
+  `d65392818f6d22f6b963b20259344bcd759b8dd1`
 - `origin/dev` and `origin/main` both point at
-  `deda8a4faf336b98431d95719978f72719ad88da`
+  `d65392818f6d22f6b963b20259344bcd759b8dd1`
 - package version in `pyproject.toml`: `0.1.0`
 - PyPI live version checked on 2026-07-02: `0.1.0`
 
 Hosted:
 
 - repo: `/Users/rohan/.config/superpowers/worktrees/usealmanac/hosted-baseline-convergence`
 - branch: `codex/workos-authkit-api-foundation`
-- current Slice 57 commit:
-  `041deb878edb3931121ad861659dff0568f23b99`
+- current Slice 58 commit:
+  `01c84637e082945f22c71e09dfb7216c49c7769d`
 - `origin/codex/workos-authkit-api-foundation` and `origin/main` both point at
-  `041deb878edb3931121ad861659dff0568f23b99`
+  `01c84637e082945f22c71e09dfb7216c49c7769d`
 - production frontend: `https://www.codealmanac.com`
-- hosted main has the setup/auth hardening, route-test guardrails, and cloud
-  setup checklist through `041deb8`
+- hosted main has setup/auth hardening, route-test guardrails, cloud setup
+  checklist, and production WorkOS identity schema repair through `01c8463`.
 
 The local wiki command currently fails on this checkout with:
 
@@ -180,12 +198,17 @@ repaired.
   `/sign-in` set a `wos-auth-verifier-*` cookie before redirecting to WorkOS,
   browser-harness showed `/login` with `Continue with GitHub` and no inputs,
   and Vercel had no recent error logs.
+- Slice 58 production auth verification passed: focused hosted backend auth
+  tests (`24 passed`), production DB row for `rohans0509` with encrypted access
+  and refresh token ciphertext, Render live deploy `dep-d93h21h9rddc73a2q0g0`,
+  backend health `{"status":"ok"}`, Vercel production Ready, and browser-harness
+  signed-in `/setup` showing `rohans0509`, `ReverieOne`, and `AlmanacCode`.
 
 ## Next Pressure Tests
 
-- Do a real signed-in production browser pass through:
-  `/login` -> GitHub AuthKit -> `/setup` -> GitHub App install/config ->
-  repository settings.
+- Continue the real signed-in production browser pass from the verified
+  `/setup` state into repository settings, 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/progress.md

@@ -1,14 +1,14 @@
 # Launch Progress
 
 Status: active.
-Updated: 2026-07-02.
+Updated: 2026-07-03.
 
 This file tracks the rough percentage estimates used in RelayForge updates.
 Percentages are planning estimates, not accounting metrics.
 
 ## Latest RelayForge Update
 
-Sent: 2026-07-02 after Slice 57 AuthKit sign-in hardening.
+Sent: 2026-07-03 after Slice 58 AuthKit production schema repair.
 
 Route:
 
@@ -20,18 +20,20 @@ doppler run --project almanac --config dev -- \
 ```
 
 Note: rate limits were postponed. PyPI Trusted Publishing is working for
-CodeAlmanac `0.1.0`. Hosted sign-in is now routed through the product login
-page first, with `/sign-in` as the only WorkOS/AuthKit start endpoint.
+CodeAlmanac `0.1.0`. Hosted sign-in now reaches the production `/setup` page
+with GitHub accounts visible. 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.
 
 ## Percentages
 
 | Area | Latest | Previous | Basis |
 | --- | ---: | ---: | --- |
-| CodeAlmanac backend/local | 96% | 96% | CodeAlmanac local/backend unchanged in Slice 57. |
-| CodeAlmanac CLI/public UX | 98% | 98% | PyPI `0.1.0` remains published and install-smoked; no CLI code changed in Slice 57. |
-| CodeAlmanac-hosted backend/auth/API | 97% | 96% | AuthKit callback now rejects non-GitHub-token completions and maps callback errors back to GitHub-only login states. |
-| Hosted frontend/onboarding | 84% | 78% | Public CTAs, protected redirects, login, `/sign-in`, and production `/setup` smoke now follow one GitHub-first setup path. |
-| Infra/deploy rename | 98% | 98% | Vercel production redeployed and aliased after Slice 57; remaining infra work is provider cleanup and signed-in walkthrough coverage. |
+| 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. |
 
 ## Update Rule
 

docs/codealmanac-launch/verification-matrix.md

@@ -172,6 +172,27 @@ Current evidence:
   `codealmanac-hosted-jaxnxk6oq-thealmanac.vercel.app`, production `/setup`
   redirect smoke, production `/sign-in` verifier-cookie smoke,
   browser-harness `/login` smoke, and Vercel error-log check.
+- Slice 58 repaired production Supabase schema drift. Production had old
+  Supabase Auth-era `users.supabase_user_id` and plaintext token columns while
+  the deployed backend expected WorkOS/AuthKit `users.workos_user_id` and
+  encrypted token columns.
+- Hosted migration
+  `supabase/migrations/20260703000000_repair_workos_identity_schema.sql`
+  records the repair path. The migration converts legacy identity columns and
+  foreign keys to WorkOS text ids, adds `oauth_token_ciphertext` and
+  `refresh_token_ciphertext`, removes plaintext token columns, and recreates
+  foreign keys to `users(workos_user_id)`.
+- Production migration history includes `20260703000000` plus the previously
+  drifted launch migrations. The repair was applied through Doppler-backed
+  `psql` because Supabase CLI migration commands hit a pooler
+  prepared-statement conflict.
+- Production DB check proved `rohans0509` has an active WorkOS user row with
+  encrypted GitHub access and refresh tokens present.
+- Slice 58 hosted verification passed: focused backend auth tests
+  (`24 passed`), Render deploy `dep-d93h21h9rddc73a2q0g0` live on commit
+  `01c8463`, backend health `{"status":"ok"}`, Vercel production Ready, and
+  browser-harness signed-in `/setup` rendering `rohans0509`, `ReverieOne`, and
+  `AlmanacCode`.
 
 ## CodeAlmanac Local Repo
 

docs/codealmanac-launch/worklog.md

@@ -2,6 +2,49 @@
 
 ## 2026-07-02
 
+- Planned Slice 58 in
+  `docs/plans/2026-07-02-slice-58-authkit-stale-session-retry.md`. The initial
+  hypothesis was a stale AuthKit session retry problem; production evidence
+  changed the slice into a schema-drift repair.
+- Confirmed the real production auth failure was not WorkOS or GitHub OAuth
+  configuration. WorkOS/GitHub returned tokens, but
+  `POST /api/auth/github-app/session` failed because production Supabase still
+  had the old Supabase Auth-era `users.supabase_user_id` shape while deployed
+  backend code expected `users.workos_user_id` and encrypted token columns.
+- Repaired production Supabase through Doppler-backed `psql` because Supabase
+  CLI migration commands hit the pooler prepared-statement error
+  `prepared statement "lrupsc_1_0" already exists`.
+- Added hosted migration
+  `supabase/migrations/20260703000000_repair_workos_identity_schema.sql`. The
+  migration creates missing launch tables, converts legacy identity foreign keys
+  to WorkOS text ids, drops plaintext GitHub token columns, adds encrypted token
+  columns, and recreates foreign keys to `users(workos_user_id)`.
+- Applied and repaired production migration history for:
+  `launch_security_hardening`, `local_agent_setup_intro`,
+  `hosted_conversation_sync`, `conversation_ingest_scheduler`,
+  `conversation_source_refs`, `encrypt_github_user_tokens`, and
+  `repair_workos_identity_schema`.
+- Verified production DB has `user_01KWJ304254FX8W88S879S8PQG` for
+  `rohans0509`, active, with encrypted GitHub access and refresh token
+  ciphertext present.
+- Verified hosted backend focused auth tests:
+  `uv run pytest tests/test_identity_auth_contract.py tests/test_github_auth_contract.py tests/test_installations_contract.py -q`
+  (`24 passed`).
+- Pushed hosted commit
+  `01c84637e082945f22c71e09dfb7216c49c7769d fix(auth): repair WorkOS identity schema migration`
+  to `origin/codex/workos-authkit-api-foundation` and hosted `origin/main`.
+- Render deployed hosted commit `01c8463` live as deploy
+  `dep-d93h21h9rddc73a2q0g0`. Backend health returned `{"status":"ok"}`.
+- Vercel production remained Ready and aliased to `https://www.codealmanac.com`.
+  No new Vercel deployment was needed for the SQL-only migration commit.
+- Browser-harness verified signed-in production setup after the Render deploy:
+  `https://www.codealmanac.com/setup` rendered `rohans0509`, cloud setup,
+  connected GitHub accounts `ReverieOne` and `AlmanacCode`, and the PyPI-shaped
+  machine setup command.
+- Sent RelayForge update through `rohan-almanac-main` with Slice 58 verification
+  evidence and progress percentages: CodeAlmanac backend/local 96%,
+  CLI/public UX 98%, hosted backend/auth/API 98%, hosted frontend/onboarding
+  88%, infra/deploy rename 99%.
 - Planned Slice 57 in
   `docs/plans/2026-07-02-slice-57-authkit-signin-hardening.md`.
 - Hardened hosted sign-in so `/sign-in` is the only route that starts