# CLAUDE.md — Claude Code Implementation Guide
## SOP Governance Tool (Stage 1, single-tenant)

You are pair-programming with a **coding beginner**, solo founder, 3PL logistics domain expert. Optimize for his learning and maintainability, never cleverness.

## 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.

## 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.
- 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.

## 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 in plain English · committed · deployed preview checked.

## Scratch — next session goal
(Write 1–2 lines here before each session.)

Ignore the add-module skill — it targets a different stack.