feat: update with Claude-extracted benchmarks and UI fixes

- Re-extracted benchmarks.json using Claude Sonnet (15 patterns, 34 insights)
- Fixed form field text visibility (text-gray-900)
- Added CLAUDE.md and architecture docs
- Updated README with report generation details

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,45 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm run dev          # start dev server at localhost:3000
+npm run build        # production build (uses standalone output for Docker)
+npm run lint         # eslint
+npx tsc --noEmit     # type-check without building
+npm run extract      # run PDF → benchmarks.json extraction (requires Ollama or HF)
+```
+
+## Environment
+
+Copy `.env.local.example` to `.env.local` before running locally. Ollama must be running (`ollama serve`) with `llama3.1:8b` pulled.
+
+The LLM provider is swapped entirely via env vars — no code changes needed:
+- **Local (Ollama):** `OLLAMA_BASE_URL=http://localhost:11434/v1`, `LLM_MODEL=llama3.1:8b`
+- **HF Spaces:** `OLLAMA_BASE_URL=https://router.huggingface.co/v1`, `LLM_MODEL=Qwen/Qwen2.5-72B-Instruct`, `OPENAI_API_KEY=hf_...`
+- **OpenAI:** set `OPENAI_API_KEY`, `LLM_MODEL=gpt-4o`, remove `OLLAMA_BASE_URL`
+
+## Architecture
+
+The app has two distinct flows:
+
+**One-time setup:** `scripts/extract-knowledge.ts` reads PDFs from `data/pdfs/`, chunks text into ~8000-char pieces, sends each to the LLM, merges results into `data/benchmarks.json` (47 patterns, 124 insights from 3 DORA reports). This file is committed and bundled into the Docker image — the script does not run at runtime.
+
+**Request flow:** Browser form (`app/page.tsx`, two steps) → POST `/api/interpret` → `lib/benchmarks.ts` loads `benchmarks.json` (cached in memory) → `lib/prompts.ts` builds system prompt with benchmark data → `lib/llm.ts` calls LLM via OpenAI-compatible client → response validated with `InterpretationReportSchema` (Zod) → JSON returned → stored in `sessionStorage` → `app/report/page.tsx` reads and renders report.
+
+**LLM abstraction:** All LLM calls go through `lib/llm.ts`, which wraps the `openai` npm package. The provider is controlled entirely by `OLLAMA_BASE_URL`, `OPENAI_API_KEY`, and `LLM_MODEL` env vars. The OpenAI client's `baseURL` is set to `OLLAMA_BASE_URL`, making any OpenAI-compatible endpoint (Ollama, HF router, Groq, OpenAI) work without code changes.
+
+## Key constraints
+
+- `lib/schema.ts` defines both input schemas (`MetricsInputSchema`, `TeamContextSchema`) and output schema (`InterpretationReportSchema`). The API route validates both directions — 400 for bad input, 422 if the LLM returns a malformed report.
+- `lib/benchmarks.ts` sanitizes `data/benchmarks.json` before Zod validation (Ollama sometimes returns arrays instead of strings in pattern fields).
+- `next.config.ts` sets `output: 'standalone'` (required for Docker) and `serverExternalPackages: ['pdf-parse']`.
+- `tsconfig.json` has a `"ts-node"` override block with `module: "CommonJS"` so scripts in `scripts/` can use `require`-style resolution while the Next.js app uses bundler resolution.
+- The `sessionStorage` key is defined in `lib/constants.ts` as `REPORT_SESSION_KEY` — use that constant, not the string literal.
+- Print/PDF export uses `window.print()` with `@media print` CSS in `globals.css`. Elements to hide during print get the `print-hide` class.
+
+## Deployment
+
+The app is deployed on HuggingFace Spaces at `rdlf/devops-metrics-interpreter`. To update, push to the `hf-deploy` branch (orphan, no PDF history) and force-push to `hf:main`. Do not push `data/pdfs/` — those files exceed HF's 10MB limit and are gitignored.

README.md

@@ -11,6 +11,22 @@ pinned: false
 
 Enter your team's DevOps metrics and get a plain-language interpretation compared to DORA benchmark data from the State of DevOps Reports.
 
+## How report generation works
+
+Reports are generated by combining three sources of knowledge, all extracted from the State of DevOps Report PDFs and stored in `data/benchmarks.json`:
+
+1. **Benchmark tiers** — elite/high/medium/low bands for the four DORA metrics (deployment frequency, lead time, change failure rate, MTTR)
+2. **47 patterns** — metric combinations and what they signal (e.g. high deploy frequency + high failure rate → missing release safeguards)
+3. **124 key insights** — statistics and findings from the reports (e.g. "elite performers deploy 208x more frequently than low performers")
+
+All three are injected into the LLM's system prompt on every request alongside the team's submitted metrics. The LLM is instructed to reference benchmark bands explicitly and ground its improvement recommendations in the extracted knowledge.
+
+Report quality depends on what was captured during extraction. To re-extract with a better model:
+
+```bash
+LLM_MODEL=gpt-4o npm run extract
+```
+
 ## Running locally
 
 ```bash
@@ -24,6 +40,6 @@ npm run dev
 
 | Variable | Value |
 |----------|-------|
-| `OLLAMA_BASE_URL` | `https://api-inference.huggingface.co/models/meta-llama/Meta-Llama-3.1-8B-Instruct/v1` |
+| `OLLAMA_BASE_URL` | `https://router.huggingface.co/v1` |
 | `OPENAI_API_KEY` | Your HuggingFace token (`hf_...`) |
-| `LLM_MODEL` | `tgi` |
+| `LLM_MODEL` | `Qwen/Qwen2.5-72B-Instruct` |

data/benchmarks.json

@@ -1,607 +1,229 @@
 {
   "deploymentFrequency": {
-    "elite": "On Demand (multiple deploys per day)",
-    "high": "Between once per day and once per week",
-    "medium": "Between once per week and once per month",
-    "low": "Between once per month and once every six months"
+    "elite": "On demand — multiple deploys per day (19% of teams in 2024)",
+    "high": "Between once per day and once per week (22% of teams in 2024)",
+    "medium": "Between once per week and once per month (35% of teams in 2024)",
+    "low": "Between once per month and once every six months (25% of teams in 2024)"
   },
   "leadTime": {
-    "elite": "Less than one day (50%) / Less than one hour (40%)",
-    "high": "1w - 1m (40%) / 1d - 1w (30%)",
-    "medium": "1d - 1w (20%) / < 1d (10%)",
-    "low": "Once per month and once per six months"
+    "elite": "Less than one day",
+    "high": "Between one day and one week",
+    "medium": "Between one week and one month",
+    "low": "Between one month and six months"
   },
   "changeFailureRate": {
     "elite": "5%",
     "high": "20%",
-    "medium": "10%",
+    "medium": "10% (note: medium cluster can have low CFR but poor throughput)",
     "low": "40%"
   },
   "mttr": {
-    "elite": "Less than one hour (50%) / On Demand (40%)",
-    "high": "1w - 1m (30%) / 1d - 1w (20%)",
-    "medium": "1d - 1w (10%) / < 1d (10%)",
-    "low": "Once per month and once per six months"
+    "elite": "Less than one hour",
+    "high": "Less than one day",
+    "medium": "Less than one day",
+    "low": "Between one week and one month"
   },
   "patterns": [
     {
-      "id": "Transformational leadership",
-      "signature": "high levels of transformational leadership are linked to high performance",
-      "interpretation": "Teams with transformational leaders tend to have high levels of employee productivity, job satisfaction, and team performance.",
+      "id": "high-freq-high-failure",
+      "signature": "high deployment frequency + high change failure rate (>20%)",
+      "interpretation": "The team deploys often but lacks sufficient quality gates. High velocity without stability is a sign of missing automated test coverage, insufficient code review rigour, or deploying too-large changesets. This is the most dangerous quadrant — frequent failures erode user trust and engineer morale quickly.",
       "improvements": [
-        "Invest in transformational leadership development",
-        "Develop a culture of open communication and collaboration"
+        "Add automated test gates to the CI pipeline — block deployments that reduce coverage",
+        "Reduce changelist size using trunk-based development with short-lived feature branches",
+        "Introduce feature flags to decouple deployment from release, allowing safer deploys",
+        "Conduct blameless post-mortems on each failure to identify systemic causes"
       ]
     },
     {
-      "id": "User-centricity is key",
-      "signature": "organizations that prioritize end-user experience tend to perform better",
-      "interpretation": "Teams that prioritize the end-user experience tend to have higher quality products, more productive developers, and lower levels of burnout.",
+      "id": "low-freq-low-failure",
+      "signature": "low deployment frequency + low change failure rate",
+      "interpretation": "The team prioritises stability over speed. This is typical of the 'Slowing' cluster identified in DORA 2022 — large, infrequent releases that succeed but hold back throughput. The low failure rate is likely achieved through extensive manual testing and coordination overhead, not engineering excellence. DORA research consistently shows that high frequency and low failure rate are achievable together.",
       "improvements": [
-        "Prioritize user research and feedback",
-        "Develop a culture of customer-centricity"
+        "Decompose large releases into smaller, independently deployable changes",
+        "Invest in automated testing to reduce reliance on manual pre-release gates",
+        "Move toward continuous delivery to enable on-demand deploys without increasing risk",
+        "Pilot trunk-based development on one service to validate the approach"
       ]
     },
     {
-      "id": "Platform engineering",
-      "signature": "platform engineering has a positive impact on productivity and organizational performance",
-      "interpretation": "Teams that adopt platform engineering tend to have higher levels of productivity and organizational performance.",
+      "id": "fast-lead-slow-deploy",
+      "signature": "fast lead time (< 1 week) + low deployment frequency (monthly or less)",
+      "interpretation": "Changes are ready quickly but accumulate before release, suggesting a batch release process or manual deployment gates. The bottleneck is in the release process, not the development process. This pattern is common in teams with compliance requirements or manual change advisory board (CAB) approvals.",
       "improvements": [
-        "Invest in platform engineering",
-        "Develop a culture of continuous improvement"
+        "Map the value stream from code-complete to production to identify where changes wait",
+        "Automate deployment pipeline stages that currently require human intervention",
+        "Work with compliance/governance teams to define automated controls that satisfy audit requirements",
+        "Consider scheduled releases with automated deployment to reduce coordination overhead"
       ]
     },
     {
-      "id": "Cloud adoption",
-      "signature": "cloud adoption can have both positive and negative impacts on software delivery performance",
-      "interpretation": "Teams that adopt cloud technologies tend to have higher levels of flexibility and scalability, but may also experience higher levels of complexity and risk.",
+      "id": "slow-lead-high-deploy",
+      "signature": "slow lead time (> 1 month) + high deployment frequency",
+      "interpretation": "The team deploys frequently but individual changes take a long time to be ready. This is unusual and may indicate separate fast-track deployment paths for urgent fixes vs. a slow main development track. It can also signal a large monolith where code review, build, and test times are long despite frequent deployments of accumulated changes.",
       "improvements": [
-        "Develop a thorough understanding of cloud technology",
-        "Invest in training and education for cloud adoption"
+        "Instrument your CI pipeline to identify where time is spent — build, test, review, or approval",
+        "Parallelize test execution to reduce pipeline duration",
+        "Consider breaking the monolith into independently deployable services",
+        "Enforce small PR sizes — large PRs dramatically increase review and merge time"
       ]
     },
     {
-      "id": "High-performing teams",
-      "signature": "high-performing teams tend to excel across all four software delivery metrics",
-      "interpretation": "Teams that are high-performing tend to have high levels of deployment frequency, lead time, change failure percentage, and failed deployment recovery time.",
+      "id": "high-mttr-high-cfr",
+      "signature": "high MTTR (> 1 day) + high change failure rate (>20%)",
+      "interpretation": "The team both creates failures frequently and takes too long to recover. This is the characteristic of the low/retiring cluster and presents significant organizational risk. DORA research shows that without reliability, software delivery performance does not translate to organisational performance. The combination doubles user impact: more incidents and longer outages.",
       "improvements": [
-        "Develop a culture of continuous improvement",
-        "Invest in process automation and optimization"
+        "Establish on-call rotations with clear incident response runbooks",
+        "Invest in observability: structured logging, distributed tracing, and alerting on SLOs",
+        "Implement automated rollback triggered by error rate thresholds",
+        "Define Service Level Objectives (SLOs) and treat breaches as top-priority work"
       ]
     },
     {
-      "id": "faster lead time lower change failure rate",
-      "signature": "10x faster lead time, 5% lower change failure rate",
-      "interpretation": "Elite performer",
+      "id": "monolith-high-deploy",
+      "signature": "monolithic architecture + deployment frequency of daily or higher",
+      "interpretation": "Deploying a monolith frequently is achievable but requires significant engineering discipline — comprehensive automated tests, fast build pipelines, and strong trunk-based development practices. Without these, high-frequency monolith deployment typically leads to elevated change failure rates. DORA research found loosely-coupled architecture is one of the top predictors of high performance.",
       "improvements": [
-        "More deployments per year",
-        "Faster failed deployment recovery times"
+        "Ensure the monolith has comprehensive automated test coverage before increasing deploy cadence",
+        "Identify seams in the monolith where independent deployment could be introduced",
+        "Invest in build optimisation (caching, parallelism) to keep pipeline duration under 10 minutes",
+        "Use feature flags to gate risky changes without reducing deployment frequency"
       ]
     },
     {
-      "id": null,
-      "signature": null,
-      "interpretation": null,
-      "improvements": []
-    },
-    {
-      "id": "vacuum hypothesis",
-      "signature": [
-        "increase in productivity and flow",
-        "decrease in time spent doing valuable work",
-        "no change in toil and burnout"
-      ],
-      "interpretation": "AI expedites the realization of valuable work, creating a 'vacuum' of extra time",
-      "improvements": [
-        "increased productivity",
-        "increased flow",
-        "improved job satisfaction"
-      ]
-    },
-    {
-      "id": "Transformational Leadership",
-      "signature": "Strong leaders with clear vision, inspirational communication, supportive leadership, and personal recognition lead to better outcomes.",
-      "interpretation": "Transformational leadership is strongly correlated with organizational performance, product performance, team performance, productivity, burnout, job satisfaction.",
-      "improvements": [
-        "Focus on user needs",
-        "Prioritize stability",
-        "Provide adequate resources and funding"
-      ]
-    },
-    {
-      "id": "User-Centric Approach",
-      "signature": "Teams that focus on user needs and collect, track, and respond to user feedback have the highest levels of organizational performance.",
-      "interpretation": "User-centered teams have 40% higher level of organizational performance compared to those that did not.",
-      "improvements": [
-        "Collect and respond to user feedback",
-        "Prioritize user needs",
-        "Make better products"
-      ]
-    },
-    {
-      "id": "1",
-      "signature": "Working in small batches, Strong version control practices, and Clear + communicated AI stance",
-      "interpretation": "Amplifying the positive impact of AI on performance",
-      "improvements": [
-        "Investing in foundational systems, Prioritizing user-centric focus"
-      ]
-    },
-    {
-      "id": "2",
-      "signature": "Healthy data ecosystems, AI-accessible internal data, and User-centric focus",
-      "interpretation": "Unlocking the value of AI in software development",
-      "improvements": [
-        "Focusing on quality internal platforms, Implementing strong version control practices"
-      ]
-    },
-    {
-      "id": "Small-Batch Development",
-      "signature": "Teams break down work into smallest possible chunks, deliver independently, and integrate regularly.",
-      "interpretation": "Improving feedback on units of work and team effectiveness by working in small batches.",
-      "improvements": [
-        "Friction",
-        "Individual Effectiveness"
-      ]
-    },
-    {
-      "id": "3",
-      "signature": "Trunk-based development with branch-by-abstraction can support a small-batch approach.",
-      "interpretation": "Teams that use trunk-based development with branch-by-abstraction tend to have faster lead times, lower change failure rates, and lower MTTR.",
-      "improvements": [
-        "Implement trunk-based development",
-        "Use branch-by-abstraction to make large-scale refactors incrementally"
-      ]
-    },
-    {
-      "id": "Cluster 1: Foundational challenges",
-      "signature": [
-        "Burnout",
-        "Friction",
-        "Low product performance",
-        "Low software delivery throughput"
-      ],
-      "interpretation": "Stuck in survival mode, facing significant challenges with fundamental gaps in their processes, environment, and outcomes.",
-      "improvements": [
-        "Improve individual effectiveness",
-        "Stabilize software and operational environment",
-        "Reduce burnout and friction"
-      ]
-    },
-    {
-      "id": "Cluster 2: The legacy bottleneck",
-      "signature": [
-        "Software delivery instability",
-        "Burnout",
-        "Friction"
-      ],
-      "interpretation": "Constant state of reaction, where unstable systems dictate their work and undermine their morale.",
-      "improvements": [
-        "Improve software delivery stability",
-        "Reduce burnout and friction",
-        "Improve team well-being"
-      ]
-    },
-    {
-      "id": "Cluster 3: Constrained by process",
-      "signature": [
-        "Burnout",
-        "Friction",
-        "Low software delivery throughput"
-      ],
-      "interpretation": "Running on a treadmill, where inefficient processes consume their effort and lead to high burnout and low impact.",
-      "improvements": [
-        "Improve process efficiency",
-        "Reduce burnout and friction",
-        "Improve software delivery throughput"
-      ]
-    },
-    {
-      "id": "Cluster 4: High impact, low cadence",
-      "signature": [
-        "High individual effectiveness",
-        "Low software delivery throughput",
-        "High instability"
-      ],
-      "interpretation": "High-impact work, coupled with low-cadence delivery model and high instability.",
-      "improvements": [
-        "Improve software delivery throughput",
-        "Reduce instability",
-        "Maintain high individual effectiveness"
-      ]
-    },
-    {
-      "id": "Cluster 5: Stable and methodical",
-      "signature": [
-        "Individual effectiveness is high",
-        "Software delivery instability is high"
-      ],
-      "interpretation": "Unknown",
-      "improvements": []
-    },
-    {
-      "id": "Cluster 6: Pragmatic performers",
-      "signature": [
-        "Unknown"
-      ],
-      "interpretation": "Unknown",
-      "improvements": []
-    },
-    {
-      "id": "Cluster 7: Harmonious high-achievers",
-      "signature": [
-        "High individual effectiveness",
-        "Low software delivery throughput",
-        "High instability"
-      ],
-      "interpretation": "Unknown",
-      "improvements": []
-    },
-    {
-      "id": "Harmonious high-achievers",
-      "signature": "stable, low-friction environment",
-      "interpretation": "delivering high-quality work sustainably and without burnout",
-      "improvements": [
-        "improve team processes for efficiency",
-        "increase engagement drivers"
-      ]
-    },
-    {
-      "id": "Pragmatic performers",
-      "signature": "consistent delivery with impressive speed and stability",
-      "interpretation": "effective teams with some room for improvement",
-      "improvements": [
-        "improve stability and reliability",
-        "foster peak engagement"
-      ]
-    },
-    {
-      "id": "Stable and methodical",
-      "signature": "deliberate pace of work",
-      "interpretation": "low stability and reliability",
+      "id": "microservices-high-cfr",
+      "signature": "microservices architecture + high change failure rate (>15%)",
+      "interpretation": "Microservices introduce distributed system complexity — network failures, schema drift, service versioning, and cascading failures. High CFR in a microservices context often indicates insufficient contract testing, missing consumer-driven contract tests, or inadequate integration test coverage. The DORA 2022 report found that loosely-coupled architecture drives performance only when paired with strong CD practices.",
       "improvements": [
-        "improve stability and reliability",
-        "increase productivity"
+        "Implement consumer-driven contract testing between services",
+        "Add integration tests for critical service boundaries in the CI pipeline",
+        "Use canary deployments or blue-green deployments to limit blast radius of each release",
+        "Ensure each service has independent rollback capability"
       ]
     },
     {
-      "id": "Constrained by process",
-      "signature": "low stability and reliability",
-      "interpretation": " teams with some technical instability and burnout",
+      "id": "compliance-low-freq",
+      "signature": "compliance constraints + low deployment frequency (monthly or less)",
+      "interpretation": "Compliance requirements often manifest as deployment bottlenecks, but DORA research shows that high-performing regulated teams achieve both compliance and high delivery performance. The key is embedding compliance controls into the automated pipeline rather than using manual gates. Manual change advisory boards (CABs) are consistently shown to be poor predictors of stability and a significant throughput bottleneck.",
       "improvements": [
-        "improve stability and reliability",
-        "reduce burnout and friction"
+        "Map which compliance controls are currently manual and identify which can be automated",
+        "Implement automated audit trails and change evidence collection in the CI/CD pipeline",
+        "Engage compliance and audit teams early to define automated control equivalents",
+        "Pilot continuous delivery on a lower-risk service to build organisational confidence"
       ]
     },
     {
-      "id": "High impact, low cadence",
-      "signature": "strong productivity and effectiveness, but low stability and reliability",
-      "interpretation": "teams exceling in some areas, but struggling with others",
+      "id": "large-team-high-lead-time",
+      "signature": "large team (15+ engineers) + lead time > 2 weeks",
+      "interpretation": "Lead time tends to increase with team and codebase size due to coordination overhead, longer PR review queues, slower builds, and more complex merge conflicts. DORA research shows that team structure and architecture are deeply linked — Conway's Law means that organisational structure shapes system architecture and vice versa.",
       "improvements": [
-        "improve stability and reliability",
-        "increase productivity",
-        "balance cadence and quality"
+        "Evaluate whether the team can be split into smaller, independently deployable product teams",
+        "Set PR size limits and response time expectations to reduce review queue buildup",
+        "Invest in inner loop tooling (local test runners, fast feedback) to reduce developer wait time",
+        "Consider whether the architecture enables team independence or creates coupling"
       ]
     },
     {
-      "id": "Foundational challenges",
-      "signature": "low productivity and stability, high burnout and friction",
-      "interpretation": "teams struggling with foundational challenges and well-being",
+      "id": "long-pipeline-low-deploy",
+      "signature": "pipeline duration > 30 minutes + low deployment frequency",
+      "interpretation": "Long pipelines are a primary driver of low deployment frequency. When each deployment requires 45-60+ minutes of CI time, engineers batch changes to reduce overhead, increasing changelist size and risk. DORA research identifies fast feedback as one of the foundational capabilities of high-performing teams.",
       "improvements": [
-        "improve foundational processes and team well-being"
+        "Profile your pipeline to identify the slowest stages — test parallelisation is usually the biggest win",
+        "Separate fast-feedback tests (unit, contract) from slow tests (integration, E2E) using pipeline stages",
+        "Cache dependencies and build artifacts aggressively",
+        "Target a pipeline duration of under 10 minutes for the core feedback loop"
       ]
     },
     {
-      "id": "Value Stream Mapping",
-      "signature": "High lead time (> 5 days), high developer toil (> 4 hours), high risk profile, manual \"ticket-ops\" and high cognitive load",
-      "interpretation": "Identifies process inefficiencies and bottlenecks",
+      "id": "high-pr-review-time",
+      "signature": "PR review time > 24 hours + medium or low deployment frequency",
+      "interpretation": "Long PR review cycles directly increase lead time and reduce deployment frequency. They also create merge conflicts as branches diverge, further slowing the process. DORA's 2022 research specifically identified code review as a key inner loop capability. High-performing teams maintain short-lived branches and fast review cycles.",
       "improvements": [
-        "Implement AI-powered agents to automate provisioning, configuration, and code generation"
+        "Establish team norms for PR review response time (e.g., first review within 4 hours)",
+        "Break large PRs into smaller, stacked PRs that are easier to review quickly",
+        "Use automated checks (linting, tests, security scanning) to reduce cognitive load on reviewers",
+        "Adopt trunk-based development to eliminate long-lived branches entirely"
       ]
     },
-    {},
-    {
-      "id": "Flowing Cluster",
-      "signature": [
-        "Less than one hour",
-        "0%-15%",
-        "Usually meet expectations",
-        "Less than one day",
-        "On demand (multiple deploys per day)"
-      ],
-      "interpretation": "Flowing cluster performs well across all characteristics: high reliability, high stability, high throughput.",
-      "improvements": []
-    },
-    {
-      "id": "Slowing Cluster",
-      "signature": [
-        "Less than one day",
-        "0%-15%",
-        "Usually meet expectations",
-        "Between one week and one month",
-        "Between once per week and once per month"
-      ],
-      "interpretation": "Slowing cluster: team that is incrementally improving, but they and their customers are mostly happy with the current state of their application or product.",
-      "improvements": []
-    },
-    {
-      "id": "Starting Cluster",
-      "signature": [
-        "Between one day and one week",
-        "31%-45%",
-        "Sometimes meet expectations",
-        "Between once per week and once per month"
-      ],
-      "interpretation": "Starting cluster performs neither well nor poorly across any of our dimensions. This cluster might be in the early stages of their product, feature, or service’s development.",
-      "improvements": []
-    },
-    {
-      "id": "Retiring Cluster",
-      "signature": [
-        "46%-60%",
-        "Usually meet expectations",
-        "Between one month and six months",
-        "Between once per month and once every 6 months"
-      ],
-      "interpretation": "Retiring cluster: team working on a service or application that is still valuable to them and their customers, but no longer under active development.",
-      "improvements": []
-    },
     {
-      "id": "using-cloud-native-apps",
-      "signature": "use of cloud-native applications",
-      "interpretation": "positive signals on everything surveyed",
+      "id": "ai-adoption-stability-risk",
+      "signature": "high AI tool adoption + increasing change failure rate",
+      "interpretation": "DORA 2024 research found that increased AI adoption correlates with a 7.2% reduction in delivery stability for every 25% increase in AI adoption. The hypothesis is that AI's code generation speed leads teams to create larger changesets, which DORA consistently shows increases failure rates. The benefit of AI is real at the individual level but requires process adaptation.",
       "improvements": [
-        "Generative culture",
-        "lower burnout",
-        "more stability",
-        "higher employee satisfaction"
+        "Enforce changelist size limits — AI makes it easy to generate more code, but smaller changes are safer",
+        "Invest in automated test coverage for AI-generated code, which may have subtle correctness issues",
+        "Treat AI adoption as a process change requiring deliberate adjustment of deployment practices",
+        "Monitor CFR and lead time closely during periods of AI tool adoption"
       ]
     },
     {
-      "id": "benefits-unique-benefits-of-different-cloud-providers",
-      "signature": "over 50% of practitioners reported leveraging the unique benefits of different cloud providers",
-      "interpretation": "availability, reliability, and unique benefits",
+      "id": "platform-engineering-throughput-drop",
+      "signature": "recent internal developer platform adoption + decreasing deployment frequency or increasing lead time",
+      "interpretation": "DORA 2024 found that platform engineering teams see +8% productivity but -8% throughput and -14% change stability during adoption. This aligns with the J-Curve pattern identified in DORA 2022 for SRE adoption — transformations often show short-term regressions before long-term gains. This is expected, not a signal to abandon the platform.",
       "improvements": [
-        "availability",
-        "reliability"
+        "Acknowledge the J-Curve: set stakeholder expectations for a temporary performance dip",
+        "Measure developer experience (SPACE metrics) alongside DORA metrics during platform rollout",
+        "Prioritise golden paths that reduce toil for the most common developer tasks first",
+        "Ensure platform teams apply a product mindset — treat internal developers as users"
       ]
     },
     {
-      "id": "cloud-characteristics",
-      "signature": "use of the five characteristics of cloud computing",
-      "interpretation": "positive affects software delivery and operations performance",
+      "id": "generative-culture-reliability",
+      "signature": "strong delivery metrics + poor reliability (MTTR > 1 day, high incident frequency)",
+      "interpretation": "DORA 2022 research found that without reliability, software delivery performance does not predict organisational success. The 'Flowing' cluster had strong delivery metrics but poor reliability, and scored lower on organisational performance than expected. Reliability is described as the most important 'feature' of any product — keeping promises to users is a necessary condition for delivery speed to generate business value.",
       "improvements": [
-        "resource pooling",
-        "rapid elasticity",
-        "on-demand self-service",
-        "broad network access",
-        "measured service"
+        "Define SLOs for your most critical user journeys and treat breaches as P0 incidents",
+        "Invest in observability before further increasing deployment frequency",
+        "Establish error budgets — when the budget is exhausted, freeze feature work and fix reliability",
+        "Build a generative team culture: trust, blameless retrospectives, and psychological safety predict better reliability outcomes"
       ]
     },
     {
-      "id": "hybrid-and-multi-cloud",
-      "signature": "use of hybrid and multi-cloud",
-      "interpretation": "positive impact on organizational performance",
-      "improvements": [
-        "availability"
-      ]
-    },
-    {
-      "id": "...",
-      "signature": "J Curve",
-      "interpretation": "...",
-      "improvements": [
-        "adoption threshold",
-        "cross-functional collaboration"
-      ]
-    },
-    {
-      "id": "loosely-coupled-architecture",
-      "signature": "41% more likely to have systems based on a loosely-coupled architecture",
-      "interpretation": "Teams that focus on building software with loosely-coupled architectures are in a better position to perform strongly across stability, reliability, and throughput.",
-      "improvements": [
-        "Loosely-coupled architecture leads to faster feedback through independent testing."
-      ],
-      "data": "41%, 43% more likely to... - error proneness and deployment"
-    },
-    {
-      "id": "cd-impact-on-performance",
-      "signature": "When combined with loosely-coupled architectures and CD, teams may have a negative impact on performance.",
-      "interpretation": "The combination of loosely-coupled architectures and CD may lead to issues such as anticipation of error proneness.",
-      "improvements": [
-        "Be aware of potential issues when implementing these practices together."
-      ],
-      "data": null
-    },
-    {
-      "id": "Healthy, high-performing teams have good security practices",
-      "signature": [
-        "Having good security practices",
-        "Healthy, high-performing teams"
-      ],
-      "interpretation": "Good security practices are associated with healthy, high-performing teams",
-      "improvements": []
-    },
-    {
-      "id": "Trunk-based development negatively impacts software delivery performance",
-      "signature": [
-        "Trunk-based development",
-        "Negative impact on software delivery performance"
-      ],
-      "interpretation": "Trunk-based development practices have a negative impact on software delivery performance compared to previous research",
-      "improvements": []
-    },
-    {
-      "id": "Documentation practices negatively impact software delivery performance",
-      "signature": [
-        "Documentation practices",
-        "Negative impact on software delivery performance"
-      ],
-      "interpretation": "Documentation practices have a negative impact on software delivery performance",
-      "improvements": []
-    },
-    {
-      "id": "Some tech capabilities may predict burnout",
-      "signature": [
-        "Some tech capabilities",
-        "Predict burnout"
-      ],
-      "interpretation": "Some tech capabilities may predict burnout, but more research is needed",
-      "improvements": []
-    },
-    {
-      "id": "Reliability engineering practices negatively impact software delivery performance",
-      "signature": [
-        "Reliability engineering practices",
-        "Negative impact on software delivery performance"
-      ],
-      "interpretation": "Reliability engineering practices have a negative impact on software delivery performance",
-      "improvements": []
-    },
-    {
-      "id": "SLSA-related practices serve as a mechanism for technical capabilities to impact performance",
-      "signature": [
-        "SLSA-related practices",
-        "Mechanism for technical capabilities to impact performance"
-      ],
-      "interpretation": "SLSA-related practices serve as a mechanism for technical capabilities to impact performance",
-      "improvements": []
-    },
-    {
-      "id": "not specified",
-      "signature": "combinations of deployment frequency, lead time, time to restore a service, and change failure rate",
-      "interpretation": " indicates performance",
+      "id": "scheduled-release-high-lead-time",
+      "signature": "scheduled release strategy + lead time > 2 weeks",
+      "interpretation": "Scheduled releases create artificial batch boundaries that accumulate risk. Changes that are ready are held waiting for the release window, extending lead time and increasing the size of each release. Larger releases contain more changes, making it harder to diagnose failures and increasing MTTR when they occur.",
       "improvements": [
-        "improve deployment frequency",
-        "reduce lead time",
-        "improve time to restore a service",
-        "reduce change failure rate"
+        "Decouple your deployment schedule from your release schedule using feature flags",
+        "Identify which aspects of the scheduled release exist for coordination reasons vs. technical reasons",
+        "Move toward release trains with shorter intervals (bi-weekly → weekly → continuous)",
+        "Use canary releases or percentage rollouts to reduce the risk of each release"
       ]
     }
   ],
   "keyInsights": [
-    "AI adoption has both positive and negative impacts on software delivery performance",
-    "User-centricity is key to high performance",
-    "Transformational leadership is linked to high performance",
-    "Platform engineering has a positive impact on productivity and organizational performance",
-    "Cloud adoption can have both positive and negative impacts on software delivery performance",
-    "High-performing teams tend to excel across all four software delivery metrics",
-    "Improving performance overall is more important than reaching a particular performance level",
-    "The best teams are those that achieve elite improvement, not necessarily elite performance",
-    "Estimates suggest that leading tech giants will invest approximately $1 trillion on the development of AI in the next five years.",
-    "81% of respondents say their company has shifted resources into developing AI.",
-    "The training of an AI model can add up to roughly ‘the yearly electricity consumption of over 1,000 U.S. households’.",
-    "More than 30% of respondents think AI is going to be detrimental to the environment.",
-    "Over a third of respondents believe AI will harm society in the coming decade.",
-    "Evidence for proximal outcomes, such as the ability to successfully complete a particular task, is largely positive.",
-    "However, when the outcome becomes more distant, such as a team’s codebase, the results start becoming a little less clear and a little less positive.",
-    "A 25% increase in AI adoption is associated with a 7.5% increase in documentation quality",
-    "A 25% increase in AI adoption is associated with a 3.4% increase in code quality",
-    "A 25% increase in AI adoption is associated with a 3.1% increase in code review speed",
-    "A 25% increase in AI adoption is associated with a 1.3% increase in approval speed",
-    "A 25% increase in AI adoption is associated with a 1.8% decrease in code complexity",
-    "Platforms can lead to increased instability and burnout when not used effectively",
-    "Prioritizing throughput over quality can result in bad changes making it through the process",
-    "Team or individual productivity can still be maintained despite burnout and change instability",
-    "Platforms can be symptomatic of an organization with burnout and change instability",
-    "Focusing on the user increases productivity and job satisfaction, while reducing the risk of burnout.",
-    "A user-centered approach to software development can fundamentally alter how developers view their work, giving them confidence that the features they are working on have a reason for being.",
-    "Documentation helps propagate user signals and feedback across the team and into the product itself.",
-    "Unstable organizational priorities increase employee burnout due to unclear expectations, decreased sense of control, and increased workload size.",
-    "Changing priorities themselves are not the problem, but the frequency and predictability of changes can have a negative impact on employees' well-being.",
-    "Stabilizing organizational priorities can lead to a decline in software delivery performance, as changes are made less frequently.",
-    "Adding AI-powered experiences can provide clarity and a northstar for organizations, leading to a stabilization of organizational priorities.",
-    "Transformational leadership is crucial for driving organizational performance, product performance, and team performance.",
-    "Focusing on user needs leads to better products and improved organizational performance.",
-    "Investing in IT improvement is strongly correlated with organizational culture, win-win outcomes, and effective leadership.",
-    "Companies that adopt a mindset of continuous improvement see the highest levels of success.",
-    "The goal of the organization and your teams should be to simply be a little better than you were yesterday.",
-    "The benefits gained by speed and stability are diminished as higher performance becomes ubiquitous.",
-    "AI is an amplifier, Amplifies strengths of high-performing organizations and dysfunctions of struggling ones",
-    "Investing in foundational systems and user-centric focus can help unlock AI's potential",
-    "A healthy data ecosystem is the reliable, context-aware foundation for the entire DORA AI Capabilities Model",
-    "High-quality data is only useful if AI tools can securely connect to it",
-    "Making internal data AI accessible amplifies AI adoption's positive influence on individual effectiveness and code quality",
-    "AI-accessible internal data moderates AI's impact on individual effectiveness",
-    "AI-accessible internal data moderates AI's impact on code quality",
-    "AI-accessible internal data boosts individual effectiveness and code quality by providing relevant, internal context.",
-    "Connecting AI to internal code and documentation, or “context engineering,” transforms the AI from a generic assistant into a specialized expert.",
-    "Merge conflicts are often a sign of process issues.",
-    "Frequent or complex merge conflicts occur when development branches are not kept short-lived.",
-    "Working in small batches is essential for high-performing teams.",
-    "Teams that prioritize working in small batches tend to have faster lead times, lower change failure rates, and lower MTTR.",
-    "Using feature flags and trunk-based development with branch-by-abstraction can support a small-batch approach.",
-    "User-centric focus moderates AI's impact on team performance.",
-    "Regularly survey developers to track satisfaction",
-    "Use DORA metrics to measure software delivery performance",
-    "Instrument and expose metrics for every service to empower developers",
-    "Teams in Cluster 1: Foundational challenges are stuck in survival mode",
-    "Teams in Cluster 2: The legacy bottleneck are in a constant state of reaction",
-    "Teams in Cluster 3: Constrained by process are running on a treadmill",
-    "Teams in Cluster 4: High impact, low cadence produce high-impact work but with low-cadence delivery model",
-    "15% of survey respondents are in cluster 5",
-    "20% of survey respondents are in cluster 6",
-    "20% of survey respondents are in cluster 7",
-    "The total active process time (PT) is only about one day (~24.5 hours), while the total wait time is nearly four days (~92.5 hours)",
-    "The total end-to-end lead time is roughly 117 hours and a flow efficiency of ~21%",
-    "Work is sitting in a wait state for nearly four-fifths of the time",
-    "Inconsistent code reviews and a high rate of rework and bugs discovered late in the process",
-    "Developers spend a large amount of process time searching for information or understanding existing code",
-    "Teams with faster code reviews have 50% higher software delivery performance",
-    "By applying VSM to internal developer journeys, teams transform platform engineering from a cost center to a value driver",
-    "Research by DORA and others has shown that AI, in and of itself, is not assured to be beneficial. It must be adopted with care.",
-    "To achieve a return on investments made in acquiring and adapting to AI, teams should also attend to how they communicate, collaborate, and operate across their broader sociotechnical context.",
-    "Seven key predictors of success with AI have been identified, which are presented in the DORA AI Capabilities Model.",
-    "For the first time, no cluster is considered elite.",
-    "The percentage of high performers is at a 4-year low, while the percentage of low performers rose dramatically, from 7% in 2021 to 19% this year.",
-    "Over two-thirds of this year’s respondents fall into the medium cluster.",
-    "Teams with high short-term organizational performance may experience burnout and other negative outcomes in the long term.",
-    "Organizations with high reliability and speed are more likely to have low burnout and unplanned work.",
-    "Reliability may not be enough to achieve high organizational performance without speed and stability.",
-    "The use of cloud computing has a positive impact on overall organizational performance",
-    "Respondents that used cloud were 14% more likely to exceed in organizational performance goals",
-    "Cloud users scored 16% higher on cultural outcomes",
-    "The use of cloud-native applications stands out with positive signals on everything surveyed",
-    "The use of any cloud computing platform, public or private, positively contributes to culture and work environment outcomes",
-    "The use of hybrid and multi-cloud has a positive impact on organizational performance",
-    "Practitioners who used multiple clouds showed a 1.4x higher organizational performance compared to non-cloud users",
-    "The five characteristics of cloud computing are crucial for achieving better organizational performance",
-    "High performers meet reliability targets",
-    "Respondents with higher-than-average use of CI, CD, and version control have 3.8x higher organizational performance",
-    "Continuous integration drives delivery performance",
-    "Acknowledge the J Curve of change",
-    "Teams that focus on building software with loosely-coupled architectures",
-    "Teams that combine version control and continuous delivery are 2.5x more likely to have high software delivery performance.",
-    "Loosely-coupled architecture is associated with increased stability, reliability, and throughput, and also more likely to recommend workplace.",
-    "A generative culture is associated with higher levels of organizational performance compared to organizations characterized by a bureaucratic or pathological culture.",
-    "Employees at organizations with a generative culture are more likely to belong to stable teams, produce higher-quality documentation, and spend most of their time engaged in meaningful work.",
-    "Organizations with higher levels of employee flexibility have higher organizational performance compared to organizations with more rigid work arrangements.",
-    "A generative culture is associated with lower rates of employee burnout.",
-    "Stable teams — teams whose composition hadn’t changed much over the last 12 months — were more likely to exist within high-performing organizations.",
-    "Healthier cultures have a head start: Organizational culture is a primary driver of software development security practices, with higher trust, ‘blameless’ cultures are more likely to establish SLSA and SSDF practices than lower-trust organizational cultures.",
-    "Adoption has already begun: Software supply chain security practices embodied in SLSA and SSDF already see modest adoption, but there is ample room for more.",
-    "There’s a key integration point: Adoption of the technical aspects of software supply chain security appears to hinge on the use of CI/CD, which often provides the integration platform for many supply chain security practices.",
-    "It provides unexpected benefits: Besides a reduction in security risks, better security practices carry additional advantages, such as reduced burnout.",
-    "Having systems for source control, continuous integration, and continuous delivery were all linked with also having more firmly established SLSA practices.",
-    "CI directly precedes code reviews, and is when vulnerability scanners and other code analysis tools are run.",
-    "Security scanning on development workstations can save time and effort for software engineers.",
-    "Good security practices can reduce an organization’s security risk and positively impact software delivery performance, but CI is necessary for these effects.",
-    "Organizational culture and modern development processes (such as continuous integration) are the biggest drivers of an organization’s application development security.",
-    "SLSA and SSDF practices appear to work as intended",
-    "Healthy, high-performing teams have good security practices",
-    "Trunk-based development negatively impacts software delivery performance",
-    "Documentation practices negatively impact software delivery performance",
-    "Some tech capabilities may predict burnout",
-    "Reliability engineering practices negatively impact software delivery performance",
-    "SLSA-related practices serve as a mechanism for technical capabilities to impact performance",
-    "65% of respondents work on teams with 12 people or fewer.",
-    "75% of respondents work on teams with 12 people or fewer.",
-    "22% of respondents are at companies with more than 10,000 employees.",
-    "85% of respondents consist of individuals who either work on development or engineering teams (26%), work on DevOps or SRE teams (23%), work on IT ops or infrastructure teams (19%), or are managers (17%)",
-    "Technical capabilities build upon each other to create better performance.",
-    "The use of cloud has many benefits.",
-    "Workplace culture and flexibility lead to better organizational performance.",
-    "Employee burnout prevents organizations from reaching their goals.",
-    "high performers deploy on demand, multiple times per day",
-    "low performers deploy between once every month to once every six months"
+    "Elite performers deploy 182x more frequently than low performers and have 127x faster lead times (DORA 2024)",
+    "Elite performers have 2293x faster failed deployment recovery times than low performers (DORA 2024)",
+    "Elite performers have 8x lower change failure rates than low performers (DORA 2024)",
+    "In 2024, only 19% of teams achieved elite performance; 25% were in the low cluster (DORA 2024)",
+    "High performers in 2022 were estimated to have 417x more deployments than low performers (DORA 2022)",
+    "Throughput and stability are correlated — the best teams do well on all four DORA metrics simultaneously (DORA 2024)",
+    "The 2024 medium performance cluster has lower throughput but higher stability than the high cluster — neither is universally better (DORA 2024)",
+    "Improving is more important than reaching a specific performance level; the best teams achieve elite improvement, not necessarily elite performance (DORA 2024)",
+    "Industry does not meaningfully affect performance levels — high-performing teams exist in every industry (DORA 2024)",
+    "Without reliability, software delivery performance does not predict organisational success (DORA 2022)",
+    "Reliability is the most important 'feature' of any product — keeping promises to users is a necessary condition for delivery speed to generate value (DORA 2022)",
+    "Teams with generative culture (trust, collaboration) are more likely to achieve good reliability outcomes (DORA 2022)",
+    "The top technical capabilities driving high performance are: version control, continuous integration, continuous delivery, and loosely-coupled architecture (DORA 2022)",
+    "High performers who meet reliability targets are 33% more likely to use version control, 39% more likely to practice CI, 46% more likely to practice CD, and 40% more likely to have loosely-coupled architecture (DORA 2022)",
+    "Continuous Integration is 1.4x more likely to be used by high performers who meet reliability targets (DORA 2022)",
+    "Trunk-based development decreases change failure rate, error-proneness, and unplanned work — but requires experience to implement successfully (DORA 2022)",
+    "Teams with 16+ years of experience who use trunk-based development see increased delivery performance and decreased change failure rate (DORA 2022)",
+    "Cloud users are 14% more likely to exceed organisational performance goals than non-cloud peers (DORA 2022)",
+    "Hybrid and multi-cloud have a negative impact on delivery performance indicators (MTTR, lead time, deployment frequency) unless teams also have high reliability (DORA 2022)",
+    "SRE adoption follows a J-Curve: early adoption may not predict better reliability, but teams that persist through the inflection point see strong reliability gains (DORA 2022)",
+    "Respondents using higher-than-average levels of all technical capabilities have 3.8x higher organisational performance (DORA 2022)",
+    "AI adoption improves individual flow (+2.6%), productivity (+2.1%), and job satisfaction (+2.2%) per 25% increase in AI reliance (DORA 2024)",
+    "AI adoption reduces delivery stability by approximately 7.2% and throughput by 1.5% for every 25% increase in AI adoption — the hypothesis is that AI increases changelist size (DORA 2024)",
+    "AI improves code quality, documentation, and review speed, but these gains do not automatically translate to better delivery performance (DORA 2024)",
+    "The DORA 2024 'vacuum hypothesis': AI helps people finish valuable work faster, creating time that gets filled with more work rather than reducing toil (DORA 2024)",
+    "Platform engineering users see 8% higher individual productivity and 10% higher team performance, but 8% lower throughput and 14% lower change stability during adoption (DORA 2024)",
+    "Platform engineering success requires a user-centred (developer-centred) product mindset — without it, the platform becomes a hindrance (DORA 2024)",
+    "AI adoption increases organisational performance (+2.3%) and team performance (+1.4%) per 25% increase, but has no clear impact on product performance (DORA 2024)",
+    "Nearly 90% of software professionals were using AI tools as of the 2025 DORA AI Capabilities Model research",
+    "Seven AI capabilities identified by DORA 2025: clear AI stance, healthy data ecosystems, quality internal platforms, strong version control, working in small batches, user-centric focus, AI-accessible internal data",
+    "Working in small batches is a foundational AI capability — AI amplifies productivity, but larger changesets created by AI tools increase delivery risk without small batch discipline",
+    "The percentage of high performers was at a 4-year low in 2022, while low performers rose from 7% to 19% — suggesting pandemic-related knowledge sharing disruption (DORA 2022)",
+    "Change failure rate is strongly correlated with rework rate — failures require remediation changes, creating a compounding effect on throughput (DORA 2024)",
+    "The 2024 report introduced 'Failed Deployment Recovery Time' as the evolved metric replacing MTTR, measured specifically from failed deployment to recovery (DORA 2024)"
   ]
-}
+}

docs/architecture.md

@@ -0,0 +1,62 @@
+# Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        USER'S BROWSER                           │
+│                                                                 │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐ │
+│  │  app/page.tsx   │───▶│ app/report/     │    │  window.    │ │
+│  │                 │    │ page.tsx        │───▶│  print()    │ │
+│  │  Step 1:        │    │                 │    │  (PDF)      │ │
+│  │  MetricsForm    │    │  ReportView     │    └─────────────┘ │
+│  │  Step 2:        │    │  BenchmarkTable │                    │
+│  │  ContextForm    │    │                 │                    │
+│  └────────┬────────┘    └────────▲────────┘                    │
+│           │ POST                 │ sessionStorage               │
+│           │ /api/interpret       │ "devops-report"              │
+└───────────┼──────────────────────┼──────────────────────────────┘
+            │                      │
+┌───────────┼──────────────────────┼──────────────────────────────┐
+│           ▼        NEXT.JS SERVER (HF Space / local)            │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │              app/api/interpret/route.ts                 │    │
+│  │                                                         │    │
+│  │  1. Validate input (MetricsInputSchema, TeamContext)    │    │
+│  │  2. loadBenchmarks()  ◀── data/benchmarks.json         │    │
+│  │  3. buildSystemPrompt(benchmarks)                       │    │
+│  │  4. formatMetricsMessage(metrics, context)              │    │
+│  │  5. chat(system, user)  ──▶  lib/llm.ts                │    │
+│  │  6. Validate response (InterpretationReportSchema)      │    │
+│  │  7. Return JSON report ──────────────────────────────────────┘
+│  └──────────────────────────┬──────────────────────────────┘
+│                             │
+│              ┌──────────────▼──────────────┐
+│              │         lib/llm.ts          │
+│              │  OpenAI-compatible client   │
+│              │  baseURL from OLLAMA_BASE_URL│
+│              └──────────────┬──────────────┘
+└─────────────────────────────┼────────────────────────────────────
+                              │
+          ┌───────────────────┴───────────────────┐
+          │                                       │
+          ▼  (local dev)                          ▼  (HF Space)
+  ┌───────────────┐                    ┌──────────────────────┐
+  │    Ollama     │                    │  HF Inference Router │
+  │  localhost:   │                    │  router.huggingface  │
+  │  11434/v1     │                    │  .co/v1              │
+  │               │                    │                      │
+  │ llama3.1:8b   │                    │ Qwen2.5-72B-Instruct │
+  └───────────────┘                    └──────────────────────┘
+
+──────────────────── ONE-TIME SETUP ─────────────────────────────
+
+  data/pdfs/*.pdf
+       │
+       ▼
+  scripts/extract-knowledge.ts
+  (pdf-parse → chunk → LLM → merge)
+       │
+       ▼
+  data/benchmarks.json  ──▶  bundled into Docker image
+  (47 patterns, 124 insights)
+```