docs: professional, judge-ready README for Cursor Hack

[trenchsheikh]

Summary

Rewrites the root README.md as a clean, professional, judge-friendly overview of the UnderWriter Cursor Hack project. The previous README was developer-focused and missed the demo narrative, the technology surface area, and the visual flow that makes the project click in 30 seconds.

The new README leads with the pitch, makes the technology stack immediately scannable, and uses three Mermaid diagrams to walk through the architecture, the streaming run lifecycle, the six desks, and the amendment PR loop.

What's in the new README

• Hero block with project tagline, one-paragraph pitch, and badge row for the headline technologies (Cursor SDK · Composer 2, Next.js 16, React 19, TypeScript, OpenAI GPT-5.5, Specter MCP).
• Why this matters — a problem/answer table that grounds the demo in real-world pain (BEC = $2.7B/yr, two-week diligence slog, mandate drift).
• Technology stack — a single table grouped by layer (agent runtime, backend, data sources, frontend, validation, mandate, resilience, mock rails) with a one-line "why" for each.
• Four Mermaid diagrams, each with a different lens:
  1. System architecture — UI → API → orchestrator → desks → sources → Cursor SDK amendment loop.
  2. Sequence diagram — the full run lifecycle including SSE event names, parallel desk fan-out, verdict synthesis, memo generation, and the override → amendment branch.
  3. Six desks at a glance — desks, their data sources, the verdict layer, and the proceed/hold split.
  4. Amendment loop — the agent edits the agent (block → override → Composer 2 → PR → review → merged mandate enforced by Desk 05).
• Quick start for backend + smoke + frontend (port 3001 / 3000), with the curl smoke kept inside a collapsible <details> block so the diagrams stay above the fold.
• API table, demo scenarios (Clean Acme PROCEED vs BEC Acme HOLD), project layout tree, configuration (highlighting DEMO_FORCE_FIXTURES), design principles (lifted from ARCHITECTURE.md), what this deliberately does not do, and credits.

Why this is judge-ready

• Skim path: tagline → pitch → why-it-matters table → tech-stack table → diagrams. A judge can grade in under 90 seconds without scrolling past one screen height before getting to a diagram.
• All technologies are surfaced: Cursor SDK + Composer 2 + MCP, OpenAI GPT-5.5, Specter, Companies House, OpenSanctions, WHOIS, Next.js 16, React 19, TypeScript, Zod, gray-matter, SSE, mailauth/pdf-parse, in-memory ledger.
• Diagrams are Mermaid, so they render natively in GitHub's PR/README view — no image hosting, always in sync with the prose.
• The amendment loop is called out as its own diagram, because that's the structural insight ("the agent edits the agent") that wins category prizes.
• Honest framing kept: fixture fallbacks, mock ledger, no real money, no email send — judges respect explicit scope.

Files changed

• README.md — full rewrite (+364 / −41).

No code, fixtures, dependencies, or build configuration changed.

Slack Thread