#00. Shared conventions (read before any spec)

Pre-build plan (historical). Decisions D1 to D26 in 00-conventions (section 8, section 9) override it; the app uses Gemini 2.5 Flash-Lite (D26), not the Claude API. Current status: HANDOFF.md. Unchecked boxes below are the plan's acceptance list, not a status report.

Every feature spec in this folder follows these names, tables, contracts and rules. If a spec needs something different, it says so in its "Open questions" section instead of silently diverging.

• UI source of truth: design_handoff_toquilla_trace/README.md (revision 2) plus the HTML prototypes in design_handoff_toquilla_trace/designs/.
• Product overview: README.md.
• Style: plain English, no em dashes, short sentences.

---

#1. Stack and layout

app/                         Next.js routes
  (public)/page.tsx          landing
  login/ signup/ forgot/
  workshop/                  dashboard (composer + proposals)
  hats/  hats/[code]/        list + detail
  weavers/
  hat/[code]/                public passport (no app shell)
  runs/  runs/[id]/          admin only
  logs/                      admin only
  settings/
components/                  UI components (shadcn/Radix primitives)
lib/
  supabase/client.ts         browser client (anon key)
  supabase/server.ts         server client for RSC / route handlers
  log.ts                     client logger (writes to app_logs)
  request-id.ts              newRequestId()
  voice/                     speech recognition hook
supabase/
  migrations/0001_init.sql   schema + RLS
  seed.sql                   sample data (handoff "Sample data")
  functions/
    _shared/domain.ts        PURE rules: stages, grades, codes, anomalies (NO imports)
    _shared/tools.ts         agent tool definitions + handlers
    _shared/log.ts           server logger
    _shared/claude.ts        Anthropic client + call helper
    _shared/http.ts          CORS, auth helpers, request id
    workshop-agent/index.ts
    apply-proposals/index.ts
    concierge/index.ts
tests/                       vitest
evals/                       agent eval cases + runner

Rule: supabase/functions/_shared/domain.ts has zero imports, so both Deno (Edge Functions) and Node (Next.js, Vitest) can import it. Next.js imports it through the tsconfig path alias @domain/* -> supabase/functions/_shared/*.

---

#2. Domain constants (implemented once in domain.ts)

export const STAGES = ["Weaving", "Washing", "Bleaching", "Blocking", "Finished"] as const; // index 0..4
export type Grade = "Standard" | "Fino" | "Superfino";
export const GRADE_RANGES = { Standard: [8, 14], Fino: [15, 24], Superfino: [25, 40] };
export const ROWS_MIN = 6, ROWS_MAX = 40;
export const HAT_CODE_RE = /^TQ-[A-Z0-9]{5}$/;
export const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"; // no I, O, 0, 1
export type OwnerType = "workshop" | "seller" | "buyer";

Core functions (pure, unit tested): nextStage(stage), canAdvance(hat, to, actor), gradeFor(rows), gradeMismatch(grade, rows), isValidCode(code), generateCode(rand), minWeavingDays(grade) and detectAnomalies(hat, events).

---

#3. Database schema (names every spec must use)

proposals.status: pending, question, blocked, approved, rejected, dismissed, failed.

RLS summary:

• Members read and write rows of their own workshop only.
• Admins (profiles.role = 'admin') read everything.
• Anonymous users can read a hat passport only through the public_hat_passport(code) SQL function (security definer), never through the raw tables.
• app_logs and agent_runs: only admins can select. Authenticated users can insert their own rows (user_id = auth.uid()). Edge Functions write with the service role.
• Role changes: a member can never change their own role (role is not updatable by the user).

---

#4. Edge Function contracts

All functions take a header x-request-id (generated in the browser as req_ + 12 hex chars) and log with it. Responses are JSON, and errors are { error: { code, message, request_id } }.

Rate limits (simple, per IP or user, in a table or in-memory per instance): concierge 8 questions per hat per session; workshop-agent 20 runs per user per hour.

---

#5. Claude API facts (do not guess these)

• Model: claude-opus-5-5 (configurable through env ANTHROPIC_MODEL).
• Thinking: on Opus 5.5, thinking can't be disabled ({type:"disabled"} returns 400). Use thinking: { type: "adaptive" } and control cost with output_config: { effort: "low" | "medium" }. The default effort is medium, so set it explicitly. Concierge uses low; workshop agent uses medium.
• Tool choice: forced tool choice (tool_choice: {type:"any"} or {type:"tool"}) returns 400 on Opus 5.5. Use tool_choice: {type:"auto"}, strict: true on each tool (schema with additionalProperties: false and required), and tell the model in the system prompt which tool to use.
• Tool loop: manual loop over stop_reason === "tool_use". Return all tool_result blocks of one turn in a single user message. Failed tools return is_error: true with a plain message the model can act on (for example a rule violation). Cap the loop at 6 iterations.
• Stop reasons: check stop_reason before reading content (end_turn, tool_use, max_tokens, refusal).
• Refusal fallback: send beta server-side-fallback-2026-07-01 with fallbacks: "default".
• No assistant prefill. Parse tool inputs as JSON objects, never by string matching.
• Usage for logs: response.usage.input_tokens, output_tokens, cache_read_input_tokens. Price $4 / $20 per million input/output tokens.
• Caching: keep the system prompt and tool list stable and first, so they can be cached. Put no timestamps in the system prompt.
• Untrusted input: notes, chat messages and hat records go in user content or tool results, never in the system prompt, and are described as data.

---

#6. Logging (app_logs)

Every user action and every server step writes exactly one row. Action names:

Rules:

• Never log passwords, tokens or full JWTs. Notes and chat text are logged (needed for debugging) and are admin-only.
• source is one of web, edge:workshop-agent, edge:apply-proposals, edge:concierge, db.
• Logging must never break the user action: wrap writes in try/catch, and the client logger batches and retries once.

---

#7. Time budget (2 hours) and cut line

• Must ship: auth + roles; voice/typed composer (voice in Chrome, typing everywhere); workshop agent with tools and proposals; approve/reject with rule re-check; public passport; read-only concierge; app_logs with a basic Logs page; seed data; deploy; README/HANDOFF.
• Nice to have: edit proposal, undo, Hats list filters, Weavers page, run trace detail, eval script.
• Cut (documented as next steps): settings, transfer emails, QR images, Live logs, export, password reset, offline banner, dark mode toggle.

Each spec marks every item as Must, Nice or Cut.

---

#8. Decisions after spec review (these override sections 1 to 7 and any spec)

The 10 specs were written in parallel and each listed conflicts under "Open questions". These are the final answers.

Still to verify at build time (not decidable on paper): exact Anthropic TypeScript SDK option names for per-request timeout and abort signal, the Supabase Edge Function wall-clock limit (the agent's run budget is 45 s), and whether Supabase Auth email confirmation slows the grader's sign-up (if so, they can use the confirmed demo accounts).

---

#9. Model provider change (D26, overrides section 5, D8 cost numbers, D16 and D17)

The app uses Google Gemini, not Claude. User decision, 2026-10-18.

Trade-off to state in the interview: Flash-Lite is fast and very cheap but weaker at multi-step tool use than larger models. That makes the guardrails (rules in code, quote check, human approval) and the eval set more important, not less. Switching models is one env var plus the _shared/llm.ts adapter.

File rename: _shared/claude.ts becomes _shared/llm.ts (a thin provider adapter: generate({ system, messages, tools?, jsonSchema? }) returning { text, functionCalls, usage, finishReason, model }).