chore(harness): make repository agent-ready

Add concise routed context, task-aware agent roles, focused skills, and structured learning promotion.\n\nUnify local development and workspace tooling, add layered test and E2E verification, harden MCP authentication, and gate deployment behind verification and explicit production promotion.

docs/agents/learnings.md

@@ -0,0 +1,19 @@
+# Learning promotion
+
+Raw activity is not durable guidance. A lesson becomes agent context only after a
+reproducible observation is reviewed and promoted.
+
+## Lifecycle
+
+1. Record a structured observation in `.agents/learnings/inbox/`.
+2. Include symptom, reproduction, cause, remediation, evidence, and scope.
+3. `npm run learn:check` validates the record.
+4. A reviewer promotes it into exactly one maintained surface: documentation,
+   skill, test fixture, invariant lint, or scoped `AGENTS.md` rule.
+5. Move it to `.agents/learnings/promoted/` and include its destination.
+
+Do not promote speculation, transient provider failures, or one-off workarounds.
+Prefer executable enforcement over prose. Review guidance on its expiry date.
+
+`.ralph/runs` and activity logs are historical evidence and are not loaded into
+normal task context.

docs/agents/routing.md

@@ -0,0 +1,21 @@
+# Agent routing and effort
+
+Use one implementation agent by default. Add independent agents only when work is
+actually separable or a risk trigger requires independent judgment.
+
+| Role | Default effort | Trigger | Do not use for |
+|---|---|---|---|
+| `repo-scout` | low | locate ownership, callers, contracts | editing or design decisions |
+| `implementation` | medium | bounded product or harness change | broad architecture review |
+| `test-writer` | medium | focused regression or missing contract test | rubber-stamping green output |
+| `verifier` | medium | independently drive changed behavior | editing implementation |
+| `database-reviewer` | medium | migrations, RLS, function/query boundaries | ordinary UI changes |
+| `security-reviewer` | high | auth, RLS, crypto, secrets, payments, destructive operations | every routine change |
+| `architecture-reviewer` | high | cross-cutting or hard-to-reverse decisions | local refactors |
+
+Escalate effort only when uncertainty, blast radius, or irreversibility justifies
+it. “Proactively use” is not a trigger. Verification agents return evidence and a
+verdict; they do not make changes.
+
+Procedures belong in skills. Agents read the applicable skill and nearest
+`AGENTS.md`, then operate within the task's authorization.

docs/architecture/system.md

@@ -0,0 +1,35 @@
+# System architecture
+
+Sauci is an npm workspace coordinated by Turborepo.
+
+| Component | Technology | Responsibility |
+|---|---|---|
+| Mobile | Expo / React Native / Expo Router | primary customer product |
+| Admin | Vite / React | content and administrative operations |
+| Web | Next.js App Router | marketing, policies, redemption |
+| Backend | Supabase Postgres/Auth/Realtime/Edge Functions | identity, data, workflows |
+| MCP | Hono / MCP SDK | authenticated internal administrative tools |
+| Shared | TypeScript types | cross-application contracts only |
+
+## Trust boundaries
+
+- Mobile and web use public Supabase credentials and depend on RLS.
+- Administrative access requires both an authenticated identity and role checks.
+- Service-role edge functions authenticate and authorize callers before user-data
+  operations.
+- MCP has privileged access and requires `SAUCI_MCP_API_KEY`; absent credentials
+  must never make a non-local deployment public.
+- Local verification uses local Supabase, never a remote project.
+
+## Product flow
+
+Two profiles join a couple, answer questions independently, and the
+`submit-response` edge function creates a match when answers are compatible.
+Realtime subscriptions surface matches and chat messages to the partner.
+
+## Change boundaries
+
+- Database shape: migration plus generated/shared types plus affected clients.
+- Edge function contract: function tests plus calling UI/store behavior.
+- Shared contract: update every consumer in the same change.
+- UI flow: component/unit coverage and observable E2E evidence.

docs/development/local-stack.md

@@ -0,0 +1,30 @@
+# Local full-stack development
+
+Use `scripts/dev-local.sh`; do not start a mixture of local and production-backed
+services manually.
+
+| Service | Owner | Port |
+|---|---|---:|
+| Supabase API / functions | Supabase CLI | 54321 |
+| Supabase database | Supabase CLI | 54322 |
+| Supabase Studio | Supabase CLI | 54323 |
+| Web | Next.js | 3000 |
+| Admin | Vite | 3001 |
+| MCP | Hono | 3002 |
+| Expo Metro | Expo | 8081 |
+
+## First run
+
+1. Use Node from `.nvmrc` and run `npm ci`.
+2. Install Docker Desktop or Rancher Desktop, tmux, and the Supabase CLI.
+3. Copy committed environment examples. Local helpers derive local Supabase
+   values; they never print or overwrite production credentials.
+4. Run `scripts/dev-local.sh reset` to apply migrations and create E2E fixtures.
+5. Run `scripts/dev-local.sh up`.
+
+`up` is idempotent. `down` stops tmux services and leaves Supabase available;
+`down --all` also stops Supabase. Use `status`, `logs <service>`, `restart
+<service>`, and `attach` for diagnosis.
+
+The Expo window defaults to Metro. Use `scripts/dev-local.sh ios` or `android` to
+launch the native app against the same backend.

docs/index.md

@@ -0,0 +1,36 @@
+# Sauci documentation
+
+This index separates maintained operational truth from implementation plans and
+historical notes. Agents should load only the section relevant to their task.
+
+## Maintained system documentation
+
+- [System architecture](architecture/system.md)
+- [Local full-stack development](development/local-stack.md)
+- [Testing strategy](testing/strategy.md)
+- [Database migration safety](operations/database-migrations.md)
+- [Agent routing and effort](agents/routing.md)
+- [Learning promotion](agents/learnings.md)
+- [Authentication](authentication.md)
+- [Database schema](schema.md)
+- [Couple pairing](couple-pairing.md)
+- [Question selection](question-selection.md)
+- [Match notifications](match-notifications.md)
+- [Subscriptions](subscription-system.md)
+- [Redemption codes](product/redemption.md)
+- [Mobile release process](releasing.md)
+
+## Feature and implementation references
+
+These contain useful history and acceptance details, but may describe planned or
+partially implemented states. Confirm claims against current code.
+
+- `admin-question-types-plan.md`
+- `content-balance-implementation.md`
+- `dares-feature.md`
+- `live-draw-feature-plan.md`
+- `NEW_QUESTION_TYPES.md`
+- `oversized-file-inventory.md`
+- `pack-icons-admin-first.md`
+- `data-retrieval-tasks.md`
+- `release-notes.md`

docs/operations/database-migrations.md

@@ -0,0 +1,22 @@
+# Database migration safety
+
+All schema changes are versioned local files under `apps/supabase/migrations/`.
+
+## Required workflow
+
+1. `npm run db:migration:new -- <descriptive_name>`
+2. Edit the generated local migration.
+3. Prefer idempotent SQL where semantics permit it.
+4. `npm run db:reset` against local Supabase.
+5. Run `npm run test:supabase` and affected application checks.
+6. Commit the migration with dependent code and types.
+
+## Forbidden paths
+
+- Never call a remote `apply_migration` MCP tool.
+- Never execute DDL through MCP SQL execution.
+- MCP SQL execution is read-only `SELECT` use only.
+- Never insert migration history manually except an explicitly approved repair.
+- Never hardcode a production URL in a migration or cron definition.
+
+CI deploys committed migrations. Local verification must not link a remote project.

docs/product/redemption.md

@@ -0,0 +1,12 @@
+# Redemption codes
+
+Promotional codes are redeemed only through `apps/web/app/redeem/page.tsx`.
+Do not add redemption UI or a redemption call to the mobile app: mobile premium
+access is governed by the platform purchase/RevenueCat flow.
+
+The public web form calls `redeem-code`, which delegates the atomic validation and
+grant to `redeem_code_by_email`. The database boundary validates active state,
+expiry, remaining uses, and prior redemption before changing premium status.
+
+Changes require web E2E coverage for validation and success/error states plus a
+Supabase integration assertion for the resulting profile and redemption record.

docs/testing/strategy.md

@@ -0,0 +1,28 @@
+# Testing strategy
+
+Verification is layered so quick feedback stays cheap while user-facing behavior
+is proved through the real stack.
+
+## Gates
+
+- `verify:fast`: invariant lint, workspace lint/typecheck, and unit tests.
+- `verify:full`: fast gate plus builds and local Supabase function tests when the
+  required local tools are present.
+- `verify:e2e`: Playwright browser flows and native Maestro flows against an
+  already-running local stack.
+- `verify`: full plus E2E; this is the pre-PR target.
+
+CI runs deterministic checks on every pull request. Running-stack tests use a
+separate job because they require Docker/Supabase and produce traces,
+screenshots, and videos as artifacts.
+
+## Test ownership
+
+- Unit/component tests live with their workspace.
+- Supabase function integration tests live in `apps/supabase/tests`.
+- Cross-application browser tests live in `e2e`.
+- Native black-box flows live in `e2e/maestro`.
+
+E2E must use local or sandbox endpoints. Tests refuse non-local Supabase URLs.
+Authentication is proved once through the public flow; reusable fixture sessions
+avoid repeating auth in unrelated scenarios.