docs: tighten README, demo copy, and ignore local agent dirs

thribhuvan003 · thribhuvan003 · commit 0e4b909ba79c · 2026-07-25T22:58:24.000+05:30
diff --git a/.gitignore b/.gitignore
@@ -50,3 +50,13 @@ coverage/
 # scratch / MCP tooling dirs
 .playwright-mcp/
 mcps/
+
+# local agent / IDE tooling (do not ship in the product tree)
+.agents/
+.claude/
+.cursor/
+.grok/
+skills-lock.json
+MEMORY.md
+ERRORS.md
+.mcp.json
diff --git a/README.md b/README.md
@@ -1,171 +1,117 @@
 # Unhold
 
-**Guided case workspace for bank-account and UPI restrictions in India.**
+**Organise a bank-account or UPI freeze case in India. Draft a letter. You send it.**
 
-Live: [unhold.live](https://www.unhold.live) · Demo (no account): [unhold.live/demo](https://www.unhold.live/demo)
-
-Unhold turns a freeze into a structured file: what happened, which papers you have, what to ask next, and a letter you can copy or print. **You send everything.** The product never emails a bank, police station, or regulator, and never claims an account will be released.
+| | |
+|---|---|
+| Live | [unhold.live](https://www.unhold.live) |
+| Demo (no account) | [unhold.live/demo](https://www.unhold.live/demo) |
+| Start a case | [unhold.live/start](https://www.unhold.live/start) |
+| Open a saved case | [unhold.live/open-case](https://www.unhold.live/open-case) |
+| Health | [unhold.live/healthz](https://www.unhold.live/healthz) |
 
 [![CI](https://github.com/thribhuvan003/unhold/actions/workflows/ci.yml/badge.svg)](https://github.com/thribhuvan003/unhold/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
----
+Unhold is a case file for a restricted account: facts, papers, next steps, and a letter you can copy or print. **Nothing is emailed to a bank, police station, or regulator on your behalf.** No unfreeze guarantee.
 
-## For reviewers (≈3 minutes)
+---
 
-1. Open the [worked example](https://www.unhold.live/demo) at a phone width.
-2. Read the server-only data boundary in [`supabase/migrations/20260713194008_server_only_data_boundary.sql`](supabase/migrations/20260713194008_server_only_data_boundary.sql) and the escalation gates in [`lib/escalations/proof-gates.ts`](lib/escalations/proof-gates.ts).
-3. From a clean checkout: `pnpm install --frozen-lockfile && pnpm verify`.
+## Try it in three minutes
 
-That path exercises lint, TypeScript strict mode, unit + contract tests, the no-auto-send guard, and a production build.
+1. Phone width → open the [demo](https://www.unhold.live/demo).
+2. Skim the safety boundary: [`docs/PRODUCT_AND_SAFETY.md`](docs/PRODUCT_AND_SAFETY.md).
+3. From a clean clone: `pnpm install --frozen-lockfile && pnpm verify`.
 
 ---
 
-## What it does
+## What you get
 
-| Area | Behaviour |
+| Step | What happens |
 | --- | --- |
-| Intake | Short questions → structured case facts. Guest flow with a recovery code; no mandatory signup. |
-| Evidence | Private storage, SHA-256 confirm, consent-gated extraction, human review when confidence is low. |
-| Drafts | Case-aware letter text from recorded facts. Citations limited to a maintained allowlist. |
-| Escalation | Later steps stay locked until required earlier proof exists (deterministic gates). |
-| Follow-up | Idempotent jobs, monitored deadlines, full case history across devices. |
-| Control | Copy / print / open-mail only. Nothing is sent on the user’s behalf. |
+| Start | Short questions. Guest session + recovery code. No forced signup. |
+| Papers | Private upload, hash check, readable/unreadable flags. You still re-read every file. |
+| Letter | Draft from your answers. You fill blanks, then copy / print / open mail yourself. |
+| Later steps | Locked until earlier send-proof is on file. |
+| Follow-up | Reminders only if you opt in. Full history if you reopen the case. |
 
-Product language and non-negotiables: [`docs/PRODUCT_AND_SAFETY.md`](docs/PRODUCT_AND_SAFETY.md).
+If someone is losing money to active fraud right now: **1930**.
 
 ---
 
-## Safety boundary
-
-Unhold is a document-organisation tool, not a law firm, bank, or government service. Freeze rules differ by authority, bank, and facts. The UI labels uncertainty, attaches sources and review dates to legal positions, and avoids release guarantees or fixed timelines.
-
-If someone is in immediate danger of fraud loss, the public cyber helpline in India is **1930**.
-
----
+## How it is built
 
-## Architecture
-
-```mermaid
-flowchart LR
-  Browser["Browser: session + UI"] --> API["Next.js API routes"]
-  API --> DB["Supabase Postgres"]
-  API --> Store["Private object storage"]
-  API --> Queue["agent_jobs queue"]
-  Queue --> Agents["Intake · Verifier · Drafter · Bundle · Escalator"]
-  Monitor["Cron + on-demand kick"] --> Queue
-  Agents --> Gates["Zod + redaction + proof gates"]
+```text
+Browser  →  Next.js (app + /api/v1)  →  Supabase (Postgres + private storage)
+                                  ↘  agent_jobs (classify / OCR / draft)
 ```
 
-**Data plane**
-
-- Browser Supabase client is used for **auth only**.
-- Application tables and RPCs are not granted to `anon` / `authenticated`.
-- Authorised server routes use the service role after owner / collaborator / operator checks.
-- Evidence and sealed bundles live in private buckets; uploads are size- and type-constrained.
-
-**Agent plane**
-
-- Jobs are idempotent, claimed with a DB lock, retried with bounded backoff, and dead-lettered after max attempts.
-- Model output is untrusted until it passes schema validation, citation controls, redaction, and the relevant proof gate.
-- Deterministic templates keep the core letter path usable when a provider is down.
-
-**Upload / OCR path (latency)**
-
-- Large phone photos are resized in the browser before PUT.
-- Confirm returns after integrity checks; vision OCR runs after the response (`after()` + queue kick).
-- Vision inputs are downscaled server-side; HEIC/WebP are normalised to JPEG when needed.
-
-### Model routing
-
-| Workload | Primary | Fallback |
-| --- | --- | --- |
-| Text (classify / draft) | Groq `openai/gpt-oss-120b` | NVIDIA `meta/llama-3.3-70b-instruct` |
-| Vision (document OCR) | Groq `qwen/qwen3.6-27b` | NVIDIA `minimaxai/minimax-m3` |
-| Embeddings (retrieval) | NVIDIA `nvidia/nv-embedqa-e5-v5` | Template path (no model) |
-
-### Stack
+- Browser talks to Supabase for **auth only**. Case data goes through server routes.
+- Jobs are claimed with a DB lock, retried with backoff, and reclaimed if a worker dies.
+- Templates cover the letter path when a model provider is down.
 
 | Layer | Choice |
 | --- | --- |
-| App | Next.js 16 (App Router), React 19, TypeScript strict |
+| App | Next.js 16, React 19, TypeScript strict |
 | Data | Supabase Postgres + private Storage |
-| Jobs | DB queue; GitHub Actions every 5 minutes + request-time kick |
-| Edge | Vercel, region `bom1` (Mumbai) |
-| i18n | English + Hindi (`next-intl`) |
-| Limits | Upstash Redis when configured; in-memory fallback locally |
+| Host | Vercel `bom1` (Mumbai) |
+| Jobs | DB queue + GitHub Actions every 5 minutes + request kick |
+| Languages | English + Hindi |
 
-Hobby-plan cron limits and external drain wiring: [`docs/DEPLOY_VERCEL_HOBBY.md`](docs/DEPLOY_VERCEL_HOBBY.md).
+Deploy notes for Hobby cron limits: [`docs/DEPLOY_VERCEL_HOBBY.md`](docs/DEPLOY_VERCEL_HOBBY.md).
 
 ---
 
-## Local setup
+## Local
 
-**Requires:** Node.js ≥ 22.14, pnpm 10.12.1.
+Node ≥ 22.14 · pnpm 10.12.1
 
 ```bash
 git clone https://github.com/thribhuvan003/unhold.git
 cd unhold
 pnpm install --frozen-lockfile
-cp .env.example .env.local
-# fill local/test values only — never commit a filled env file
+cp .env.example .env.local   # local values only — never commit secrets
 pnpm dev
 ```
 
-Environment catalogue: [`config/VERCEL_ENV_KEYS.md`](config/VERCEL_ENV_KEYS.md).  
-Apply SQL under `supabase/migrations/` in order against your project before exercising auth or storage.
-
----
-
-## Verification
+Env keys: [`config/VERCEL_ENV_KEYS.md`](config/VERCEL_ENV_KEYS.md).  
+Apply `supabase/migrations/` in order before testing auth or storage.
 
 ```bash
-pnpm verify             # lint · types · unit · contracts · no-auto-send · build
-pnpm test:e2e:smoke     # Playwright smoke (desktop + mobile)
-pnpm test:e2e           # full browser suite
+pnpm verify           # lint · types · unit · contracts · no-auto-send · build
+pnpm test:e2e:smoke   # Playwright smoke
 ```
 
-CI runs the same deterministic checks on every PR and on pushes to `main`, plus secret scanning and smoke tests. Do not treat a green badge as a substitute for reading the safety contract.
-
-Health (JSON, no auth): `GET https://www.unhold.live/healthz` or `/api/v1/health`.
-
 ---
 
-## Repository layout
+## Layout
 
 ```text
-app/                 App Router UI + versioned /api/v1 routes
-components/          Mobile-first case UI
-lib/agents/          Intake, verifier, drafter, evidence, monitor, escalator
-lib/api/             Authz, errors, request contracts
-lib/escalations/     Deterministic proof gates
-lib/jobs/            Enqueue, claim, process, on-demand kick
-lib/evidence/        Hash, mime, compress, vision prep
-supabase/migrations/ Schema, RLS, storage, privileges
-tests/unit/          Domain + golden fixtures
-tests/contract/      API and migration contracts
-tests/e2e/           Journeys + a11y smoke
-docs/                Product safety, deploy, research notes
+app/                 UI + /api/v1
+components/          Case UI
+lib/                 Domain, jobs, evidence, gates
+supabase/migrations/ Schema and policies
+tests/               unit · contract · e2e
+docs/                Product safety, deploy
+messages/            en + hi copy
 ```
 
 ---
 
-## Status and limitations
+## Limits (honest)
 
-Public beta **0.1.0**. Expect sharp edges; report them via issues or [security advisories](SECURITY.md).
+Public beta **0.1.0**.
 
-- The user must verify extracted fields and send every letter themselves.
+- You verify extracted fields and send every letter.
 - Process guidance can go stale; dated sources are not personal legal advice.
-- Model reads can be wrong; low-confidence or inconsistent files are flagged for review.
-- Whether an account moves, and when, is decided only by the bank and the ordering authority.
+- Document reads can be wrong; low-confidence files are flagged.
+- Only the bank and ordering authority decide if an account moves.
 
 ---
 
-## Security and contributing
+## Security · contributing
 
-- Vulnerabilities: private report only — [`SECURITY.md`](SECURITY.md).
-- Changes: [`CONTRIBUTING.md`](CONTRIBUTING.md). Prefer safer, clearer, more reliable behaviour over new claims.
-
----
+- Vulnerabilities: [`SECURITY.md`](SECURITY.md) (private report).
+- Patches: [`CONTRIBUTING.md`](CONTRIBUTING.md). Prefer safer and clearer over louder claims.
 
-MIT License · Maintained by [thribhuvan003](https://github.com/thribhuvan003)
+MIT · [thribhuvan003](https://github.com/thribhuvan003)
diff --git a/app/[locale]/demo/page.tsx b/app/[locale]/demo/page.tsx
@@ -53,7 +53,7 @@ export default async function DemoPage({ params }: Props) {
   const path = getUnfreezePath("cyber_upi_chain", locale);
 
   return (
-    <div className="mx-auto flex max-w-[430px] flex-col gap-4 lg:max-w-2xl">
+    <div className="u-case-shell mx-auto flex w-full flex-col gap-4">
       {/* Lead with the killer insight in plain words, not a caveat — all three
           comprehension reviewers (HRs + a normal user) said the value was buried
           under a legal briefing. State it first; let the cards below be the proof. */}
diff --git a/components/evidence/PapersChecklist.tsx b/components/evidence/PapersChecklist.tsx
@@ -57,7 +57,7 @@ const DEFAULT_CORE_DOCS: PaperDocDef[] = [
   {
     type: "freeze_sms",
     label: "Freeze SMS or notice",
-    why: "Shows when and how the bank froze it. The starting point for any letter. AI also explains what it means.",
+    why: "Shows when and how the bank froze it. Starting point for any letter.",
     term: "freeze intimation",
     article: "a",
     kindLabel: "freeze SMS or notice",
diff --git a/messages/en.json b/messages/en.json
@@ -59,7 +59,7 @@
       },
       {
         "title": "Add the papers for your case",
-        "desc": "Clear photos or PDFs of what your checklist asks for. Unhold checks readability; you still review the original."
+        "desc": "Clear photos or PDFs of what your checklist asks for. You still re-read every file yourself."
       },
       {
         "title": "Get a draft letter + proof pack",
@@ -417,38 +417,38 @@
   },
   "DemoPage": {
     "eyebrow": "Worked example · made-up facts",
-    "title": "See the input, the decision, and the draft — before starting a case.",
-    "intro": "This is a sample walkthrough, not your case. It shows what Unhold organises, what it suggests next, and the kind of letter draft you review. It does not decide who can release funds or predict an outcome.",
-    "sampleNote": "Sample only: Asha Rao · ₹1,800 shown as affected · total restriction after an unexpected UPI credit · NCRP reference available. Nothing is sent.",
-    "truthTitle": "Read this once so the demo does not mislead",
+    "title": "What Unhold produces — before you start a real case.",
+    "intro": "Sample walkthrough only. Not your case. Shows facts → next step → a letter draft you would review. Does not decide who can release funds.",
+    "sampleNote": "Sample: Asha Rao · ₹1,800 held · total freeze after an unexpected UPI credit · NCRP on file. Nothing is sent.",
+    "truthTitle": "So the demo is not misleading",
     "truthPoints": [
-      "This letter is a draft template filled with sample facts — not a lawyer-signed document.",
-      "Your real letter uses your answers (freeze type, role, authority type, amount). Court and tax drafts ask different things than cyber drafts.",
-      "You always send the letter yourself. Unhold never emails the bank or police."
+      "The letter is a filled template with sample facts — not a lawyer document.",
+      "A real draft uses your answers. Court and tax freezes ask different things than cyber freezes.",
+      "You send every letter yourself. Unhold never emails the bank or police."
     ],
-    "proofTitle": "What changed from input to output",
+    "proofTitle": "From input to output",
     "proofSteps": [
       {
         "label": "INPUT",
-        "text": "Asha’s stated facts, restriction type, amount, date and available NCRP reference."
+        "text": "Asha’s facts: freeze type, amount, date, NCRP reference."
       },
       {
         "label": "DECISION",
-        "text": "Ask for the written scope, ordering authority and official next step; do not assume the branch can release it."
+        "text": "Ask in writing for scope, ordering authority, and the official next step — do not assume the branch can release the money."
       },
       {
         "label": "OUTPUT",
-        "text": "A concise L1 draft, a relevant paper checklist and dated official contact sources for Asha to verify."
+        "text": "L1 draft, paper checklist, dated official contact sources for her to verify."
       }
     ],
-    "sourcesTitle": "Official links and dated contact checks",
-    "sourcesDesc": "Contacts are linked to their published source. Legal outcomes still depend on the actual order, facts and jurisdiction:",
+    "sourcesTitle": "Official links (dated)",
+    "sourcesDesc": "Each contact points at its published source. Outcomes still depend on the real order and facts:",
     "sourceLabel": "SBI official page",
-    "letterTitle": "Sample draft letter (you would review and send)",
-    "letterDesc": "Summary first. Open the full draft to see every line. On a real case you fill any blanks before sending.",
-    "letterFactNote": "total restriction · ₹1,800 · unexpected UPI credit · NCRP reference provided",
-    "ctaTitle": "Your case won’t look like Asha’s.",
-    "ctaBody": "The path and letter adapt to what you enter. After you start, write down the recovery code — that is how you reopen the case on another phone.",
+    "letterTitle": "Sample draft (review before send)",
+    "letterDesc": "Summary first. Open the full draft for every line. On a real case you fill blanks before sending.",
+    "letterFactNote": "total freeze · ₹1,800 · unexpected UPI credit · NCRP provided",
+    "ctaTitle": "Your case will not match Asha’s.",
+    "ctaBody": "Path and letter follow what you enter. After you start, save the recovery code — that is how you reopen on another phone.",
     "startCta": "Start my own case",
     "backHome": "Back to home"
   },
diff --git a/messages/hi.json b/messages/hi.json

Original file line number	Diff line number	Diff line change
`@@ -57,7 +57,7 @@ const DEFAULT_CORE_DOCS: PaperDocDef[] = [`
`57`	`57`	`{`
`58`	`58`	`type: "freeze_sms",`
`59`	`59`	`label: "Freeze SMS or notice",`
`60`		`- why: "Shows when and how the bank froze it. The starting point for any letter. AI also explains what it means.",`
	`60`	`+ why: "Shows when and how the bank froze it. Starting point for any letter.",`
`61`	`61`	`term: "freeze intimation",`
`62`	`62`	`article: "a",`
`63`	`63`	`kindLabel: "freeze SMS or notice",`