deckhearth/.cursor/rules/no-go-zones.mdc

---
description: Files and directories agents must not edit, and should not use as context examples
alwaysApply: true
---

# No-go zones

Do not edit, refactor, or quote as context examples. If you think you need to change one of these, stop and ask.

## Generated / vendored

- `node_modules/` — generated dependency tree
- `.next/` — Next.js build output
- `.vercel/` — Vercel CLI local config + build cache
- `out/`, `build/` — build outputs if present

## Append-only / historical

- `components/Layout.js.backup` — legacy snapshot; delete with a real PR, never edit
- `scripts/add-*.js`, `scripts/fix-*.js`, `scripts/seed-*.js` — historical migration / seed jobs already executed. Write a NEW dated script (or a real migration) for further schema changes; never edit ones that already ran.

## Secrets / credentials

- `.env`, `.env.local`, `.env.development.local`, `.env.test.local`, `.env.production.local`
- Anything matching `.env*.local`
- Never commit `JWT_SECRET`, `POSTGRES_URL`, `RESEND_API_KEY`, `BLOB_READ_WRITE_TOKEN`, `GEMINI_API_KEY`, OpenAI/Anthropic keys.

## Local-only / per-developer

- `.code-review-graph/` — local MCP graph index (only if `user-code-review-graph` is installed)
- `.convoys/.metrics.jsonl` — per-developer convoy analytics (gitignored by default)

## Editing rules of thumb

- **Schema changes:** until a proper migration tool lands, document the change in a new dated script under `scripts/migrations/YYYY-MM-DD-<slug>.js` (folder TBD). Do NOT edit `scripts/setup-neon-db.js` in place for any **DDL change** (`CREATE TABLE`, `ALTER`, new columns, constraint changes) — it's idempotent and meant for first-time setup only. **Operational changes are allowed** (env-var gating, error-message hardening, module-system fixes) — `drop-public-setup` set this precedent by adding the `ADMIN_INITIAL_PASSWORD` gate and converting the script to ESM. The distinction: if the change touches DDL strings or `INSERT` semantics, file a migration; if it only touches Node-module behavior or pre-flight validation, edit in place and document why in the convoy.
- **Auth refactors:** `lib/permission-middleware.js`, `pages/api/auth-utils.js`, `lib/auth-secret.js`, and `lib/use-auth.js` are the four documented auth surfaces. Tighten them inside a single convoy; don't cherry-pick. (The legacy `lib/auth-context.js` and `lib/admin-auth.js` were deleted by `single-auth-provider`; do not resurrect them.)
- **Card-import jobs:** `pages/api/cards/import-*.js` hit external APIs with rate limits. Don't run them ad-hoc against prod data; use staging.
bootstrap: agent pipeline v0.5.0 + ship-readiness review Installs the three-layer agent-pipeline scaffold (https://github.com/varutasu/agent-pipeline @ v0.5.0): L1 — Context (curated brain) - AGENTS.md: orientation, conventions, 8 explicit gotchas - .cursor/rules/: no-go-zones, api-routes, auth-and-permissions, db-and-schema, ui-and-theming, schema-map - .cursor/skills/: add-api-route, add-page recipes - docs/agent-context/README.md: layer explainer - docs/SCHEMA_MAP.md: hand-curated Neon Postgres reference (replaces Prisma schema map since stack is raw SQL) L2 — Subagent roles (copied verbatim from upstream templates) - 9 .cursor/agents/role-*.md files: Conductor, IA-Architect, UX-Reviewer, Architect, Implementer, Reviewer, Design-System-Auditor, A11y-Auditor, Doc-Writer L3 — Pipeline scaffolding (Vercel variant) - CI: lint + schema-map-drift only (no duplicate build — Vercel handles it). Test job commented out until vitest lands. - preview-smoke + visual-diff via wait-for-vercel-preview - pr-health-rollup sticky comment aggregator - agent-context-drift weekly cron - PULL_REQUEST_TEMPLATE, CODEOWNERS (auth/admin paths tagged) - .convoys/ folder + seed ship-readiness.md review - lib/flags/index.js (JS — converted from TS template) - scripts/wt.sh (Cursor 3.2 deprecation stub), scripts/log-convoy-event.sh - tests/smoke/app.smoke.spec.ts (Playwright skeleton) Manifest - .agent-context-manifest.yml: tracks 31 artifacts by sha256 for future sync-agent-context drift detection Review - .convoys/ship-readiness.md: 16 findings (7 P0 ship-blockers, 5 P1 quality-bar, 4 P2 refactor, P3 UX/IA/a11y/docs) with proposed 13-convoy launch sequence. No production code changed in this commit. All findings in the ship-readiness review will be addressed in follow-up convoys starting with fix-auth-bypass. Structural brain: user-code-review-graph MCP has indexed the codebase (122 files, 628 nodes, 5602 edges, 11 communities, 84 flows). Per-developer; not committed. Co-authored-by: Cursor <cursoragent@cursor.com> 2026-05-23 00:16:08 -04:00			`---`
			`description: Files and directories agents must not edit, and should not use as context examples`
			`alwaysApply: true`
			`---`

			`# No-go zones`

			`Do not edit, refactor, or quote as context examples. If you think you need to change one of these, stop and ask.`

			`## Generated / vendored`

			- `node_modules/` — generated dependency tree
			- `.next/` — Next.js build output
			- `.vercel/` — Vercel CLI local config + build cache
			- `out/`, `build/` — build outputs if present

			`## Append-only / historical`

			- `components/Layout.js.backup` — legacy snapshot; delete with a real PR, never edit
			- `scripts/add-.js`, `scripts/fix-.js`, `scripts/seed-*.js` — historical migration / seed jobs already executed. Write a NEW dated script (or a real migration) for further schema changes; never edit ones that already ran.

			`## Secrets / credentials`

			- `.env`, `.env.local`, `.env.development.local`, `.env.test.local`, `.env.production.local`
			- Anything matching `.env*.local`
			- Never commit `JWT_SECRET`, `POSTGRES_URL`, `RESEND_API_KEY`, `BLOB_READ_WRITE_TOKEN`, `GEMINI_API_KEY`, OpenAI/Anthropic keys.

			`## Local-only / per-developer`

			- `.code-review-graph/` — local MCP graph index (only if `user-code-review-graph` is installed)
			- `.convoys/.metrics.jsonl` — per-developer convoy analytics (gitignored by default)

			`## Editing rules of thumb`

docs: post-convoy cleanup for drop-public-setup Reflects the merged drop-public-setup convoy (PR #13) in repo documentation. Small focused pass; no behavior changes. AGENTS.md: - § 1 auth bullet: replace "seed admin row still ships in setup-neon-db.js" claim with the new env-var-gated reality and the R1 operator-rotation caveat. - § 4 Gotcha #4: mark RESOLVED with commit refs (ff80753 + b63b509), document the as-shipped behavior, the Brief 2 CJS→ESM Node 22.x fix, and the R1 operator caveat. Entry kept (not renumbered) per the same convention used for resolved gotchas #2, #3, #5. - § 5 Running locally: add ADMIN_INITIAL_PASSWORD to the env-var template list with a note that setup-db exits 1 if it's unset. .convoys/ship-readiness.md: - P0 #3: mark RESOLVED 2026-05-23 with commit refs, document the full as-shipped behavior including Brief 2's CJS→ESM bonus, the R1 operator caveat (Decision A — going-forward only), and the deferred sibling weak-cred references queued for purge-weak-creds-from-helpers. .cursor/rules/no-go-zones.mdc: - Editing rules of thumb: clarify the schema-vs-operational distinction for scripts/setup-neon-db.js. drop-public-setup set the precedent that operational changes (env-var gating, pre-flight validation, module-system fixes) are allowed in place, while DDL changes still need a separate migration script. Documented so future agents don't have the same confusion the drop-public-setup architect did (see Decision B in .convoys/drop-public-setup.md). No changes to: package.json, lib/, pages/, components/, scripts/, .github/**, README.md (already updated in PR #13). Co-authored-by: Cursor <cursoragent@cursor.com> 2026-05-23 18:04:35 -04:00			- Schema changes: until a proper migration tool lands, document the change in a new dated script under `scripts/migrations/YYYY-MM-DD-<slug>.js` (folder TBD). Do NOT edit `scripts/setup-neon-db.js` in place for any DDL change (`CREATE TABLE`, `ALTER`, new columns, constraint changes) — it's idempotent and meant for first-time setup only. Operational changes are allowed (env-var gating, error-message hardening, module-system fixes) — `drop-public-setup` set this precedent by adding the `ADMIN_INITIAL_PASSWORD` gate and converting the script to ESM. The distinction: if the change touches DDL strings or `INSERT` semantics, file a migration; if it only touches Node-module behavior or pre-flight validation, edit in place and document why in the convoy.
refactor(auth): collapse lib/auth-context.js + lib/admin-auth.js onto lib/use-auth.js (#31) `lib/use-auth.js` is now the sole client-side auth surface (P1 §9 of `.convoys/ship-readiness.md`). The legacy `lib/auth-context.js` (`AuthProvider` + `useAuth`) and `lib/admin-auth.js` (`AdminProvider` + `useAdmin` + `useIsAdmin`) are deleted; every importer is migrated to the canonical hook. Pre-convoy a worst-case page mount issued THREE identical `GET /api/auth/verify` requests (one per provider/hook); the post-convoy floor is one verify per page mount (3 → 1 on `pages/card/[id].js`, 2 → 1 elsewhere). Importer inventory swept (7 source files): - `pages/_app.js` — removed `<AuthProvider>` wrapper; `<ThemeProvider>` is now the only top-level provider. `lib/use-auth.js` is hook-only, no replacement provider needed. - `pages/index.js`, `pages/scanner.js`, `pages/decks.js`, `pages/deck/[id].js`, `pages/deck-builder.js` — `import { useAuth }` path swap from `../lib/auth-context` to `../lib/use-auth`. All five pages destructured only `{ user }` or `{ user, loading }`; verified no consumer reads `login` / `register` from useAuth (those flows are in `pages/login.js` / `pages/signup.js` which call the API directly), so no shape-parity gap on `lib/use-auth.js`. - `pages/card/[id].js` — replaced `useIsAdmin()` (the only consumer of `lib/admin-auth.js` anywhere in the tree) with synchronous `user?.role === 'admin'` derived from the existing `useAuth()` call. Render condition at line 524 stays byte-identical. Decisions documented in `.convoys/single-auth-provider.md`: - D1: no extension to `lib/use-auth.js` (zero call sites for `login` / `register` from useAuth — those flows are direct fetches in `login.js` / `signup.js`). - D2: `useIsAdmin()` collapses onto `useAuth()`; no separate hook. - D3: provider tree `<ThemeProvider><AuthProvider>{children}</AuthProvider></ThemeProvider>` → `<ThemeProvider>{children}</ThemeProvider>`. - D4: 3 → 1 verify roundtrip on `card/[id].js`; 2 → 1 on every other page-load. - D5: zero test files modified; the 21-test vitest suite is server- side or prop-driven (`Layout.test.js` passes `user` as a prop, never imports the legacy hooks). Doc / config updates so the deletion lands cleanly: - `.github/CODEOWNERS` — drop the two CODEOWNERS lines for the deleted files. - `AGENTS.md` § 2 architecture row + § 3 "Auth (client)" bullet — rewritten for the post-convoy single-surface state. - `.cursor/rules/auth-and-permissions.mdc` — § "Legacy" reframed to "deleted by this convoy"; § "Authentication state on the client" updated to the post-convoy `useAuth()` shape and the direct-fetch login flow used by `login.js` / `signup.js`. - `.cursor/rules/no-go-zones.mdc` — auth-refactors bullet drops the deleted files from the canonical list. - `.cursor/skills/add-page/SKILL.md` — checklist + anti-pattern row refer to the deletion. Verification: - `rg "lib/auth-context\|lib/admin-auth" --type js` → 0 hits in source. - `npm run lint` → 128 → 125 problems (3 fewer errors from the deleted unused-import lines; no regression). - `npm run test:run` → 21/21 pass (including the 5 Layout regression locks from `fix-layout-default-user`, which are prop-driven and unaffected). - `npm run build` → all 26 pages compile end-to-end; no SSR / static- generation breakage that would have surfaced if a page tried to use the legacy context hook unwrapped. - Manual smoke deferred to operator post-merge per convoy doc. Risks (full discussion in convoy file): - R1 shape parity gap — verified zero consumers of legacy-only surface; mitigated. - R2 SSR mismatch from removing `<AuthProvider>` — `useEffect`- guarded `localStorage` read; identical SSR shape pre/post; build passes. - R3 missed importer — post-delete grep + build pass would surface any miss. - R5 stale `useAuth` cache across components — pre-existing pattern, called out as follow-up rather than addressed here. Out of scope: any change to `lib/permission-middleware.js` (server- side; resolved P0 #1), `lib/auth-secret.js` (resolved P0 #2), `pages/api/**` route handlers, login / register API contracts, or the seeded admin account flow. Co-authored-by: Cursor <cursoragent@cursor.com> 2026-05-26 23:58:08 -04:00			- Auth refactors: `lib/permission-middleware.js`, `pages/api/auth-utils.js`, `lib/auth-secret.js`, and `lib/use-auth.js` are the four documented auth surfaces. Tighten them inside a single convoy; don't cherry-pick. (The legacy `lib/auth-context.js` and `lib/admin-auth.js` were deleted by `single-auth-provider`; do not resurrect them.)
bootstrap: agent pipeline v0.5.0 + ship-readiness review Installs the three-layer agent-pipeline scaffold (https://github.com/varutasu/agent-pipeline @ v0.5.0): L1 — Context (curated brain) - AGENTS.md: orientation, conventions, 8 explicit gotchas - .cursor/rules/: no-go-zones, api-routes, auth-and-permissions, db-and-schema, ui-and-theming, schema-map - .cursor/skills/: add-api-route, add-page recipes - docs/agent-context/README.md: layer explainer - docs/SCHEMA_MAP.md: hand-curated Neon Postgres reference (replaces Prisma schema map since stack is raw SQL) L2 — Subagent roles (copied verbatim from upstream templates) - 9 .cursor/agents/role-*.md files: Conductor, IA-Architect, UX-Reviewer, Architect, Implementer, Reviewer, Design-System-Auditor, A11y-Auditor, Doc-Writer L3 — Pipeline scaffolding (Vercel variant) - CI: lint + schema-map-drift only (no duplicate build — Vercel handles it). Test job commented out until vitest lands. - preview-smoke + visual-diff via wait-for-vercel-preview - pr-health-rollup sticky comment aggregator - agent-context-drift weekly cron - PULL_REQUEST_TEMPLATE, CODEOWNERS (auth/admin paths tagged) - .convoys/ folder + seed ship-readiness.md review - lib/flags/index.js (JS — converted from TS template) - scripts/wt.sh (Cursor 3.2 deprecation stub), scripts/log-convoy-event.sh - tests/smoke/app.smoke.spec.ts (Playwright skeleton) Manifest - .agent-context-manifest.yml: tracks 31 artifacts by sha256 for future sync-agent-context drift detection Review - .convoys/ship-readiness.md: 16 findings (7 P0 ship-blockers, 5 P1 quality-bar, 4 P2 refactor, P3 UX/IA/a11y/docs) with proposed 13-convoy launch sequence. No production code changed in this commit. All findings in the ship-readiness review will be addressed in follow-up convoys starting with fix-auth-bypass. Structural brain: user-code-review-graph MCP has indexed the codebase (122 files, 628 nodes, 5602 edges, 11 communities, 84 flows). Per-developer; not committed. Co-authored-by: Cursor <cursoragent@cursor.com> 2026-05-23 00:16:08 -04:00			- Card-import jobs: `pages/api/cards/import-*.js` hit external APIs with rate limits. Don't run them ad-hoc against prod data; use staging.