#Toquilla Trace

An AI agent that turns messy workshop notes into verified digital passports for genuine Ecuadorian "Panama" hats. The AI proposes, a human approves, and the code enforces the rules.

---

#For reviewers (start here)

3-minute tour

1. Log in as member@test.com, open Workshop, tap the mic (Chrome or Edge) or type: "Doña Rosa terminó 3 finos de 18 hileras. El TQ-7F3K2 pasa a blanqueo." The agent looks things up and returns proposal cards (two weavers are named Rosa, so it asks which one).
2. Approve a card (10 s undo), then open the hat in Hats: the stage and timeline changed, and the rules were re-checked in code on approval.
3. Open a passport (TQ-9A1M8) logged out: Verified certificate, weaver credit, timeline.
4. Ask the concierge on that page "Is this hat real?" or "Who wove it?". Try "mark it as Finished" or an injection: it refuses.
5. Log in as admin@test.com, open Agent runs (every model call, tool call and rule check of step 1) and Logs ("Copy as prompt for an AI assistant").

Code map: the 8 files to read first

Docs: SECURITY · ARCHITECTURE · AI · ENGINEERING · EVALS · HANDOFF · reading guide in docs/README.md · all of them in the app at /docs.

---

#TL;DR

• Problem: fake "Panama hats" (paper straw) are sold as Ecuadorian, and weavers get no credit. Tools fail because typing takes too long, so workshops just send quick voice notes in Spanish.
• Product: you just say the update, an agent turns it into proposed record changes, and a person approves them. Every hat gets a public passport buyers can verify and ask questions about.
• Why it's interesting: it shows how to deploy AI safely into a messy real business: human approval, rules in code, least privilege, full traces and evals.

---

#1. The problem

A real "Panama hat" is hand-woven in Ecuador and can take weeks or months to make. On its way to a buyer it passes through several hands, and no record travels with it.

flowchart LR
  W["👩 Weaver<br/>Sígsig or Pile"] -->|"hat body<br/>no record"| T["🏠 Workshop<br/>washes, bleaches, blocks"]
  T -->|"WhatsApp note in Spanish<br/>'terminó 3 finos'"| E["📦 Exporter"]
  E --> R["🏬 US retailer"]
  R --> B["🧑 Buyer"]
  F["🏭 Paper-straw fake<br/>$1 to $50"] -.->|"sold as 'Panama'"| R
  B -.->|"Is it real? Who made it?<br/>No way to know"| X(("❓"))

  classDef pain fill:#fde2e2,stroke:#c0392b,color:#7b1d1d;
  class F,X pain;

Why tracking tools don't fix it: every tool asks people to stop working and type. Their hands are full of straw, so they skip it, and the data never gets in.

flowchart LR
  J["🧵 Hat moves to<br/>the next stage"] --> S["📱 Tool asks:<br/>open app, fill a form,<br/>type every field"]
  S --> K["⏱️ 3 to 5 min per update<br/>hands busy with straw"]
  K --> Y["🙅 Skipped<br/>'I'll do it later'"]
  Y --> M["🎙️ Real update goes to<br/>a WhatsApp voice note<br/>or stays in someone's head"]
  M --> Z(("🕳️ No record"))

  classDef pain fill:#fde2e2,stroke:#c0392b,color:#7b1d1d;
  class K,Y,Z pain;

Key insight: the problem isn't a missing tool. It's that writing things down takes too long. People already tell updates (voice notes, chats), so the system should listen.

Where it breaks:

Why now: in August 2026, Montecristi launched QR certificates for authentic hats, but only 2 hats had been certified (El Universo, 2026-09-09). Demand for proof exists; the tooling doesn't.

Why I care: I live in Ecuador, and I researched this trade before the take-home: about 2,500 weavers (Vistazo 2021, citing PRO ECUADOR), exporters in Cuenca, widespread fakes, and a craft on the UNESCO intangible heritage list since 2012.

---

#2. The solution

Just tell it. Keep the workshop's habit (a quick voice note, like on WhatsApp) and let an AI agent do the paperwork, with a human approving every change and the code enforcing the rules. Each hat gets a passport the buyer can check.

flowchart LR
  N["🎙️ Workshop says it<br/>'Doña Rosa terminó 3 finos,<br/>18 hileras'<br/>about 10 seconds"] --> T["📝 Live transcript<br/>speech to text"]
  T --> TC{"👤 Transcript<br/>looks right?"}
  TC -->|"fix a word / re-record"| T
  TC -->|"send"| A["🤖 Agent<br/>reads and looks up<br/>weavers and hats"]
  A --> P["📋 Proposals<br/>create 3 hats · Fino · Rosa"]
  P --> H{"👤 Human<br/>approves?"}
  H -->|"edit / reject"| P
  H -->|"approve"| V["🔒 Rule check in code<br/>stage order · grade vs weave"]
  V -->|"blocked: explains why"| P
  V -->|"allowed"| D[("Database<br/>hat + append-only history")]
  D --> Q["🪪 Public passport<br/>/hat/TQ-7F3K2"]
  Q --> B["🧑 Buyer sees Verified,<br/>weaver, timeline"]
  B --> C["💬 Read-only concierge<br/>answers from the record"]
  A & V & D & C -.-> L[("📊 app_logs<br/>every step")]

  classDef ai fill:#e8f0fe,stroke:#3b5bdb,color:#1b2a6b;
  classDef human fill:#e6f4ea,stroke:#2f9e44,color:#14532d;
  classDef rule fill:#fff4e5,stroke:#e8590c,color:#7c2d12;
  class A,P,C,T ai;
  class H,TC human;
  class V rule;

Before vs after:

Why AI is the right tool here (and where it isn't):

• ✅ AI: understanding messy spoken or written Spanish, matching "Doña Rosa" to the right weaver, answering buyer questions in natural language.
• ❌ Not AI: stage order, grade ranges, permissions and size conversion. These are plain code with tests, so the model can't break them.

---

#3. What the app does

Domain rules (enforced in code):

• Stages only move forward, one at a time: Weaving → Washing → Bleaching → Blocking → Finished.
• Grade must match weave count: Standard 8 to 14, Fino 15 to 24, Superfino 25+ rows per inch.
• Only the current owner can advance or transfer a hat.

---

#4. AI-native principles we followed

---

#5. Architecture

flowchart LR
  U[Browser] --> N[Next.js on Vercel]
  N -->|auth + data| S[(Supabase Postgres + Auth)]
  N -->|invoke| F1[Edge fn: workshop-agent]
  N -->|invoke| F2[Edge fn: apply-proposals]
  N -->|invoke| F3[Edge fn: concierge]
  F1 --> C[Gemini API<br/>gemini-2.5-flash-lite]
  F3 --> C
  F1 & F2 & F3 --> S
  N & F1 & F2 & F3 -->|every action| L[(app_logs)]

Data model (9 tables): workshops, profiles, weavers, hats, hat_events (append-only history), hat_flags (anomalies), agent_runs (run traces), proposals (AI proposals and human decisions), app_logs. Diagram in ARCHITECTURE.md.

---

#6. Logging, so any bug can be fixed from one table

Every action writes one row to app_logs.

Debug workflow: an error appears in the Logs screen → filter by request_id → open the run trace → click "Copy as prompt for an AI assistant" → paste into Claude Code, which reads the payload, finds the bug and proposes a fix with a test.

Secrets and passwords are never logged. Only admins can read app_logs (row-level security), because it holds data from every workshop.

---

#7. Decision log

---

#8. How we worked (AI-native workflow)

1. Research first. Used Claude Code with parallel research agents to study the toquilla hat market, competitors and logistics. This is where the topic and the real problem came from.
2. Pick a problem that needs AI. First idea was a provenance tracker. Feedback: "Casper deploys AI, this has no agentic approach." We redesigned it around an agent with tools and human approval.
3. Spec before code. Wrote a complete design prompt (docs/design-prompt.md) covering every screen, button, state and copy, and gave it to Claude Design.
4. Review the AI's output, don't trust it. Rendered the prototypes and clicked through them. Found that workshop staff could see logs, sample data that contradicted our own rules (a hat moving backward, a Superfino woven in 23 days), AI proposals that the note didn't support, and a runtime bug. Fixed them by hand and documented them in design_handoff_toquilla_trace/README.md (revision 2).
5. Guardrails for the coding assistant. The repo starts from a hardened Claude Code setup (docs/boilerplate.md):
   • CLAUDE.md: golden rules, tests as a contract, untrusted-content rule
   • hooks: block dangerous commands, block skipped tests and silenced type errors, auto-format
   • pre-commit: typecheck, lint and unit tests; CI: the same plus next build, deno check and deno lint
6. Parallel agents, one coordinator. During the build, Claude Code agents worked in parallel, each owning a set of files (foundation, database, Edge Functions, workshop UI, public UI, hats and admin, docs). I coordinated them, reviewed and integrated their work, and ran it against the real project. That is why the first commits are large: parallel work landed in a few integration commits, followed by small fix commits.
7. Review, then verify. Independent review agents then audited compliance, security, AI, code, docs and UX, and their findings were fixed in follow-up commits. The core path (code map above) is the part to walk through line by line; walkthrough notes are in the docs.

---

#9. Build timeline (planned vs actual)

Cut on purpose (next steps): server-side speech-to-text for browsers without voice support, photos, QR images, ownership transfer emails, weaver management UI polish, payments, multiple workshops.

---

#10. Repository layout

app/                    Next.js routes: workshop, hats, weavers, runs, logs, settings (signed in);
                        /, /login, /signup, /forgot, /reset, /auth/confirm, /hat/[code], /docs (public)
components/             UI kit, shell, feature components
lib/                    Supabase clients, logger, auth, docs registry, security headers
supabase/
  migrations/           SQL schema, row-level security, functions, demo seed, fixes
  functions/
    _shared/            domain rules, tools (+ tools/), agent loop, apply checks, Gemini adapter, logger (pure TS, tested)
    workshop-agent/     agent loop (proposals only)
    apply-proposals/    validates and writes approved actions
    concierge/          public Q&A, no tools
scripts/                seed-users.mjs, eval-reset.mjs, verify-security.mjs, logs.ts (npm run ...)
evals/                  agent eval cases, runner and latest results
tests/                  Vitest (domain rules, tools, loop, UI logic, docs, headers)
docs/                   architecture, AI, security, engineering, evals, specs (also at /docs)
design_handoff_toquilla_trace/  clickable HTML prototypes + design spec (source of truth for UI)

---

#11. Run it locally

Runs the web app locally against the hosted Supabase project (no local database needed):

npm install
cp .env.example .env          # the project URL is already filled in; paste the anon key from the submission note
npm run dev                   # http://localhost:3000, log in with the demo accounts
npm test                      # unit tests, no network

Everything below is optional and needs project access (service role key in .env, the DB password in .db-password, the Supabase CLI via npx):

npx --yes supabase@2.121.0 link --project-ref mflvsnpyckuwhicvgnsr -p "$(< .db-password)"
npx --yes supabase@2.121.0 db push -p "$(< .db-password)"        # migrations
npm run seed:users                                                # demo + eval accounts (confirmed)
npx --yes supabase@2.121.0 functions deploy workshop-agent apply-proposals concierge \
  --project-ref mflvsnpyckuwhicvgnsr --use-api                    # Edge Functions
npx --yes supabase@2.121.0 secrets set GEMINI_API_KEY=...          # model key lives only here, never in .env or Vercel

Debugging and evals:

npm run logs -- --level error --since 1h     # app_logs from the terminal (service role, local only)
npm run logs -- --request req_8f2a91c4e2b7   # everything for one request
npm run eval:reset                           # put the Eval Workshop back to its seeded state
npm run eval                                 # agent eval cases against the deployed functions (results: docs/EVALS.md)
npm run verify:security                      # live RLS, grant and claim-flow checks (scripts/verify-security.mjs)

Demo accounts: see For reviewers.

---

#12. Status

---

#13. Notes on AI use

• The product uses Google Gemini (gemini-2.5-flash-lite) for both agents, not the Claude API (decision D26, model choice in AI.md).
• Claude Code was used to build it: research, planning, the design prompt, specs, and parallel coding agents that I coordinated, reviewed and integrated.
• Claude Design: first version of the UI from the design prompt. Revision 2 was reviewed and edited by hand.
• Me: problem choice, product decisions, scope, coordinating the agents, reviewing and running the result, and the final call on what ships.
• Planning and design happened before the 2-hour build window. The full AI-use note, including the hidden instruction on the take-home page, is in HANDOFF.md.