# TESTDRIVE-SPEC.md — Pure Test Drive back end (for Code)
**Design owns the FE** (`pure-testdrive.html` + `pure-testdrive-admin.html`, live, fail-soft). Code owns the sandbox + RPCs. Contract-first; idempotent; audited.

## Tables
```sql
create table if not exists public.pure_testdrive_envs (
  id uuid primary key default gen_random_uuid(),
  name text not null,                 -- "Dave"
  email text default '',
  role text default '',               -- agent|broker|mls|assoc|''(pick)
  txn  text default '',               -- seller|buyer|landlord|''(pick)
  auth text not null default 'guest'  -- guest | full
    check (auth in ('guest','full')),
  token text unique,                  -- opaque link token (guest)
  org_id uuid,                        -- scoped demo org (isolated, RLS)
  status text default 'active',       -- active | trashed
  created_by text, created_at timestamptz default now(), last_seen timestamptz
);
-- Demo rows live in a scoped org so trashing = delete where org_id = env.org_id.
-- All seeded rows carry is_demo=true (existing convention) as a backstop.
```

## RPCs (SECURITY DEFINER, admin-gated, audited)
| RPC | Args | Effect |
|---|---|---|
| `mcp_td_issue` | `name,email,role,txn,auth` | create env + scoped demo org + seed sample deal/docs; if `auth='full'` provision a Supabase auth user + MFA enroll invite; return `{id,token,url}`. |
| `mcp_td_list` | — | active envs for the admin panel. |
| `mcp_td_reset` | `user` \| `id` | delete all demo data for that env's org (trash); keep or remove the env row. |
| `mcp_report_extract` | `doctype,file`\|`{sample:true}` | Claude-vision field extraction → `{fields:[{label,value}]}` written to the doctype's target table (see `SECURITY`/`PURE_DATAENTRY`: contract→pure_offers, utility→pure_utility_bills, appraisal→pure_appraisals, inspection→pure_inspections, id→pure_identity_docs, financial→pure_financials, mortgage→pure_loan_apps, legal→pure_legal_forms, generic→pure_documents). Powers real doc-runs in Test Drive + Pure Ingest. |

## Auth
- **Guest (no password):** link `/pure-testdrive.html?u=Name&mode=guest[&role&txn]` works immediately; token-scoped read/write to the demo org only (anon key + RLS on `org_id`).
- **Full + MFA:** `mode=full` routes through sign-in; `mcp_td_issue` pre-provisions the user + `mfa_required=true` (reuses the existing MFA enroll flow, pure-mfa.html).

## Wiring
- Admin panel = **Test Drive tab in `pure-admin-console`** (Shattique). Add nav entry → `pure-testdrive-admin.html`.
- Trash-when-done is the `mcp_td_reset` call (FE already invokes it; fail-soft to localStorage today).
- Isolation: demo orgs never touch real client data (no real PII until auth window — CLAUDE canon).

## Change log
- 2026-06-30 — Lane A: FE live (core + admin issuer), fail-soft; this spec hands the sandbox + RPCs to Code.