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.
13. Before beginning implementation, tell the user whether the proposed change
   is likely deliverable through an Expo OTA update, likely requires a new
   native/store build, or has no applicable OTA path, with a brief reason. If
   uncertain, state that uncertainty and name the validation needed.

## 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.