M0: scaffold Next.js + TypeScript + Tailwind + shadcn; revise CLAUDE.md

CLAUDE.md

@@ -1,54 +1,69 @@
 # CLAUDE.md — Claude Code Implementation Guide
 ## SOP Governance Tool (Stage 1, single-tenant)
 
-You are pair-programming with a **coding beginner** who is the product owner and domain expert (3PL logistics). Optimize for his learning and for maintainability, not for cleverness.
+You are pair-programming with a **coding beginner**, solo founder, 3PL logistics domain expert. Optimize for his learning and maintainability, never cleverness.
 
-## Project context
-- Full specs live in `/docs` — READ THE RELEVANT SPEC before implementing anything:
-  `01-PRD` (scope/roles) · `02-FRD` (requirements + acceptance criteria) · `03-architecture` (stack & decisions AD-1…AD-6) · `04-database-schema` (DDL + RLS) · `05-api-spec` (routes & payloads) · `06-ui-ux` (screens & tokens) · `07-development-plan` (milestones M0–M7, incl. M6.5 incident log).
-- Stack is FIXED: Next.js App Router + TypeScript + Tailwind + shadcn/ui + Supabase + Vercel + Anthropic API. Do not introduce other databases, ORMs (use supabase-js), state libraries, or i18n frameworks.
-- Single org today, but `org_id` + RLS on every table is non-negotiable (AD-1).
+## Project description
+Web app for ONE company (founder's own warehouse) replacing manual SOP governance: Editors draft SOPs (AI-assisted), Approvers approve/reject, Admin publishes versioned snapshots, Staff view on phone in EN/BM/ZH and tap-acknowledge with a typed-name signature. Dashboard tracks acknowledgement %. Staff also report floor incidents (photo + severity) feeding SOP revisions. Every governance action is audit-logged.
 
-## How to work with me (the human)
-1. **Explain as you go.** After writing code, give a 3–5 line plain-English summary of what it does and why. If I ask "explain", teach me line-by-line.
-2. **Small steps.** Implement ONE checklist item at a time, then tell me exactly how to test it in the browser before moving on.
-3. **Ask before:** adding any dependency, changing the schema, deviating from a spec, or deleting more than ~30 lines.
-4. **Never** put secrets in client code, disable RLS "temporarily", or mock away auth to make something work.
-5. When something fails, show me the error, your diagnosis in plain English, then the fix.
+## Fixed stack (never substitute)
+Next.js 14+ App Router + TypeScript · Supabase (Postgres + Auth + Storage + RLS) · Vercel · Anthropic API (server-side only) · Tailwind + shadcn/ui. No other DB, ORM (use supabase-js directly), state library, or i18n framework. Ask before adding ANY dependency not already in this list.
+
+## Hard rules
+1. `org_id` on every table, RLS enabled on every table — non-negotiable even with 1 org.
+2. State machine (`canTransition()`, `nextVersion()`) lives ONLY in `lib/workflow.ts`. No status transition logic duplicated elsewhere.
+3. AI calls are server-side only (`/api/ai/*` routes), never from the client. `ANTHROPIC_API_KEY` and `SUPABASE_SERVICE_ROLE_KEY` only in server files / Vercel env vars.
+4. Every mutation writes an `audit_log` row in the same transaction (route handler using service-role client).
+5. Published SOP content is a frozen snapshot in `sop_versions` — never edit it; edits happen on the draft row only.
+6. No secrets client-side, never disable RLS "temporarily", never mock away auth to make something work.
+
+## Spec-review decisions (apply when the relevant milestone is built)
+- **Storage:** `sop-photos` bucket, path-scoped policy — Editor+ write to SOP step paths; Staff insert-own under `incidents/{user_id}/*` (needed for FR-7.1 staff photo upload). Apply at M6.5/S19.
+- **Approver scope:** Approver acts org-wide, not department-scoped — PRD "in their scope" language is dropped, matches existing RLS/schema. No dept filter needed on approvals.
+- **FR-3.2 notification:** "Editor notified in-app" = visible via SOP status change + History (audit) tab. No separate notifications table/UI.
+- **`sop_status` enum:** drop `archived` — unused in Stage 1, remove from `create type sop_status` in `db/schema.sql` at S2.
+
+## Directory layout (from 03-architecture §4)
+```
+/app
+  /(auth)/login
+  /(admin)/dashboard  /sops  /sops/[id]/edit  /approvals  /users  /audit
+  /(staff)/my-sops  /my-sops/[id]
+  /api/sops/... /api/ai/... /api/ack ...
+/components   (ui/ = shadcn, sop/ = editor pieces, staff/ = mobile viewer)
+/lib
+  supabase/ (browser client, server client, service client)
+  ai/ (anthropic client, prompts, parsers)
+  workflow.ts (status machine)
+  audit.ts (writeAudit())
+/db
+  schema.sql  policies.sql  seed.sql
+/docs (spec pack)
+CLAUDE.md
+```
+
+## How we work together
+1. **One milestone at a time**, per `docs/07-development-plan.md` session plan (S1...S22). Don't build ahead.
+2. Before writing code for a step: explain the plan in plain English first, wait if it's non-trivial.
+3. After writing code: 3–5 line plain-English summary of what it does and why. If asked "explain", go line-by-line.
+4. **Ask before:** adding a dependency, changing the schema, deviating from a spec, deleting more than ~30 lines.
+5. When something fails: show the error, plain-English diagnosis, then the fix.
+6. Test in the browser after each small step before moving to the next.
 
 ## Conventions
 - TypeScript strict; server components by default, `"use client"` only when needed.
-- All workflow mutations go through `/app/api/*` route handlers using the service-role client; state transitions ONLY via `lib/workflow.ts`; every mutation writes `audit_log` in the same transaction (AD-3).
-- Reads use the user-scoped client under RLS.
-- Errors: return `{ error: { code, message } }` with correct HTTP status (see 05-api-spec §5).
-- Commits: after each working step, imperative plain English ("Add SOP publish route with version snapshot").
+- Reads use the user-scoped client under RLS; writes/workflow mutations go through `/app/api/*` with the service-role client.
+- Errors: `{ error: { code, message } }` with correct HTTP status (05-api-spec §6).
+- Commits: imperative plain English, after each working step ("Add SOP publish route with version snapshot").
 - Files: kebab-case; components PascalCase; one component per file.
 
-## Session plan (follow in order; ~2 hours each)
-Before each session: read the matching milestone in `docs/07-development-plan.md` and the FRD items it cites. After each: run the ✅ checklist with me, commit, push (Vercel auto-deploys).
-
-- **S1 (M0):** Scaffold app, Tailwind, shadcn init; Supabase clients in `lib/supabase/`; env wiring; deploy hello world.
-- **S2 (M0):** Apply `db/schema.sql` + `db/policies.sql` + `db/seed.sql`; verify tables + RLS deny-by-default with an anon query test.
-- **S3–4 (M1):** Login page + session; profiles + JWT claims hook; role-redirect middleware; route guards.
-- **S5 (M1):** Users & Departments admin pages (invite, role change, deactivate).
-- **S6–7 (M2):** SOP list (filters/search) + create dialog; SOP detail shell with status badge.
-- **S8–9 (M2):** Structured editor: sections nav, step cards (add/reorder/delete), photo upload to Storage, autosave.
-- **S10 (M3):** `lib/workflow.ts` (canTransition, nextVersion) with unit tests; submit route + validation.
-- **S11 (M3):** decide (approve/reject) + approvals queue page; publish route with version snapshot transaction; versions tab.
-- **S12 (M3):** `lib/audit.ts`; wire audit into all mutations; audit page + per-SOP history tab.
-- **S13 (M4):** Assign-departments dialog + route; staff `/my-sops` list (mobile shell, needs-ack vs acked).
-- **S14 (M4):** Staff SOP viewer (mobile, language switcher) + acknowledge flow (typed-name sheet, immutability, re-ack on new version) + share link.
-- **S15 (M5):** Dashboard cards + per-SOP acknowledgement table + department table + overdue badges.
-- **S16 (M5):** Ack report endpoint + CSV export; audit CSV.
-- **S17 (M6):** `lib/ai/` (client, prompts, JSON parser with one retry); `/api/ai/draft` + editor modal; ai_log + daily rate limit.
-- **S18 (M6):** `/api/ai/translate` + translations tab + reviewed flag + staff-viewer fallback rule (safety → English until reviewed).
-- **S19 (M6.5):** Incidents table + policies; POST /api/incidents; staff report flow (viewer "Report a problem" + My SOPs button, severity buttons, photo upload).
-- **S20 (M6.5):** Admin incident list with filters + detail; review/close route with resolution note + "requires SOP revision" jump; SOP detail Incidents tab; dashboard open-incidents card.
-- **S21 (M7):** Security checklist from `docs/03-architecture.md §6` — verify each item with me and show the evidence.
-- **S22 (M7):** Real data seed for the company; fix onboarding frictions; final walkthrough of `docs/02-FRD.md` acceptance criteria.
+## Current milestone
+**M0 — Setup (S1).** Scaffold Next.js + TypeScript + Tailwind + shadcn/ui; create Supabase project (Singapore region); Supabase clients in `lib/supabase/`; env wiring; deploy hello world to Vercel.
 
 ## Definition of done (any task)
-Works in the browser · matches its FRD acceptance criteria · no TypeScript errors · explained to me in plain English · committed · deployed preview checked.
+Works in the browser · matches its FRD acceptance criteria · no TypeScript errors · explained in plain English · committed · deployed preview checked.
 
 ## Scratch — next session goal
-(Human writes 1–2 lines here before each session.)
+(Write 1–2 lines here before each session.)
+
+Ignore the add-module skill — it targets a different stack.