Converting an existing project onto this model

Work top to bottom. Each step is small and independently shippable — do them as separate PRs where it makes sense (dogfood the small-PR rule).

1. Adopt the conventions

• Copy AGENTS.md to the repo root; stamp the playbook commit it came from.
• Add a one-line CLAUDE.md: See AGENTS.md.
• Set the DEPLOY CLASS / DEPLOY TARGET header for this project.
• (Optional) add a Cursor rules stub pointing at AGENTS.md.

2. Repo hygiene

• .gitignore covers node_modules, .next, .env, local platform dirs (.vercel, etc.).
• .env is not committed; .env.example is (keys only, no values).
• Commit the lockfile if it isn't already — CI's npm ci needs it. (Common miss: a lockfile that's never been added.)
• Move any hard-coded secrets out of code and history into the platform's env store. If a secret was ever committed, rotate it.

3. Dependencies

• Bump to latest stable. Framework majors go in their own PR, verified green (typecheck + build + tests). Document any major you deliberately hold back, and why.

4. Gates + branch protection

• Copy ci/gates.yml into .github/workflows/; adjust the script names to match the project (typecheck, lint, validate:content, build).
• Protect main: no direct pushes, require the gates to pass, require one review, require the branch up to date before merge.

5. Previews

• Turn on per-PR preview deployments for the deploy target.
• Keep preview env vars separate from production — never expose prod secrets to a preview.

6. Deploy pipeline (by class)

Container-image:

• Add a Dockerfile; set output: 'standalone'; add a /health route.
• Copy ci/deploy-image.yml; wire registry auth (the host needs a pull PAT).
• Move Postgres/Redis/flags to separate resources.

Managed-source:

• Pin the framework preset/adapter explicitly.
• Add source/dependency scanning to CI (npm audit / dependency review / trivy fs) — this replaces image scanning.
• Set env vars in the platform dashboard for Production and Preview.

7. Verify

• Open a throwaway PR: confirm the gates run, a preview URL appears, and a red check blocks merge. Then you're on the model.