Owner-managed repo. Telegraph. Min tokens.

## Memory
- durable prefs/rules/notes to `~/agents-database`
- do not rely on Codex-only local state as source of truth

## Git / Deploy
- default branch: `main`
- this repo auto-deploys to Vercel
- for every change, start from a fresh branch created from up-to-date `origin/main`
- do not block local commits on working branches; commit freely when the work is coherent
- do not push directly to `main` unless the user explicitly asks for it
- protect `main` from direct changes: no direct push and no merge without explicit user confirmation
- treat this as near-future client production

## Workflow
- safe by default: check `git status/diff` first
- prefer end-to-end verify before handoff
- for Playwright/e2e, prefer a stable app-like server path over dev-only watcher flows when either can satisfy the test objective; keep the repo default framed as the most repeatable cross-machine setup, not a workaround for one host
- when a working branch is considered done/ready, open a PR automatically; do not ask the user for permission
- when user asks for handoff to another agent, leave clean repo state first: docs, tests, and code aligned across whole repo; no half-done, incomplete, stale, or misleading leftovers
- keep `PLAN.md` as the source of truth for current repo state and executive summary of next implementation direction
- every meaningful change must have its plan and progress documented in repo so work is visible and resumable
- do not create or rely on a repo-local task system here; durable task tracking lives in Sebas's global task system outside this repo
- inside this repo, use `PLAN.md` for concise current-state reporting and use focused docs under `docs/` for implementation notes or design material only
- when implementation changes ship, update `PLAN.md` in the same work
- seeded demo/e2e fixtures used by operator flows should stay valid across normal near-future local runs; avoid near-term hard-coded expiry windows unless the task explicitly tests expiry behavior
- Prisma workflow is migration-first. Never use `prisma db push` for normal repo work.
- `pnpm dev` always uses local Postgres and prepares it with `db:local:up`, `db:deploy`, and `db:generate` before starting Next dev
- when realistic local data matters, refresh local DB from production with `CLONE_LOCAL_DB_CONFIRM=1 pnpm db:clone-prod-to-local`
- approved local schema flow:
  - start `pnpm dev`
  - edit `prisma/schema.prisma`
  - run `pnpm db:migrate --name <slug>` from another terminal while local dev is running
  - commit `prisma/schema.prisma`, `prisma/migrations/**`, and `prisma/migration_lock.toml` when changed
- if `prisma/schema.prisma` changes, the staged diff must also include a migration; pre-commit enforces this
- `dangerously-sync-without-migration` is escape hatch only for throwaway work with explicit env opt-in
- Prisma migrate/deploy/status wrappers must reject non-local `DATABASE_URL` by default; remote use needs explicit opt-in
- CI and main pre-push must run Prisma migration checks; schema validation always and DB status when a safe local/CI DB is available
- push to `main` also triggers a GitHub Actions production migration job that runs `pnpm db:deploy` against production before relying on the new app code
- subsystem docs under `docs/` must describe only what is already implemented; no future promises there
- whenever code changes materially affect behavior or architecture, update both `PLAN.md` and the relevant implemented docs in the same work
- push working-branch progress frequently to improve team communication and resumability, but keep commits coherent
- before proposing or building a demo-oriented feature, read `docs/demo-iteration-mode.md` and follow its L1/L2/L3 delivery model and anti-debt guardrails
- use `docs/index.md` as the docs entrypoint to find current discovery/implementation context before deciding scope
- use `docs/repo-map.md` to find the right app/lib/components entrypoints before editing
- for sports/classes demo wedges, check `docs/coaches-solution-thesis.md` and `docs/classes-subroute-plan.md` first, then keep docs aligned with shipped behavior

## Android APK Versioning
- for Ballbox-distributed Android APKs under `android/`, bump app version on every new delivered build
- current convention for `android/machine-ads-sync` is sequential patch bumps: `0.1.5` -> `0.1.6` -> ...
- keep `versionCode` strictly increasing with the delivered APK version
- when handing off a requested APK build, include the versioned filename in the exported artifact when practical, e.g. `ballbox-machine-ads-sync-v0.1.6.apk`

## Founder Role
- founder is available here mainly to unblock business-logic and product-decision questions
- default: keep moving without asking unless one of those decisions materially changes direction
- when blocked on product/business choice, ask here concisely with the current recommendation first