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. The Sol primary agent owns scope, risk classification, acceptance criteria, progress steering, final diff and evidence review, and the final answer. Delegate every substantive repository task to a project agent. Each substantive implementation must use one Terra implementation agent as a coherent execution unit, normally combining scoped discovery, implementation, focused tests, and iteration. "Substantive" includes repository exploration, multi-file reasoning, implementation, test execution, or contract/risk analysis. Add a repo_scout, reviewer, or verifier only for separable work or the triggers in docs/agents/routing.md; do not duplicate the implementation agent's detailed exploration or checks without a concrete reason. 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
Dependency and lockfile discipline	docs/development/dependencies.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. When question interaction types, response payloads, configuration, or match semantics change, update docs/question-types.md in the same change and run npm run lint:harness to prove its type list matches the shared contract. 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.