Merge branch 'main' into story-121/form-layout

Author: danielnaab

README.md

@@ -1,154 +1,140 @@
 # Forms Lab
 
-LLM-assisted forms platform for government forms. Upload a PDF, extract a
-structured spec, deliver a form experience (static or conversational), and
-generate a filled PDF back out.
-
-The core idea: **separate _what to collect_ from _how to present it_.** A
-`DataCollectionSpec` describes the fields and their semantics; a `FormSpec`
-describes how they are presented. Swap the presentation (static page,
-conversational chat, review layout) without touching the extraction pipeline,
-and swap the extraction strategy without touching delivery. Every LLM-powered
-step is a pluggable _variant_ that can be selected per user at runtime.
-
-## Live demo
-
-- **Dashboard** — [https://forms.labs.flexion.us/](https://forms.labs.flexion.us/) (deployment overview, branch list)
-- **Application** — [https://forms.labs.flexion.us/main/](https://forms.labs.flexion.us/main/) (main branch)
-- **Catalog** — [https://forms.labs.flexion.us/main/catalog](https://forms.labs.flexion.us/main/catalog)
-  (architecture, decisions, experiments, personas, stories, design system)
-- **Slide deck** — [https://forms.labs.flexion.us/main/presentation](https://forms.labs.flexion.us/main/presentation)
-
-Each active branch is deployed at `/<branch>/` alongside main.
-
-## Key findings
-
-Full write-ups live in the catalog. Headlines:
-
-1. **Hybrid-v1 Pareto-dominates prompt-only extraction.**
-   [`sonnet-hybrid-v1`](catalog/experiments/pdf-field-extraction/sonnet-hybrid-v1.md)
-   (one short instruction, one inline exemplar, temperature=0) wins four of
-   five metrics outright — precision 99.2%, recall 72.6%, sensitivity 51.1% —
-   and ties on type accuracy, at the same cost as baseline Sonnet. It is now
-   the production default. The prompt shape that topped the Assignment 10
-   tool-calling leaderboard on Mistral 8B reproduces on Claude Sonnet 4 for a
-   completely different task.
-
-2. **Tool-use is the structural precision/sensitivity lever.**
-   [`tool-use-sonnet`](catalog/experiments/pdf-field-extraction/tool-use-sonnet.md)
-   forces typed tool calls instead of free JSON: sensitivity accuracy jumps
-   27% → 79% (+51pp) and precision reaches 96.3%. Recall is step-limited at
-   20 rounds, so it shines on short-to-moderate forms.
-
-3. **Nova Pro marks the non-Claude capability boundary for extraction.**
-   [`nova-pro`](catalog/experiments/pdf-field-extraction/nova-pro.md) scored
-   97% on the homework's 10-field tool-calling task but extracts at 0.6%
-   recall here — it summarizes sections instead of enumerating fields. Prompt
-   engineering does not recover this. Model selection dominates prompt
-   engineering once the task is outside the model's capability range.
-
-4. **Model size is not the dominant lever for shaping.**
-   [Shaping model comparison](catalog/experiments/shaping-model-comparison/_suite.md):
-   Opus/Sonnet/Haiku all cluster around 67-73% command-kind precision.
-   Three intents are at ceiling across all three models; two fail across all
-   three. Prompt disambiguation (e.g. `renamePage` vs `renameGroup`) is the
-   bottleneck, not parameter count.
-
-Suite indexes:
+**Forms shouldn't be this hard.**
+
+Forms Lab is an experiment in making high-quality digital forms achievable for
+any public sector organization. It combines practical experience from federal
+forms work with LLM capabilities to collapse the cost of turning paper forms
+into accessible, modern experiences.
+
+## The problem
+
+Public sector organizations struggle to deliver good digital form experiences —
+not because they lack ambition, but because of structural barriers.
+Procurement timelines stretch months. Authority-to-operate processes add
+overhead. Custom development requires specialized talent that's hard to hire
+and expensive to retain. The result: forms stay locked in PDF, and the public
+bears the burden.
+
+## The approach
+
+**Configuration over code.** Forms are defined as structured JSON specs — what
+data to collect, how to present it, how fields map back to source documents.
+The specs are readable and editable by non-technical domain experts through a
+no-code UI, and equally accessible to LLM agents that can generate and refine
+them programmatically.
+
+**LLM assistance across the lifecycle.** Rather than bolting AI onto one step,
+Forms Lab introduces LLM capabilities at multiple stages — extracting fields
+from source PDFs, shaping raw extractions into usable form definitions,
+powering conversational form-filling, and generating accessible forms from
+regulatory source material. Each LLM-powered step is a pluggable _variant_:
+swappable at runtime, comparable in evaluation harnesses, improvable
+independently.
+
+**Git-native collaboration.** Every project is a git repository. Branches
+represent draft edits; merging publishes. This gives teams version history,
+diff-based review, and rollback — the same workflow developers already trust,
+extended to form content that non-developers manage through the UI.
+
+**Modern CSS with conformance testing.** The design system uses USWDS 3.x
+design tokens exclusively, enforced by automated stylelint rules. Cascade
+layers (`@layer`) provide predictable specificity. Conformance tests verify
+that our modern CSS implementation looks and behaves like USWDS — maintaining
+its well-tested patterns and accessibility guarantees even as the underlying
+approach evolves.
+
+**Evaluation-driven development.** LLM outputs are non-deterministic, so the
+platform includes structured evaluation harnesses that score extraction and
+shaping quality across fixture sets. This replaces "does it look right?" with
+measurable, reproducible comparisons between strategies.
+
+Experiment results and methodology:
 [PDF extraction](catalog/experiments/pdf-field-extraction/_suite.md) ·
 [Shaping](catalog/experiments/shaping-model-comparison/_suite.md) ·
-[Authoring pipeline](catalog/experiments/authoring-pipeline/_suite.md) ·
-[Roadmap](catalog/experiments/_roadmap.md)
+[Authoring pipeline](catalog/experiments/authoring-pipeline/_suite.md)
 
-## Quick start
+## Try it
+
+- **Live application** —
+  [https://forms.labs.flexion.us/main/](https://forms.labs.flexion.us/main/)
+- **Catalog** —
+  [https://forms.labs.flexion.us/main/catalog](https://forms.labs.flexion.us/main/catalog)
+  (architecture, decisions, experiments, design system)
+
+### Local development
 
 **Prerequisites:** [Bun](https://bun.sh/) 1.x or later.
 
 ```bash
 bun install
-bun run dev                # dev server at http://localhost:3000
-bun test                   # tests
-bun run check              # lint + type check + tests (run before push)
+bun run dev          # dev server at http://localhost:3000
+bun test             # tests
+bun run check        # lint + type check + tests (run before push)
 ```
 
 See [CLAUDE.md](CLAUDE.md) for the full command reference, session workflow,
-deployment architecture, and contribution conventions.
+and contribution conventions.
 
 ## Project layout
 
 ```
 src/
-├── entrypoints/           # Hono servers and CLI
-│   ├── app/               # Forms platform web app (routes, middleware, public)
-│   ├── dashboard/         # Deployment dashboard (homepage service)
-│   ├── webhook/           # GitHub webhook listener
-│   ├── notify/            # Notification delivery
-│   └── cli/               # CLI commands
-├── services/              # Domain services (one public entry per service)
-│   ├── data-collection/   # Core model: what to collect
-│   ├── forms/             # Resolution, delivery, sessions, shaping, filling
-│   ├── form-documents/    # PDF extraction, field mapping, filling
-│   ├── extraction/        # Extraction variant registry
-│   ├── evaluation/        # Evaluation harness and LLM-as-judge kinds
-│   ├── projects/          # Project service and form-project git repo
-│   ├── auth/              # GitHub OAuth, sessions
-│   ├── deployment/        # Deploy orchestration
-│   └── ...
-├── design-system/         # flex-* components (server-rendered JSX)
-└── shared/                # Pure utilities
-
-catalog/                   # Versioned catalog content (markdown/JSON)
-├── personas/              # Who the system serves
-├── stories/               # GitHub Issue copies (user stories)
-├── architecture/          # System docs
-├── decisions/             # ADRs
-└── experiments/           # LLM experiment suites + runs
-
-projects/                  # Form project directories (specs, assets)
-infrastructure/            # Pulumi (EC2) + NixOS (server config)
-test/                      # Bun test suite
+├── entrypoints/         # Hono servers and CLI
+│   ├── app/             # Forms platform web app
+│   ├── dashboard/       # Deployment dashboard
+│   ├── webhook/         # GitHub webhook listener
+│   └── cli/             # CLI commands
+├── services/            # Domain services (one public entry per service)
+│   ├── data-collection/ # Core model: what to collect
+│   ├── forms/           # Resolution, delivery, sessions, shaping, filling
+│   ├── form-documents/  # PDF extraction, field mapping, filling
+│   ├── extraction/      # Extraction variant registry
+│   ├── evaluation/      # Evaluation harness
+│   ├── projects/        # Project service and git repo
+│   └── auth/            # GitHub OAuth, sessions
+├── design-system/       # flex-* components (server-rendered JSX)
+└── shared/              # Pure utilities
+
+catalog/                 # Versioned catalog (architecture, decisions, experiments)
+infrastructure/          # Pulumi (EC2) + NixOS (server config)
 ```
 
 Dependencies flow one way: `shared → services/design-system → entrypoints`.
-Each service exposes its public API through `src/services/<name>/index.ts`
-and is enforced by `test/architecture/dependency-rule.test.ts`. See the
-[architecture principles](catalog/decisions/architecture/architecture-principles.md).
+See the [architecture principles](catalog/decisions/architecture/architecture-principles.md).
+
+## Origins
+
+This work began as a final project for Flexion's
+[LLMs In Production](https://www.manning.com/books/llms-in-production) class
+([cohort repo](https://github.com/flexion/llm-class-2026-winter-cohort);
+class outcome preserved on the
+[`final-project`](https://github.com/flexion/forms-lab/tree/final-project)
+branch). Development continues on `main`, building toward a scalable platform
+for public sector forms.
+
+Forms Lab builds on experience from the
+[10x Form Platform](https://github.com/gsa-tts/forms)
+([Flexion fork](https://github.com/flexion/forms)) — a GSA-funded initiative
+exploring reusable approaches to government forms digitization.
 
 ## Tech stack
 
 - **Runtime:** Bun
 - **Framework:** Hono (server-rendered JSX, no client runtime)
 - **Language:** TypeScript
-- **Testing:** Bun test
-- **Linting:** Biome + Stylelint (design-token enforcement)
+- **LLMs:** Claude (Opus/Sonnet/Haiku) via Anthropic SDK and AWS Bedrock
 - **Persistence:** Git-based — specs and catalog content live in the repo
-- **LLMs:** Claude (Opus/Sonnet/Haiku) via Anthropic SDK and AWS Bedrock;
-  Amazon Nova Pro for cross-provider comparison
-- **Deployment:** Pulumi + NixOS on EC2, branch-per-deployment via GitHub
-  webhook
-
-## Workflow
-
-Session commands (installed in `.claude/commands/`):
-
-```bash
-/create-story                # New user story (GitHub issue + notes dir)
-/start-story <description>   # Initialize a session (worktree, context)
-/finish-story                # Run checks, code review, open PR
-/review-story <PR>           # Review another session's PR
-```
-
-Infrastructure changes branch from main as `infra/YYYY-MM-DD-description`;
-feature work branches as `story-N/name` or `docs/<description>`. See
-[CLAUDE.md](CLAUDE.md) for commit conventions, the stacked branch workflow,
-and deployment details.
+- **Deployment:** Pulumi + NixOS on EC2, branch-per-deployment via GitHub webhook
 
 ## Contributing
 
-Class project for [LLM Class 2026 Winter Cohort](https://github.com/flexion/llm-class-2026-winter-cohort).
 Development follows vertical slicing: each user story delivers a complete,
 demoable capability through all layers. Tests are required for new
-functionality; `bun run check` must pass before push.
+functionality. `bun run check` must pass before push.
+
+See [CLAUDE.md](CLAUDE.md) for commit conventions, the stacked branch workflow,
+and deployment details.
 
 ## License
 

src/entrypoints/app/routes/catalog/index.tsx

@@ -66,12 +66,12 @@ catalog.get('/', async (c) => {
 
       <div class="l-stack" style="--stack-space: var(--flex-space-xl)">
         <section>
-          <p class="catalog-group-label">Presentation</p>
+          <p class="catalog-group-label">Presentations &amp; walkthroughs</p>
           <div class="l-grid" style="--grid-min: 280px">
             <ContentCard
               title="Slide Deck"
               href={resolveUrl('/presentation')}
-              description="15-minute live presentation — narrative arc, key findings, and demo"
+              description="Final project presentation for Flexion's LLMs In Production class — narrative arc, key findings, and live demo"
             />
             <ContentCard
               title="Walkthrough"