V1 Operational Runbooks

The V1 product’s operational runbooks live in the memberintel repo at docs/runbooks/, not in this KB. They’re command-heavy and tied tightly to the V1 source code — auto-syncing them here would invite drift between what the runbook says and what the code does. (We learned this in May 2026: doc-first drafting against shipped code consistently produced inaccuracies that reviewers caught later.)

This page exists as a breadcrumb. If you’re on call, take a handoff, or are trying to ship a fix to V1, start in the memberintel repo, not here.

Why these exist

Bus-factor coverage. As of May 2026, Seth is the only person who has operated V1 end-to-end. The runbooks codify what he knows so that a competent engineer who doesn’t know this codebase can take over deploys, debug auth, inspect the customer brain, or run an incident.

Audience: Python / FastAPI / Cloud Run literate, but does not already know V1. Each runbook is command-first and ends with a “Things that have bitten Seth before” section so institutional knowledge doesn’t walk out the door.

The runbooks

Runbook	Covers	When to read
01-deploy.md	Backend (Cloud Run via deploy.yml), SPA (app.membersintel.com), marketing (membersintel.com), WP plugin. Rollback as a top-level operation, secret rotation procedure, migration application.	”I need to ship a change” or “I need to roll back”
02-auth.md	JWT, Google OAuth, SSO from marketing site. Endpoint table, end-to-end smoke test, six common failure modes with fixes.	”Login is broken / a user can’t log in / SSO is weird”
03-customer-brain.md	SOUL/BIBLE/HEARTBEAT/MEMORY inspection, reset, memory-cap checks. Failure modes including the streaming-vs-non-streaming tool_result gap.	”The AI doesn’t remember things / BIBLE looks wrong”
04-incident-response.md	Meta-runbook. Severity ladder, first-five-minutes triage, where-to-look table, six specific playbooks, postmortem template.	”Prod is on fire — where do I start?”
README	Index, conventions, “where things live” cross-reference.	First time reading the runbooks.

A fifth runbook covering one-time GCP setup lives separately at docs/deploy/gcp-setup-runbook.md — read only if standing up infrastructure from scratch.

Related decisions

The runbooks reference these ADRs (synced into this KB under the decision section):

• ADR-0007: Auth via JWT + Google OAuth + AI Foundation PKCE — backs 02-auth.md
• ADR-0015: Customer brain four-document architecture — backs 03-customer-brain.md
• ADR-0016: Brain mutation via Anthropic tool calls — backs 03-customer-brain.md
• ADR-0017: MemberIntel Connect WordPress plugin as data source — backs the sync sections in 01-deploy.md and 03-customer-brain.md
• ADR-0018: Brain memory limits and content sanitization — backs the memory-cap and sanitization sections in 03-customer-brain.md

Planned additions

The May 2026 first-batch covered the four most-load-bearing surfaces. Follow-ups, in priority order:

1. Secrets rotation deep-dive (currently a section of 01-deploy.md, deserves its own runbook)
2. Site-data-sync deep-dive (WP plugin contract, sync service, common failure modes)
3. Stripe billing (when the integration ships)
4. Database / migrations / RLS testing
5. Observability — Cloud Logging, OTEL, BigQuery (per ADR-0010)