Toquilla TraceDocsGitHub
docs/README.mdView on GitHub

Docs index

Every document in the repo, one line each, plus a suggested reading order. Live app: https://toquilla-trace.vercel.app

Read them in the app

The main docs also render inside the app at /docs, no login needed. Pages are built once from the repo markdown (app/docs/, list of pages in lib/docs/registry.ts):

In-app pageSource file
/docs/overviewREADME.md
/docs/handoffHANDOFF.md
/docs/guidethis file
/docs/architectureARCHITECTURE.md
/docs/aiAI.md
/docs/securitySECURITY.md
/docs/engineeringENGINEERING.md
/docs/evalsEVALS.md
/docs/specs, plus one page per spec (/docs/specs-00-conventions to /docs/specs-10-quality-evals-and-delivery)specs/README.md and specs/NN-*.md
/docs/designdesign_handoff_toquilla_trace/README.md

The rest (EDGE, FOUNDATION, the UI docs, seed notes) are only in the repo.

Suggested reading order

Same order as the /docs index in the app.

10 minutes:

  1. README.md: start with "For reviewers" (demo accounts, 3-minute tour, the 8 core files), then the problem and the decision log.
  2. HANDOFF.md: what works, what is missing, how to run it, AI-use note.
  3. SECURITY.md: the demo-password note at the top, then the TL;DR.
  4. ARCHITECTURE.md: how the pieces fit and where each rule lives.
  5. AI.md: where AI is used, how it is boxed in, and the model choice.

45 minutes: the 10-minute list, then:

  1. ENGINEERING.md: tests, quality gates, logging, delivery, known gaps. The current test and build numbers live only there.
  2. EVALS.md: the measured agent score and why cases failed. Eval numbers live only there.
  3. specs/README.md and specs/00-conventions.md sections 8 and 9: the decisions (D1 to D26) that override the pre-build plan.
  4. Optional: EDGE.md for the Edge Function contracts, specs/05-domain-rules.md for the numbered rule cases.

All documents

Start here

DocWhat it is
README.mdProduct overview: problem, solution, principles, architecture sketch, decision log
HANDOFF.mdHandoff note: live link, demo accounts, what works, what is incomplete, AI-use note

How it is built

DocWhat it is
ARCHITECTURE.mdSystem design, data flow, where each rule is enforced, how to extend it
AI.mdAgent and concierge design, guardrails, model choice
EVALS.mdEval results against the deployed functions: per-case table, cost, latency, the failures and what changed
SECURITY.mdAuthentication, authorization (RLS), data safety, AI safety, secrets, security headers
ENGINEERING.mdEngineering practices: conventions, types, tests, quality gates, logging, delivery, AI-assisted workflow, gaps
EDGE.mdThe workshop-agent, apply-proposals and concierge Edge Functions: contracts, env, deploy, smoke test
FOUNDATION.mdBuild notes: the scaffold guide given to feature agents (versions, file map at scaffold time, aliases, deviations from the specs)
../supabase/seed-notes.mdDatabase notes: migrations, triggers, SQL functions, demo seed and users

UI (build notes written during implementation; may be outdated)

DocWhat it is
UI-WORKSHOP.mdLogin, signup, forgot password and the workshop screen (composer and proposals)
UI-PUBLIC.mdLanding page, public passport, claim and buyer concierge
UI-HATS-ADMIN.mdHats, Weavers, Settings, admin Logs and Agent runs, plus npm run logs and npm run eval
../design_handoff_toquilla_trace/README.mdDesign handoff (revision 2): the UI source of truth, with clickable HTML prototypes

Planning (written before the timed build)

DocWhat it is
specs/README.mdWhat we expect to be judged on, and the list of feature specs
specs/00-conventions.mdShared stack, schema, contracts, logging rules and the final decisions D1 to D26
specs/01-auth-and-roles.md to specs/10-quality-evals-and-delivery.mdOne spec per feature, each with scope (Must, Nice, Cut), tests and acceptance criteria
design-prompt.mdHistorical: the prompt that produced the first design
boilerplate.mdThe Claude Code guardrail setup this repo started from