Sauci/AGENTS.md

Sauci agent map

Sauci is a couples connection product: an Expo mobile app, React admin, Next.js web app, standalone Node/PostgreSQL backend, hosted Supabase Auth, and an internal MCP service in one npm/Turborepo workspace.

Golden rules

1. Read the nearest AGENTS.md before changing a scoped area.
2. Preserve tenant and couple isolation. Never bypass RLS, role checks, or auth.
3. Product-data schema changes are committed SQL files in apps/api/drizzle/. Hosted Supabase owns Auth only; do not deploy product-data migrations or Edge Functions there. Never execute remote DDL through MCP or provider tools.
4. Never target production from local development or E2E. Database integration tests must fail closed unless DATABASE_URL resolves to loopback. Authenticated native acceptance may use only the designated non-production Auth project.
5. Read apps/mobile/DESIGN.md before mobile UI work.
6. Keep shared package exports type-only and route them through src/index.ts.
7. Do not commit secrets, generated evidence, local logs, or runtime state.
8. Implement in a task-specific git worktree created from current staging, not in the shared staging checkout. After the work is verified, commit the scoped changes, merge the completed task branch back into local staging, push staging, and prove local and remote commit parity.
9. Before merging, identify every deployed app or service the change can affect and prove the relevant compatibility contracts still hold. Preserve deployed interfaces and supported client behavior; repository checks alone do not prove a live change is safe.
10. Delegate every substantive repository task to at least one project agent so detailed exploration or execution stays out of the primary context. "Substantive" includes repository exploration, multi-file reasoning, implementation, test execution, or contract/risk analysis. Use repo_scout for read-only investigation and implementation for bounded changes; use the additional roles according to docs/agents/routing.md. The primary agent retains scope, acceptance, review, and the final answer. Skip delegation only for trivial conversation, a single obvious lookup, or a mechanical one-line edit whose coordination cost exceeds the work.
11. Use high-effort reviewers only for the risk triggers in docs/agents/routing.md.
12. Agents must not use em dash characters in text they add to this repository.

Repository map

Area	Purpose	Local instructions
apps/mobile	Expo React Native product	apps/mobile/AGENTS.md
apps/admin	Vite administration UI	apps/admin/AGENTS.md
apps/web	Next.js marketing/redemption UI	apps/web/AGENTS.md
apps/api	standalone API, worker, PostgreSQL migrations	repository rules
apps/supabase	legacy data-plane history; hosted Auth configuration only	apps/supabase/AGENTS.md
apps/mcp	internal administrative MCP service	apps/mcp/AGENTS.md
packages/shared	shared TypeScript contracts	packages/shared/AGENTS.md
e2e	cross-application Playwright flows	e2e/README.md
docs	maintained system of record	docs/index.md

Workflows

• Implementation: create a task worktree from current staging; commit verified work, merge it back to local staging, push staging, and verify remote parity.
• Bootstrap: npm ci
• Full local stack: scripts/dev-local.sh up
• Fast checks: npm run verify:fast
• Authoritative repository checks: npm run verify:full
• Running-stack E2E: npm run verify:e2e
• Everything: npm run verify
• Before a PR: use .codex/skills/verify/SKILL.md

When a check cannot run because a prerequisite is absent, report it as an environment limitation; do not call it a passing product check.

Where to look

Question	Source of truth
System boundaries and data flow	docs/architecture/system.md
Local services, ports, fixtures	docs/development/local-stack.md
Test layers and required gates	docs/testing/strategy.md
Database migration safety	docs/operations/database-migrations.md
Agent roles and effort routing	docs/agents/routing.md
Learning promotion	docs/agents/learnings.md
Mobile visual language	apps/mobile/DESIGN.md
Domain documentation index	docs/index.md

Documentation discipline

Update the maintained doc when a contract, command, port, or invariant changes. Plans and historical notes are evidence, not current architecture. A repeated lesson becomes permanent only after it is reproduced and promoted into a doc, skill, fixture, or executable check.