Promote staging → main (prod release): 162 commits of unreleased work

[qiuethan]

origin/main (prod) is currently 162 commits behind origin/staging. Everything merged since the doc-visibility / security-review release lives only on staging, including:

• On-behalf-of actor auth (On-behalf-of actor auth: act-as-user + X-On-Behalf-Of (platform_auth) #73) and per-doc visibility grants (Document visibility: per-doc grants (person/team) + actor-scoped enforcement #74)
• /add-email (/add-email: self-service alternate-email identifiers (bot + team-tracking) #75)
• The docs refresh series (PRs feat(bot): promote /doc from beta to stable (global registration) #108–chore: refresh stale docs/config (bot verification, llm .env.example) + gitignore caches #117)
• Meeting recording v2 + the Discord voice DAVE/Opus fix (PRs feat: meeting recording v2 — stateful meeting service + Discord voice surface (live transcription) #119, fix: Discord voice E2EE (DAVE) + service-side Opus decode — makes /record work end-to-end #120)

None of this is tracked by a board item, so the promotion keeps sliding. This issue exists to make it visible.

Scope

• Diff staging vs main and write the release notes / changelog for the promotion
• Enumerate DB migrations that must run against the prod Neon branch, in order
• Enumerate new/changed env vars and secrets each service needs in prod (llm, verification, documentation-system, team-tracking, bot)
• Confirm the doc-visibility feature flag state intended for prod (staging is live; prod is key-ready but the feature was never promoted)
• Verify CI is green on staging immediately before the merge
• Open and merge the staging → main PR
• Post-deploy smoke check on prod: health endpoints, one bot command, one authenticated docs read

Notes

Prod promotion has been deferred through several feature epics. The longer main lags, the larger and riskier a single promotion becomes — worth doing before the content-acquisition (#82) work adds more surface.

[qiuethan]

Promotion audit (2026-07-26)

Worked the checklist against the actual repo + Railway state. Findings below; two items are blockers, one changes the plan.

Divergence is clean

origin/staging is 174 ahead / 3 behind origin/main. The 3 "behind" commits are the empty merge commits from PRs #29, #62, #80 — git diff origin/staging...origin/main is empty, so main is a strict content subset. No cherry-picks or conflict resolution needed. 178 files, +11369/−294.

Migrations to run against prod Neon (in order)

All three API services auto-run alembic upgrade head as a Railway preDeployCommand, so these fire automatically on the merge-to-main deploy — there is no manual gate.

Service	Prod is at	Must apply
team-tracking	005	006_email_provider_multivalued, 007_membership_no_overlap
documentation-system	002	003_doc_grants, 004_docs_url_unique_active
verification	001	none
meeting	—	no DB

⚠️ Two of these mutate live prod data destructively and are not reversible:

• 004_docs_url_unique_active soft-removes (active=false) every duplicate-URL doc row except the earliest, then adds the partial unique index. Its downgrade() drops the index but explicitly leaves the soft-removals in place.
• 007_membership_no_overlap tombstones overlapping memberships by collapsing them to zero-length dateranges (ended_at = started_at, updated_by='migration_007_dedup') before adding the gist EXCLUDE constraint.

Both self-backfill, so they won't fail on dirty data — they'll silently rewrite it. Snapshot / branch both prod Neon DBs before merging.

Env vars + secrets

team-tracking, verification, documentation-system, llm are at full key-parity between staging and production. Real gaps, all meeting-related:

1. The meeting service does not exist in the production Railway environment (staging only — prod has llm, documentation-system, team-tracking, verification, discord-bot). Needs creating: root /, RAILWAY_DOCKERFILE_PATH=services/meeting/Dockerfile, PORT=8003, plus MEETING_ENV=production, API_KEY, CONSUMER_KEYS (a meetings-scoped key for discord-bot), AWS_REGION + Transcribe creds, LLM_BASE_URL, LLM_API_KEY.
2. Prod discord-bot is missing MEETING_BASE_URL and MEETING_API_KEY.
3. Prod llm's CONSUMER_KEYS has only the discord-bot consumer — staging also has a meeting consumer. Minutes generation fails without it.

Also note services/llm/.env.example changed defaults (bedrock → bedrock-converse, claude-sonnet-5 → claude-sonnet-4-6), but both Railway envs already set these explicitly, so no action.

Doc-visibility: there is no feature flag

Checklist item 4 rests on a wrong premise. services/documentation-system/src/config.py has no flag — Settings is just database_url, api_key, directory_base_url, directory_api_key, docs_env. Per-doc visibility in src/api/authz.py is unconditional; it ships live the moment main deploys.

What actually gates behaviour is key scopes, and the semantics changed in a fail-closed direction. In read_context:

• docs:read:all → SEE_ALL
• docs:read with X-On-Behalf-Of → that actor's visibility
• docs:read without the header → DENY (sees nothing)

So if the prod discord-bot doc key carries only docs:read, any /doc path that doesn't pass an actor returns empty rather than everything. The bot does send the header (docClient.js oboHeader, fed from principal?.person?.id in commands/doc.js), but that resolves to undefined for an unlinked user — and prod's directory is sparser than staging's.

Verify before merging (read-only, metadata only):

DATABASE_URL="<prod documentation-system Neon URL>" \
  uv --project services/documentation-system run doc-keys list

Confirm the discord-bot consumer's scopes are what you intend for prod. I did not run this — it needs your prod credentials.

CI

Green on staging — latest run (Merge pull request #130, 30225471217) passed all checks in 44s. Re-verify immediately before the merge.

Post-deploy: command registration is required

Four commands exist on staging but not main: /add-email, /help, /record, /verify-email. They will not appear in Discord until npm run register:production runs, and global registrations take up to ~1h to propagate.

Related: /record is now promoted from beta to stable — PR #131 (into staging). It was the only beta command; the beta partition is now empty. This is exactly why the meeting service must be provisioned in prod before prod command registration, or /record becomes visible in the real UTMIST server and fails on use.

Suggested ordering

1. Merge chore(bot): promote /record from beta to stable #131 → staging; confirm CI green.
2. Snapshot/branch both prod Neon DBs (team-tracking, documentation-system).
3. Verify the prod doc key scopes (command above).
4. Provision the prod meeting service + add the meeting consumer to prod llm + set MEETING_* on the prod bot.
5. Open + merge the staging → main PR. Migrations run automatically on deploy.
6. npm run register:all.
7. Smoke: /health on all six services, /whoami + one authenticated /doc show in the real server, one /record start→stop cycle.

Doc drift worth fixing

docs/RAILWAY-DEPLOYMENT.md still describes a three-service deployment (team-tracking, documentation-system, discord-bot); there are now six. The root README.md was missing /record and the meeting service row entirely — fixed in #131, though the meeting row says "Deployed (staging)" and needs updating once prod is provisioned.

[qiuethan]

Promotion complete — shipped 2026-07-27 01:59 UTC

Merged via PR #132 (merge commit 162e260), 175 commits / 38 PRs.

Checklist status

• Diff staging vs main + release notes — written into Promote staging → main: 175 commits (doc visibility, meeting recording, security fixes) #132; divergence was clean (main's 3 "ahead" commits were empty merge commits, git diff origin/staging...origin/main empty)
• Enumerate DB migrations — all four ran successfully via preDeployCommand, confirmed in prod logs:
  • team-tracking 005 → 006 → 007
  • documentation-system 002 → 003 → 004
  • verification: none. meeting: no DB.
• Enumerate new/changed env vars — team-tracking, verification, documentation-system and llm were already at key-parity; all gaps were meeting-related and are now provisioned (see below)
• Confirm doc-visibility flag state — there is no flag; src/api/authz.py is unconditional and shipped live with this merge. Gating is key scopes (docs:read + X-On-Behalf-Of, or docs:read:all)
• Verify CI green on staging — green at cb2fc83 and again on the Promote staging → main: 175 commits (doc visibility, meeting recording, security fixes) #132 PR run
• Open + merge the staging → main PR
• Post-deploy smoke check — still open, needs a human in Discord (see below)

Prod state after deploy

All six services ● Online, all on merge commit 162e260:

Service	Status
team-tracking	Online, migrated to 007
documentation-system	Online, migrated to 004
verification	Online
llm	Online
meeting	Online, uvicorn on :8003
discord-bot	Online, Bot ready as Misty#9616

Slash commands registered: 11 stable, globally, in both environments; 0 beta. Global registration can take ~1h to propagate through Discord's cache.

New in prod this release

services/meeting is now deployed to production (Railway service 44b3a877…, shared with staging, tracking main), with MEETING_BASE_URL/MEETING_API_KEY wired into the prod bot and a meeting consumer added to prod llm's CONSUMER_KEYS. /record was promoted from beta to stable in #131, so it is now visible in every server the bot is in.

Remaining smoke test

Needs to be done by hand in the real server:

1. /whoami — directory reachable
2. /doc show <id> — the one to watch. Doc visibility is now live and fail-closed: a docs:read key without X-On-Behalf-Of resolves to DENY rather than see-all. The bot does send the header from principal?.person?.id, but that is undefined for an unlinked user. If /doc returns empty for someone who should see results, check the prod bot key's scopes with doc-keys list against the prod documentation-system DB.
3. /record start → stop — end-to-end voice → PDF + audio.

Follow-ups

• docs/RAILWAY-DEPLOYMENT.md still documents a three-service deployment; there are now six.
• Root README.md lists the meeting service as "Deployed (staging)" — it is now staging + prod.