@appsforgood/next-supabase-kit 0.1.0

package/templates/next-supabase/SKILLS.md

@@ -0,0 +1,221 @@
+# Skills
+
+Use these reusable skills when building or reviewing this project.
+
+## Planning And Agent Council
+
+Use for planning requests, roadmap work, ambiguous feature requests, core architecture changes, auth/data changes, release changes, and any task that needs multiple agent roles.
+
+Required checks:
+- Planner starts planning and ambiguous requests.
+- Lead Architect reviews core changes before implementation.
+- Security Reviewer joins auth, data mutation, external-call, dependency, secret, and release-risk changes.
+- QA Engineer verifies behavior changes before completion.
+- Documentation Maintainer updates living docs when behavior, architecture, release, or standards change.
+
+## Best-Practice Maturity Review
+
+Use for setup audits, release readiness, roadmap checkpoints, dogfood reviews, and any claim that work is best-practice rather than merely functional.
+
+Required checks:
+- `QUALITY_GATES.md` names the target level: baseline, strong, or best-practice.
+- Affected areas are mapped across council, architecture, Supabase/RLS, security, frontend, accessibility, testing, release, docs, and repo health.
+- Evidence is named for each affected area.
+- Missing evidence is treated as incomplete, not as a passing caveat.
+- Research findings are promoted into templates, skills, checklists, audit checks, tests, release gates, or decisions before they count as kit behavior.
+
+## Agent Handoff Tracing
+
+Use for meaningful multi-agent work, core changes, security-sensitive changes, frontend acceptance reviews, release work, and any task where a decision should survive beyond the chat thread.
+
+Required checks:
+- Select the workflow from `.agent-kit/agent-roster.json`.
+- Select or confirm the model profile from `MODEL_ROUTING.md` and `.agent-kit/model-routing.json`.
+- Read `.agent-kit/project-context.json`, `.agent-kit/project-context.md`, and active correction files before routing meaningful work.
+- Record council-session evidence in Agent Studio with `agent-kit session ...` commands when available, or in `COUNCIL.md` / schema-backed records when CLI tooling is unavailable.
+- Capture each agent decision, risk, next handoff, and evidence.
+- Mark required outputs as missing, partial, complete, or not applicable.
+- Record verification commands, results, and skipped-test rationale.
+- Record human corrections before continuing and promote durable project or agent corrections when the correction should apply to future sessions.
+
+## Upgrade Maintenance
+
+Use for Agent Kit, Next.js, Supabase, UI library, testing tool, release workflow, or assistant-adapter upgrades.
+
+Required checks:
+- Read `UPGRADE.md` before accepting versioned behavior changes.
+- Run `agent-kit diff` before accepting template changes.
+- Run `agent-kit update` only on a branch where conflicts can be reviewed.
+- Preserve valid local overrides in `.agent-kit/overrides.json`.
+- Check Next.js upgrade guides and codemods when framework behavior changes.
+- Check Supabase migration history, RLS impact, generated types, and rollback risk when data/auth behavior changes.
+- Record package versions, migration order, rollback notes, verification commands, owner, and date.
+
+## Next.js App Router Architecture
+
+Use for routing, Server Components, Client Components, Server Actions, Route Handlers, data fetching, caching, revalidation, metadata, and protected app layouts.
+
+Required checks:
+- Server/client boundary is explicit.
+- Secrets never enter client bundles.
+- Data loading preserves auth context.
+- Loading, error, and empty states are handled.
+- Caching and revalidation cannot leak user-specific data.
+
+## Supabase Auth, SSR, And RLS
+
+Use for Supabase Auth, SSR clients, middleware, sessions, Row Level Security, Storage policies, and service-role usage.
+
+Required checks:
+- RLS protects every user-owned or tenant-owned table.
+- UI checks are not treated as authorization.
+- Service-role keys are server-only.
+- Auth redirects and session refreshes are tested.
+- IDOR is prevented at the SQL policy boundary.
+
+## Postgres Migrations And Schema
+
+Use for schema changes, constraints, indexes, SQL functions, triggers, seed data, and rollback planning.
+
+Required checks:
+- Migrations are ordered and reversible where practical.
+- Constraints protect integrity.
+- Indexes support expected access patterns.
+- Data migrations have failure and retry guidance.
+
+## OWASP Security Review
+
+Use for every auth change, API route, Server Action, data mutation, external call, file upload, or dependency addition.
+
+Required checks:
+- Injection, broken auth, IDOR, SSRF, insecure configuration, vulnerable dependencies, and unsafe deserialization are considered.
+- Inputs are validated and outputs are safely rendered.
+- Errors are explicit but do not leak secrets.
+
+## Frontend Design System
+
+Use for every user-facing screen and component.
+
+Required checks:
+- `DESIGN.md` has enough brand, content, user-need, and creative-direction context for the screen.
+- Reference-set, anti-reference, source-safety, and distinctiveness evidence exists for significant frontend work.
+- Frontend distinctiveness benchmark evidence exists for significant frontend work: first-screen proof, content fingerprint, reference benchmark, asset provenance, state proof, and visual QA proof.
+- Frontend product-quality scorecard exists for significant frontend work.
+- Interface is domain-specific and task-first.
+- Design tokens and component patterns are consistent.
+- Avoid generic AI-site defaults.
+- Loading, empty, error, disabled, success, and mobile states are designed.
+- Use the matching `.agent-kit/design-briefs/*` brief for SaaS, admin, marketplace, content, tool, ecommerce, portfolio/venue, education, community/social, or AI workflow surfaces.
+- Review final desktop and mobile screenshots with `.agent-kit/prompts/screenshot-review.md`.
+
+## Content-First Creative Direction
+
+Use before designing or changing a user-facing site, product screen, dashboard, tool, marketplace, content experience, ecommerce flow, portfolio, venue page, education product, community surface, or AI workflow UI.
+
+Required checks:
+- Audience, user needs, product category, and content inventory are explicit.
+- Brand personality, visual constraints, category references, and non-goals are captured.
+- At least two creative directions are considered before implementation.
+- The chosen direction affects tokens, layout, copy, imagery, density, and interaction tone.
+- Missing real content or assets are documented instead of hidden behind generic placeholders.
+
+## Reference-Led Design Critique
+
+Use before accepting significant frontend work, especially when the product risks looking like a generic AI-generated site.
+
+Required checks:
+- `DESIGN.md` includes 3-5 references and 2-3 anti-references.
+- References are used for hierarchy, density, state treatment, typography, content handling, or interaction learning without copying source designs.
+- Source-safety notes name brand marks, layouts, copy, and protected assets that must not be copied.
+- Distinctiveness is judged as weak, adequate, or strong.
+- `.agent-kit/prompts/design-critique-gate.md` records required changes and missing evidence before acceptance.
+
+## Frontend Product Quality Rubric
+
+Use before accepting significant frontend work when a repeatable acceptance score is needed.
+
+Required checks:
+- User/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety are scored `0-2`.
+- Critical zeroes are rejected.
+- Total score is at least `10/14` before acceptance.
+- Best-practice frontend claim requires at least `12/14`, desktop/mobile review, and visual QA evidence.
+- Best-practice frontend claim also requires passing distinctiveness benchmark evidence.
+
+## Frontend Distinctiveness Benchmark
+
+Use before accepting significant frontend work that could still be interchangeable with another product in the same category.
+
+Required checks:
+- The first viewport proves the real product object, task, workflow, content, or decision.
+- Product nouns, labels, data shapes, records, actions, and edge cases are visible or documented.
+- References are translated into lessons and anti-references without copied source design, brand identity, copy, or assets.
+- Asset provenance is recorded for real, generated, licensed, and placeholder visuals.
+- Important states and desktop/mobile evidence exist for the change risk.
+- Reject work that would still look valid after only changing the logo or headline.
+
+## Marketing Copy And Messaging
+
+Use before writing or accepting public-facing pages, landing pages, pricing copy, CTAs, onboarding copy, empty states, product voice, or conversion-critical UX copy.
+
+Required checks:
+- `MESSAGING.md` identifies audience, pain, desired outcome, alternatives, differentiator, proof, objections, voice, and conversion goal.
+- Missing positioning inputs are asked as explicit questions before final copy is written.
+- Claims are supported by named proof or marked as assumptions.
+- Headline, subhead, CTA, proof, and objection handling match the same value proposition.
+- Copy uses real product nouns, workflows, constraints, and customer language.
+- CTAs have one primary action and clear secondary actions.
+- Risky pricing, privacy, security, compliance, performance, medical, financial, or legal claims are reviewed before release.
+- Marketing Copy Lead hands off public-facing copy to Frontend Design Lead for layout and hierarchy review.
+
+## Accessibility WCAG 2.1 AA
+
+Use for forms, navigation, modals, menus, tables, dashboards, and any custom interaction.
+
+Required checks:
+- Semantic HTML is preferred.
+- ARIA is used only when needed.
+- Keyboard navigation and focus states work.
+- Color contrast meets WCAG 2.1 AA.
+
+## Testing And QA
+
+Use for unit, integration, regression, Playwright smoke coverage, visual QA, and acceptance evidence.
+
+Required checks:
+- Core logic has unit tests.
+- Preserved behavior has regression tests.
+- Critical paths have smoke tests.
+- Auth and data mutation paths are prioritized.
+- High-risk UI changes have screenshot or visual-regression evidence.
+
+## Visual Regression QA
+
+Use when changing user-facing screens, reusable components, visual design tokens, responsive layouts, image-heavy pages, or any surface where appearance is part of acceptance.
+
+Required checks:
+- Visual QA tier is named: baseline screenshots, Playwright screenshots, Storybook visual tests, or visual-regression service.
+- Component states and important responsive breakpoints are captured.
+- Dynamic or volatile regions are mocked, masked, frozen, or excluded with rationale.
+- Baseline updates require human review and a short rationale.
+- Visual checks do not replace accessibility, keyboard, semantic, auth, or data-boundary tests.
+
+## Documentation Maintenance
+
+Use after every significant change.
+
+Required checks:
+- `SPEC.md` reflects current behavior.
+- `DECISIONS.md` records important tradeoffs.
+- `DOCS.md` explains workflows and integration points.
+- `COUNCIL.md` captures required handoffs and evidence for meaningful multi-agent work.
+- `MODEL_ROUTING.md` captures model profile and IDE enforcement evidence.
+- `QUALITY_GATES.md`, `DESIGN.md`, `MESSAGING.md`, `STYLE_GUIDE.md`, `SECURITY.md`, `TESTING.md`, `DEPLOYMENT.md`, and `UPGRADE.md` stay current.
+
+## Compatibility Profiles
+
+Use `.agent-kit/profiles/*` before feature planning when the project is a SaaS, marketplace, admin app, or content app.
+
+Required checks:
+- The project type's auth, data, design, testing, and handoff risks are named.
+- Agent ownership matches the profile.
+- Missing profile assumptions are recorded in `DECISIONS.md`.

package/templates/next-supabase/SPEC.md

@@ -0,0 +1,114 @@
+# Specification
+
+This file is the living functional and technical specification for the project.
+
+## Product Summary
+
+Describe the product, primary users, core workflows, and business-critical behavior.
+
+## Current Architecture
+
+Document the current system shape:
+
+- Next.js routing model
+- Server Components and Client Components
+- Route Handlers and Server Actions
+- Supabase Auth flow
+- Supabase tables, RLS policies, and Storage buckets
+- Deployment target
+- Observability and logging
+
+## Behavioral Contracts
+
+List behavior that must be preserved during changes:
+
+- Agent council routing in `.agent-kit/agent-roster.json`
+- Model profile routing in `MODEL_ROUTING.md` and `.agent-kit/model-routing.json`
+- Council-session evidence in `COUNCIL.md`
+- Agent, council-session, model-routing, and audit-report schema contracts in `.agent-kit/schemas/`
+- Planner default ownership for planning and Lead Architect review for core changes
+- Quality gate evidence in `QUALITY_GATES.md`
+- Content-first design direction in `DESIGN.md`
+- Messaging and copy evidence in `MESSAGING.md`
+- Reference-led design critique evidence in `DESIGN.md`
+- Auth and session behavior
+- User ownership and tenant boundaries
+- Data mutation rules
+- API response expectations
+- UI workflows and critical paths
+
+## Data Model
+
+Document tables, relationships, constraints, indexes, and ownership rules.
+
+## RLS Policy Inventory
+
+Track authorization at the data boundary.
+
+| Table/Bucket | Owner Boundary | Select | Insert | Update | Delete | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| `example_table` | `user_id = auth.uid()` | Required | Required | Required | Optional | Replace with real policy names. |
+
+## Security Requirements
+
+- Authorization is enforced by Supabase RLS.
+- Service-role keys are server-only.
+- User input is validated at all boundaries.
+- User-controlled output is safely rendered.
+- Privileged operations are logged.
+
+## Quality Gate Level
+
+Record the current maturity target and evidence.
+
+| Area | Baseline | Strong | Best-Practice | Evidence |
+| --- | --- | --- | --- | --- |
+| Council routing | TBD | TBD | TBD | `AGENT_ROSTER.md`, `COUNCIL.md` |
+| Model routing | TBD | TBD | TBD | `MODEL_ROUTING.md`, `ASSISTANT_ADAPTERS.md` |
+| Architecture | TBD | TBD | TBD | Affected-layer map, `DECISIONS.md` |
+| Supabase/RLS | TBD | TBD | TBD | RLS inventory, migration tests |
+| Messaging | TBD | TBD | TBD | `MESSAGING.md`, proof map, objection handling, CTA hierarchy |
+| Frontend | TBD | TBD | TBD | `DESIGN.md`, reference-set evidence, design critique verdict, product-quality scorecard, screenshots, visual QA |
+| Testing | TBD | TBD | TBD | Unit, regression, smoke, visual evidence |
+| Release | TBD | TBD | TBD | `DEPLOYMENT.md`, logs, rollback notes |
+
+## UX Requirements
+
+- Interfaces are mobile-first and accessible.
+- Loading, empty, error, disabled, and success states are handled.
+- Visual design is domain-specific and avoids generic AI-site defaults.
+- Audience, user needs, real content, brand constraints, and creative direction are documented before frontend implementation.
+- Audience, pain, desired outcome, differentiator, proof, objections, voice, and CTA hierarchy are documented before public-facing or conversion-facing copy is accepted.
+- Reference set, anti-references, source-safety notes, and design critique verdict are documented before accepting significant frontend work.
+- Frontend product-quality scorecard is documented before accepting significant frontend work.
+- First screens show the real product, task, object, content, or workflow.
+
+## Brand And Content Inventory
+
+Track the inputs that make the UI specific to this product.
+
+| Area | Current Decision | Evidence |
+| --- | --- | --- |
+| Product category | TBD | `DESIGN.md` |
+| Primary audience | TBD | User research, analytics, stakeholder input, or project brief |
+| User needs | TBD | `DESIGN.md` and accepted stories |
+| Real content/data | TBD | Seeds, CMS, database schema, product copy, assets |
+| Value proposition | TBD | `MESSAGING.md`, proof, objections, and CTA evidence |
+| Brand constraints | TBD | Logo, colors, fonts, imagery, platform rules |
+| Reference set | TBD | `DESIGN.md`, category references, source-safety notes |
+| Anti-references | TBD | `DESIGN.md`, explicit non-goals |
+| Chosen creative direction | TBD | Creative-direction matrix and screenshots |
+| Design critique verdict | TBD | `DESIGN.md`, critique-gate review |
+| Visual QA tier | TBD | `TESTING.md`, Storybook, Playwright report, visual-regression service, or screenshot artifacts |
+
+## Component And State Inventory
+
+Track important UI surfaces so design quality is reviewable.
+
+| Surface | Components | Loading | Empty | Error | Disabled | Success | Mobile Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Primary workflow | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+
+## Open Questions
+
+Track unresolved product or technical decisions here until they become entries in `DECISIONS.md`.

package/templates/next-supabase/STYLE_GUIDE.md

@@ -0,0 +1,104 @@
+# Style Guide
+
+## Code Style
+
+- Prefer explicit names over clever abbreviations.
+- Keep server-only logic in server-only modules.
+- Keep UI components focused on rendering and interaction.
+- Validate inputs at boundaries before calling business logic.
+- Return clear errors; do not silently swallow failures.
+
+## Next.js Patterns
+
+- Use Server Components by default.
+- Use Client Components only for browser state, events, effects, or client-only libraries.
+- Keep Route Handlers and Server Actions thin.
+- Keep user-specific data out of shared caches.
+
+## Supabase Patterns
+
+- Use SSR-safe Supabase clients.
+- Enforce ownership and tenancy through RLS.
+- Keep service-role access isolated to trusted server code.
+- Document every policy assumption.
+
+## Frontend Design Rules
+
+Use `DESIGN.md` before visual implementation. Frontend work should be content-first: audience, user needs, real content, brand constraints, and creative direction must be understood before styling starts.
+
+Do not default to generic AI-site visual patterns:
+
+- No generic purple-blue gradient hero as the default solution.
+- No fake metrics or placeholder dashboard cards.
+- No vague SaaS copy.
+- No oversized rounded card grids unless the domain calls for them.
+- No landing page when the user asked for a working app or tool.
+
+Prefer:
+
+- Task-first screens.
+- Domain-specific navigation and information hierarchy.
+- Real workflow states.
+- Reusable design tokens.
+- Accessible forms and controls.
+- Clear density rules for admin, SaaS, and operational tools.
+- Mobile-first responsive layouts.
+- Creative direction that is visibly tied to product content and user need.
+
+Use `.agent-kit/prompts/brand-content-intake.md` and `.agent-kit/prompts/creative-direction-matrix.md` when inputs are under-specified. Use `.agent-kit/design-briefs/*` before designing SaaS, admin dashboard, marketplace, content app, tool, ecommerce, portfolio/venue, education, community/social, or AI workflow surfaces. Use `.agent-kit/prompts/screenshot-review.md` after implementation to review desktop and mobile screenshots. Use `.agent-kit/prompts/visual-qa-plan.md` when a change needs repeatable visual regression or component-state evidence.
+
+Use `.agent-kit/prompts/design-critique-gate.md` before accepting significant frontend work. `DESIGN.md` should name a reference set, anti-references, source-safety notes, and a distinctiveness verdict so a design cannot pass only because it has tokens, states, and screenshots.
+
+Use `.agent-kit/prompts/frontend-distinctiveness-benchmark.md` before accepting significant frontend work. `DESIGN.md` should prove first-screen specificity, content fingerprint, reference benchmark, asset provenance, state proof, and visual QA proof so a design cannot pass while remaining interchangeable with another product in the same category.
+
+Use `.agent-kit/prompts/frontend-product-quality-scorecard.md` before accepting significant frontend work. `DESIGN.md` should score user/task fit, content specificity, visual identity, information architecture, component states, accessibility and interaction, and source safety. Reject work with critical zeroes or a total score below `10/14`; reserve best-practice claims for `12/14` or higher with desktop/mobile and visual QA evidence.
+
+## Messaging And Copy Rules
+
+Use `MESSAGING.md` before writing public-facing or conversion-facing copy. Copy should identify the audience, pain, desired outcome, differentiator, proof, objections, voice, and CTA hierarchy before it is accepted.
+
+Prefer:
+
+- Specific product nouns, workflows, constraints, and customer language.
+- Claims tied to proof or marked as assumptions.
+- One primary CTA with clear secondary actions.
+- Useful next steps for onboarding, empty, error, permission, upgrade, and pricing copy.
+
+Reject unsupported superlatives, invented proof, dark patterns, forced urgency, vague AI claims, and risky pricing, privacy, security, compliance, performance, medical, financial, or legal wording.
+
+## Design Token Inventory
+
+Define design tokens instead of ad hoc styling.
+
+| Token Area | Required Decisions |
+| --- | --- |
+| Color | Semantic colors, contrast, status colors |
+| Typography | Font family, scale, weights, line height |
+| Spacing | Base unit, dense/admin spacing, section spacing |
+| Radius | Component radius defaults and exceptions |
+| Motion | Duration, easing, reduced-motion behavior |
+| Shadow/Depth | When elevation is allowed |
+
+## Component States
+
+Every interactive component should consider:
+
+- Default
+- Hover
+- Focus
+- Disabled
+- Loading
+- Empty
+- Error
+- Success
+- Mobile
+
+For reusable components, capture these states as Storybook stories, Playwright screenshot cases, or documented screenshot evidence when the component is visually significant.
+
+## Accessibility
+
+- Use semantic HTML first.
+- Use ARIA only when semantics are insufficient.
+- Keep keyboard navigation predictable.
+- Maintain visible focus states.
+- Meet WCAG 2.1 AA contrast.

package/templates/next-supabase/TESTING.md

@@ -0,0 +1,68 @@
+# Testing
+
+Testing should be proportional to risk. Auth, data mutations, payments, admin actions, and migrations receive the most coverage.
+
+## Required Test Types
+
+- Unit tests for core logic and edge cases.
+- Regression tests for preserved behavior.
+- Integration tests for API, Server Actions, and Supabase interactions where practical.
+- Playwright smoke tests for auth and critical user workflows.
+- Visual QA for important user-facing screens and reusable component states.
+
+## Critical Smoke Paths
+
+Define project-specific smoke tests for:
+
+- Login and logout
+- Protected route access
+- Primary user workflow
+- Data creation and update
+- Error and empty states
+- Mobile navigation
+
+## Visual QA And Regression
+
+Choose the smallest reliable visual QA tier for the project:
+
+| Tier | Use When | Evidence |
+| --- | --- | --- |
+| Baseline | Any user-facing UI exists | Desktop/mobile screenshots reviewed with `.agent-kit/prompts/screenshot-review.md` |
+| Strong | Primary workflows or responsive layouts change often | Playwright screenshot checks such as `toHaveScreenshot()` for stable pages/states |
+| Mature | Shared component system, design system, or frequent UI releases | Storybook state stories plus visual regression in CI through Chromatic, Argos, Loki, Playwright snapshots, or equivalent |
+
+Required rules:
+
+- Capture default, loading, empty, error, disabled, success, permission-denied, and mobile states where relevant.
+- Stabilize dynamic data, animations, dates, avatars, generated media, and third-party widgets before visual comparison.
+- Review baseline updates as product changes; do not auto-accept visual diffs without rationale.
+- Keep accessibility, semantic, keyboard, auth, and data-boundary tests separate from visual checks.
+
+## CI Gates
+
+Every project should define the smallest reliable CI gate for its risk profile.
+
+Recommended baseline:
+
+- Install from lockfile
+- Typecheck
+- Unit tests
+- Build
+- Dependency audit
+- `agent-kit audit --min-readiness baseline-setup`
+- Playwright smoke tests for critical paths
+- Visual QA evidence for high-risk UI changes
+
+## Security-Focused Tests
+
+Prioritize:
+
+- IDOR attempts
+- Cross-tenant access attempts
+- Unauthorized API calls
+- RLS-protected reads and writes
+- Service-role-only operations
+
+## Test Gaps
+
+If test infrastructure does not exist, document the smallest viable setup and the risk of shipping without it.

package/templates/next-supabase/UPGRADE.md

@@ -0,0 +1,59 @@
+# Upgrade Guide
+
+Use this file when upgrading Agent Kit, Next.js, Supabase, shared UI primitives, or any tool that changes project behavior.
+
+## Agent Kit Upgrade Flow
+
+```bash
+npx @agent-skills/next-supabase-kit@latest doctor
+npx @agent-skills/next-supabase-kit@latest diff
+npx @agent-skills/next-supabase-kit@latest update
+npx @agent-skills/next-supabase-kit@latest audit --min-readiness baseline-setup
+```
+
+Use `agent-kit audit --min-readiness best-practice-candidate` only after starter placeholders and upgrade evidence are replaced with project-specific evidence.
+
+## Required Review
+
+- Create a branch before running `agent-kit update`.
+- Run `agent-kit diff` before accepting changed templates.
+- Review `.agent-kit/conflicts/` before accepting changed templates.
+- Preserve valid local customizations in `.agent-kit/overrides.json`.
+- Review `AGENTS.md`, `AGENT_ROSTER.md`, `ASSISTANT_ADAPTERS.md`, `MODEL_ROUTING.md`, `COUNCIL.md`, `QUALITY_GATES.md`, `SECURITY.md`, `TESTING.md`, and `DEPLOYMENT.md`.
+- Record accepted tradeoffs in `DECISIONS.md`.
+- Update this file with package version, release notes, migration status, rollback notes, owner, and date.
+
+## Next.js Upgrade Notes
+
+- Check the official Next.js upgrade guide for the target version.
+- Use official Next.js codemods when the upgrade guide recommends them.
+- Confirm routing, Server Component, Client Component, Route Handler, Server Action, caching, metadata, and middleware behavior.
+- Confirm model-routing recommendations, IDE enforcement limits, and dated model comments still match the project's active tools.
+- Run build, tests, smoke checks, and visual QA for affected screens.
+
+## Supabase Upgrade Notes
+
+- Treat schema, RLS, storage, auth, and edge-function changes as migration work.
+- Check local and remote migration history before deployment.
+- Do not rely on dashboard-only database changes for production behavior.
+- Record migration order, rollback risk, and verification evidence in `DEPLOYMENT.md`.
+- Regenerate typed clients after schema changes when the project uses generated Supabase types.
+
+## Rollback Evidence
+
+| Item | Value |
+| --- | --- |
+| Previous package/framework version | TBD |
+| New package/framework version | TBD |
+| Branch or revert commit | TBD |
+| Template conflicts reviewed | TBD |
+| Database migrations applied | TBD |
+| Rollback command or process | TBD |
+| Verification commands | TBD |
+| Owner/date | TBD |
+
+## Upgrade History
+
+| Date | Change | Evidence | Outcome |
+| --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD |