konpeki 0.1.0

package/slides/results-explanation/PROMPT.md

@@ -0,0 +1,32 @@
+Make a three-page presentation explaining a search-quality evaluation to the
+engineering lead at Waymark. Help them decide whether to test a reranker on
+live traffic, balancing retrieval quality against latency.
+
+---
+
+Waymark is a fictional internal-document search tool. The evaluation compares
+its baseline retrieval with the same retrieval followed by a reranker. Both
+use the same document snapshot and the same 80 hand-authored queries: 50
+direct lookups and 30 questions requiring several pieces of information.
+
+A query passes when at least one reviewer-labeled relevant document appears
+in the top five results. This measures retrieval, not whether a generated
+answer would be correct or complete.
+
+- Direct lookups: baseline passes 44 of 50; reranker passes 46 of 50.
+- Multi-part questions: baseline passes 15 of 30; reranker passes 21 of 30.
+- End-to-end median search latency: baseline 180 ms; reranker 310 ms.
+- End-to-end 95th-percentile search latency: baseline 420 ms; reranker 760 ms.
+
+These are synthetic, hand-authored results from one illustrative evaluation
+pass, not an executed benchmark. Per-query outcomes, repeated timings, costs
+and reviewer-agreement measurements are unavailable. Aggregate counts do not
+show which individual queries improved or regressed.
+
+---
+
+The proposed gate for a limited live trial is at least 80% passing queries
+overall and p95 latency no greater than 800 ms. Assess both conditions, show
+the category-level trade-off and explain what this small offline set cannot
+establish. Passing this gate would justify a limited trial, not a full rollout;
+live query mix, tail latency and individual regressions still need evaluation.

package/slides/results-explanation/index.tsx

@@ -0,0 +1,96 @@
+import type { ReactNode } from 'react';
+import { fontsReady } from '../../lib/typeface.ts';
+
+await fontsReady;
+const ink = '#172B37', muted = '#4D606B', accent = '#006B68', line = '#CBD5DA';
+const T = ({ x = 112, y, size = 36, weight = 400, color = ink, children }: { x?: number; y: number; size?: number; weight?: number; color?: string; children: ReactNode }) =>
+  <text x={x} y={y} fontSize={size} fontWeight={weight} fill={color}>{children}</text>;
+function Frame({ page, title, description, children }: { page: number; title: string; description: string; children: ReactNode }) {
+  return <svg xmlns="http://www.w3.org/2000/svg" width="1920" height="1080" viewBox="0 0 1920 1080" fontFamily="IBM Plex Sans" role="img" aria-label={`${title}. ${description}`} data-page={page}>
+    <rect width="1920" height="1080" fill="#FFFFFF" />
+    <T y={151} size={66} weight={600}>{title}</T>
+    {children}
+    <T x={1760} y={1014} size={28} color={muted}>{page} / 3</T>
+  </svg>;
+}
+const Gate = () => <Frame page={1} title="Waymark’s reranker clears the trial gate" description="Synthetic illustrative results, not an executed benchmark. Baseline passes 59 of 80 queries, 73.75%, with p95 420 milliseconds. Reranker passes 67 of 80, 83.75%, with p95 760 milliseconds. Gate: at least 80% passing and p95 at most 800 milliseconds. Only the reranker meets both; a limited trial is justified, not a full rollout.">
+  <T y={225} color={muted}>Synthetic, hand-authored results • one illustrative evaluation pass</T>
+  <T y={340} size={32} weight={500}>Proposed limited-trial gate</T>
+  <T y={405} size={45} weight={500}>≥80% passing queries overall  +  p95 ≤800 ms</T>
+  <line x1={112} y1={468} x2={1808} y2={468} stroke={line} strokeWidth={2} />
+  <T x={790} y={522} size={30} color={muted}>Passing queries</T>
+  <T x={1250} y={522} size={30} color={muted}>p95 latency</T>
+  <T x={1580} y={522} size={30} color={muted}>Both gates</T>
+  <T y={610} size={40} weight={500}>Baseline</T>
+  <T x={790} y={610} size={40}>59/80 · 73.75%</T>
+  <T x={1250} y={610} size={40}>420 ms</T>
+  <T x={1580} y={610} size={36}>No</T>
+  <line x1={112} y1={655} x2={1808} y2={655} stroke={line} />
+  <T y={740} size={40} weight={600} color={accent}>Retrieval + reranker</T>
+  <T x={790} y={740} size={40} weight={600} color={accent}>67/80 · 83.75%</T>
+  <T x={1250} y={740} size={40} weight={600} color={accent}>760 ms</T>
+  <T x={1580} y={740} size={36} weight={600} color={accent}>Yes</T>
+  <line x1={112} y1={790} x2={1808} y2={790} stroke={line} strokeWidth={2} />
+  <T y={883} size={40} weight={500}>Proceed to a limited live trial, not a full rollout.</T>
+  <T y={941} size={32} color={muted}>The reranker has 3.75 percentage points of quality headroom and only 40 ms at p95.</T>
+</Frame>;
+
+const Tradeoff = () => <Frame page={2} title="Multi-part retrieval gains most; latency rises" description="Direct lookups: baseline 44 of 50, 88%; reranker 46 of 50, 92%, plus 4 percentage points. Multi-part questions: baseline 15 of 30, 50%; reranker 21 of 30, 70%, plus 20 points. Median latency rises from 180 to 310 milliseconds; p95 from 420 to 760. Same document snapshot and same 80 queries. A pass means at least one reviewer-labeled relevant document in the top five, not a correct or complete generated answer.">
+  <T y={225} color={muted}>Same document snapshot and 80 queries: 50 direct lookups, 30 multi-part questions.</T>
+  <T y={325} size={32} weight={500}>Queries passing (%)</T>
+  <T x={740} y={325} size={28} color={muted}>Baseline</T>
+  <T x={960} y={325} size={28} color={accent}>Reranker</T>
+  {[0, 50, 100].map(v => <g key={v}><line x1={380 + v * 7} y1={358} x2={380 + v * 7} y2={706} stroke={line} /><T x={365 + v * 7} y={752} size={26} color={muted}>{v}</T></g>)}
+  <T y={425} size={32} weight={500}>Direct lookups</T>
+  <rect x={380} y={382} width={616} height={40} fill={muted} />
+  <rect x={380} y={445} width={644} height={40} fill={accent} />
+  <T x={1045} y={413} size={28}>44/50 · 88%</T>
+  <T x={1045} y={477} size={28} color={accent}>46/50 · 92%</T>
+  <T y={626} size={32} weight={500}>Multi-part</T>
+  <rect x={380} y={581} width={350} height={40} fill={muted} />
+  <rect x={380} y={644} width={490} height={40} fill={accent} />
+  <T x={755} y={613} size={28}>15/30 · 50%</T>
+  <T x={895} y={677} size={28} color={accent}>21/30 · 70%</T>
+  <T x={1360} y={325} size={32} weight={500}>End-to-end latency</T>
+  <T x={1360} y={411} size={30} color={muted}>Baseline / reranker</T>
+  <T x={1360} y={479} size={39} weight={500}>180 / 310 ms</T>
+  <T x={1360} y={531} size={30} color={muted}>Median · +130 ms</T>
+  <T x={1360} y={654} size={39} weight={500}>420 / 760 ms</T>
+  <T x={1360} y={706} size={30} color={muted}>p95 · +340 ms</T>
+  <T y={830} size={37} weight={500}>+4 points on lookups; +20 on multi-part questions.</T>
+  <T y={881} size={30} color={muted}>Multi-part questions require several pieces of information.</T>
+  <T y={925} size={30} color={muted}>Pass = at least one reviewer-labeled relevant document in the top five results.</T>
+  <T y={969} size={30} color={muted}>Measures retrieval, not generated-answer correctness or completeness. Synthetic results.</T>
+</Frame>;
+
+const Trial = () => <Frame page={3} title="Use the live trial to test what offline cannot" description="Recommended next step: limit reranker exposure and retain baseline comparison. Evaluate the live query mix, repeated tail latency, and individual query regressions before expanding. Aggregate counts do not identify improved or regressed queries. Per-query outcomes, repeated timings, costs, and reviewer agreement are unavailable; the small hand-authored offline set cannot establish production performance or rollout readiness.">
+  <T y={231} size={38} color={accent} weight={500}>Limit reranker exposure and retain a baseline comparison.</T>
+  <T y={331} size={30} color={muted}>Unknown in this offline set</T>
+  <T x={860} y={331} size={30} color={muted}>Evidence to collect before expanding</T>
+  <line x1={112} y1={370} x2={1808} y2={370} stroke={line} strokeWidth={2} />
+  <T y={435} size={37} weight={500}>Production query mix</T>
+  <T x={860} y={435} size={34}>Measure passing rates by live query category.</T>
+  <T y={486} size={30} color={muted}>80 hand-authored queries may not represent traffic.</T>
+  <T x={860} y={486} size={30} color={muted}>Check whether the overall ≥80% result holds.</T>
+  <line x1={112} y1={529} x2={1808} y2={529} stroke={line} />
+  <T y={594} size={37} weight={500}>Tail-latency stability</T>
+  <T x={860} y={594} size={34}>Repeat end-to-end timings under live load.</T>
+  <T y={645} size={30} color={muted}>One pass gives no variability estimate.</T>
+  <T x={860} y={645} size={30} color={muted}>Check p95 ≤800 ms; current headroom is 40 ms.</T>
+  <line x1={112} y1={688} x2={1808} y2={688} stroke={line} />
+  <T y={753} size={37} weight={500}>Individual regressions</T>
+  <T x={860} y={753} size={34}>Review paired outcomes for each query.</T>
+  <T y={804} size={30} color={muted}>Aggregate gains can hide newly failing queries.</T>
+  <T x={860} y={804} size={30} color={muted}>Identify which queries improve or regress.</T>
+  <line x1={112} y1={849} x2={1808} y2={849} stroke={line} strokeWidth={2} />
+  <T y={920} size={30} color={muted}>Also unavailable: costs and reviewer agreement. Collect both before a rollout decision.</T>
+  <T y={964} size={30} color={muted}>These synthetic results establish neither production performance nor rollout readiness.</T>
+</Frame>;
+
+export const meta = { title: 'Waymark: evaluating a reranker', createdAt: '2026-09-12T14:20:00Z' };
+export const notes = [
+  'Decision: 59/80 baseline and 67/80 reranker. Only reranker satisfies both proposed gates. All supplied results are synthetic.',
+  'Bars share a 0–100% scale. Net category count changes do not identify individual query transitions.',
+  'Live-trial evidence collection is a recommendation, not a supplied operational trial design. No sample size, exposure fraction or duration was specified.',
+];
+export default [Gate, Tradeoff, Trial];

package/slides/retrospective/PROMPT.md

@@ -0,0 +1,43 @@
+Make a four-page retrospective for the engineers and product lead who built
+Dockline. Explain what they planned, what changed during the project, what
+they actually delivered and what they should do differently next time.
+
+---
+
+Dockline is a fictional tool for requesting temporary test environments.
+A four-week pilot involved two engineers and one product lead. The initial
+plan was to let teams request an environment, see its status, extend its
+expiry and have expired environments deleted automatically.
+
+Week 1: the team agreed the request fields and built a form plus a status
+page. Provisioning remained a manual operator task. They had not yet assigned
+an owner for deletion failures or defined which environments must be retained.
+
+Week 2: review with operators exposed two requirements: some environments
+needed a retention hold, and deletion needed an audit trail. The team removed
+automatic deletion from the pilot scope instead of adding it late. They kept
+expiry reminders and a manual cleanup queue.
+
+Week 3: eight invited users submitted 12 pilot requests. Nine included all
+required information; three needed clarification because the form did not
+explain the environment-owner field. Two users expected “submitted” to mean
+“ready”, although provisioning had not finished. Those two users may also
+have submitted requests needing clarification; the counts are separate.
+
+Week 4: the form gained an owner-field explanation, and the status page
+distinguished submitted, provisioning and ready. A second exercise used six
+new requests: all had the required fields. It did not retest status understanding.
+These are synthetic project records, not observations of a real pilot.
+
+---
+
+Delivered: request form, operator-updated status page, expiry reminders and
+manual cleanup queue. Provisioning and deletion remain manual. Self-service
+expiry extensions, retention holds, deletion audit trail and automatic deletion
+are not implemented. No time-saving or reliability measurements are available.
+
+The team's proposed lesson is to involve operators and define lifecycle
+ownership before committing to automation. The next step is to specify retention
+and audit behavior, assign a deletion-failure owner and retest status understanding.
+The small second exercise suggests the form change helped; it does not establish
+a lasting improvement or prove which change caused the result.

package/slides/retrospective/index.tsx

@@ -0,0 +1,105 @@
+import type { ReactNode } from 'react';
+import '../../lib/typeface.ts';
+
+const ink = '#182D39';
+const muted = '#4E606B';
+const accent = '#006C70';
+const line = '#B9C8CD';
+
+function Copy({ x, y, lines, size = 34, weight = 400, color = ink }: {
+  x: number; y: number; lines: string[]; size?: number; weight?: number; color?: string;
+}) {
+  return <text x={x} y={y} fontSize={size} fontWeight={weight} fill={color}>
+    {lines.map((text, i) => <tspan key={i} x={x} dy={i ? size * 1.35 : 0}>{text}</tspan>)}
+  </text>;
+}
+
+function Frame({ page, title, description, children }: {
+  page: number; title: string; description: string; children: ReactNode;
+}) {
+  return <svg xmlns="http://www.w3.org/2000/svg" width="1920" height="1080" viewBox="0 0 1920 1080"
+    fontFamily="IBM Plex Sans" role="img" aria-labelledby={`title-${page} desc-${page}`} data-dockline-page={page}>
+    <title id={`title-${page}`}>{title}</title>
+    <desc id={`desc-${page}`}>{description}</desc>
+    <rect width="1920" height="1080" fill="#FFFFFF" />
+    <Copy x={112} y={155} lines={[title]} size={64} weight={600} />
+    {children}
+    <Copy x={1710} y={1018} lines={[`${page} / 4`]} size={26} color={muted} />
+  </svg>;
+}
+
+const Plan = () => <Frame page={1} title="Dockline planned a self-service lifecycle"
+  description="A fictional temporary test-environment tool. Four weeks, two engineers, one product lead. Planned: request, view status, extend expiry, automatic deletion. Week 1 delivered a form and status page with manual operator provisioning. Deletion-failure ownership and retention rules were undefined.">
+  <Copy x={112} y={242} lines={['Fictional test-environment project · Four weeks · Two engineers + one product lead']} size={32} color={muted} />
+  {[
+    ['Request', 'Ask for an', 'environment'],
+    ['Track', 'See its', 'status'],
+    ['Extend', 'Move its', 'expiry date'],
+    ['Delete', 'Remove expired', 'environments automatically'],
+  ].map(([title, ...body], i) => <g key={title}>
+    <Copy x={112 + i * 430} y={402} lines={[title]} size={44} weight={600} color={accent} />
+    <Copy x={112 + i * 430} y={466} lines={body} size={32} />
+  </g>)}
+  <line x1={112} x2={1808} y1={601} y2={601} stroke={line} strokeWidth={2} />
+  <Copy x={112} y={682} lines={['Week 1']} size={38} weight={600} />
+  <Copy x={112} y={742} lines={['Request fields agreed.', 'Form and status page built.', 'Provisioning stayed with an operator.']} />
+  <Copy x={1030} y={682} lines={['Lifecycle questions left open']} size={38} weight={600} />
+  <Copy x={1030} y={742} lines={['Who owns deletion failures?', 'Which environments must be retained?']} />
+</Frame>;
+
+const Scope = () => <Frame page={2} title="Operator review changed the pilot scope"
+  description="In week 2 operators identified retention holds and a deletion audit trail as requirements. Rather than adding these late, the team removed automatic deletion. Delivered: request form, operator-updated status page, expiry reminders and manual cleanup queue. Provisioning and deletion remain manual.">
+  <Copy x={112} y={270} lines={['Week 2 · Requirements surfaced']} size={36} weight={600} color={accent} />
+  <Copy x={112} y={344} lines={['Some environments needed', 'a retention hold.', '', 'Deletion needed an audit trail.']} size={38} />
+  <Copy x={1050} y={270} lines={['Scope decision']} size={36} weight={600} color={accent} />
+  <Copy x={1050} y={344} lines={['Remove automatic deletion', 'from the pilot rather than', 'add these requirements late.']} size={38} />
+  <line x1={112} x2={1808} y1={601} y2={601} stroke={line} strokeWidth={2} />
+  <Copy x={112} y={681} lines={['Delivered']} size={42} weight={600} />
+  <Copy x={112} y={754} lines={['Request form', 'Operator-updated status page']} size={36} />
+  <Copy x={1050} y={754} lines={['Expiry reminders', 'Manual cleanup queue']} size={36} />
+  <Copy x={112} y={912} lines={['Provisioning and deletion remain manual.']} size={34} weight={500} color={accent} />
+</Frame>;
+
+const Evidence = () => <Frame page={3} title="Form completeness improved in a small retest"
+  description="Week 3: eight invited users made 12 requests; nine complete and three needing clarification because the environment-owner field was unexplained. Two users confused submitted with ready; these user and request counts may overlap. Week 4 added an owner explanation and distinct submitted, provisioning and ready states. All six new requests had required fields. Status understanding was not retested. This suggests help, not lasting improvement or causation.">
+  <Copy x={112} y={213} lines={['Synthetic pilot records']} size={28} color={muted} />
+  <Copy x={112} y={270} lines={['Week 3 · Eight invited users']} size={36} weight={600} />
+  <Copy x={1050} y={270} lines={['Week 4 · Six new requests']} size={36} weight={600} />
+  <Copy x={112} y={383} lines={['9 of 12']} size={76} weight={600} color={accent} />
+  <Copy x={1050} y={383} lines={['6 of 6']} size={76} weight={600} color={accent} />
+  <Copy x={112} y={440} lines={['requests had all required information.']} size={32} />
+  <Copy x={1050} y={440} lines={['new requests had all required fields.']} size={32} />
+  <Copy x={112} y={524} lines={['Three needed clarification:', 'the environment-owner field', 'was not explained.']} size={34} />
+  <Copy x={1050} y={524} lines={['Added an owner-field explanation.', 'Status now distinguishes submitted,', 'provisioning and ready.']} size={34} />
+  <line x1={112} x2={1808} y1={665} y2={665} stroke={line} strokeWidth={2} />
+  <Copy x={112} y={726} lines={['Two users read “submitted” as “ready”.', 'They may overlap with requests needing', 'clarification; these are separate counts.']} size={32} />
+  <Copy x={1050} y={726} lines={['Status understanding was not retested.', 'The form result suggests help, but does', 'not establish lasting improvement', 'or which change caused the result.']} size={32} />
+</Frame>;
+
+const Next = () => <Frame page={4} title="Define lifecycle ownership before automation"
+  description="The proposed lesson is to involve operators and define lifecycle ownership before committing to automation. Next: specify retention and audit behavior, assign a deletion-failure owner and retest status understanding. Not implemented: self-service expiry extensions, retention holds, deletion audit trail or automatic deletion. No time-saving or reliability measurements are available.">
+  <Copy x={112} y={246} lines={['Proposed lesson: involve operators before committing to automation.']} size={34} color={muted} />
+  <Copy x={112} y={352} lines={['Next steps']} size={40} weight={600} color={accent} />
+  {[
+    ['Specify behavior', 'Define retention holds and deletion audit behavior.'],
+    ['Assign ownership', 'Name the owner for deletion failures.'],
+    ['Retest understanding', 'Check whether users distinguish submitted from ready.'],
+  ].map(([heading, body], i) => <g key={heading}>
+    <line x1={112} x2={1808} y1={394 + i * 116} y2={394 + i * 116} stroke={line} strokeWidth={2} />
+    <Copy x={112} y={460 + i * 116} lines={[heading]} size={34} weight={600} />
+    <Copy x={650} y={460 + i * 116} lines={[body]} size={34} />
+  </g>)}
+  <line x1={112} x2={1808} y1={742} y2={742} stroke={line} strokeWidth={2} />
+  <Copy x={112} y={819} lines={['Not implemented']} size={32} weight={600} />
+  <Copy x={650} y={819} lines={['Self-service expiry extensions, retention holds,', 'deletion audit trail and automatic deletion.']} size={32} />
+  <Copy x={112} y={942} lines={['No time-saving or reliability measurements are available.']} size={32} color={muted} />
+</Frame>;
+
+export const meta = { title: 'Dockline — four-week retrospective' };
+export const notes = [
+  'Synthetic project records supplied in PROMPT.md; not observations of a real pilot. The initial plan was broader than the delivered pilot.',
+  'Retention and audit requirements were discovered, not implemented. Removing automatic deletion was the explicit scope decision.',
+  'Do not add the two users to the three requests. Different denominators and possible overlap. Six new requests are a small exercise, not a causal test.',
+  'These are proposed next steps, not completed work or a delivery commitment. No measured time-saving or reliability claims are supported.',
+];
+export default [Plan, Scope, Evidence, Next];

package/slides/sankey/PROMPT.md

@@ -0,0 +1,11 @@
+Make a one-page operations briefing for fictional support team Brook, using a Sankey chart to show how 120 support tickets moved from intake channel through routing to outcome.
+
+---
+
+Web intake supplied 70 tickets: 50 entered automated handling and 20 entered specialist handling. Email supplied 50: 30 entered automated handling and 20 entered specialist handling.
+
+Of the 80 tickets in automated handling, 70 were resolved and 10 escalated. Of the 40 in specialist handling, 20 were resolved and 20 escalated. Each ticket follows one route at each stage; there are no loops, duplicates or omitted tickets. These are synthetic, hand-authored counts for one fictional week.
+
+---
+
+Use flow widths proportional to ticket counts and directly label nodes and link counts. Make the total of 120 and conservation through intermediate nodes clear. Show that specialist handling accounts for 20 of the 30 escalations, without implying it causes escalation or performs worse: ticket complexity and routing criteria are unknown. Channel-to-outcome breakdowns are not supplied and must not be inferred from the merged flows.

package/slides/sankey/index.tsx

@@ -0,0 +1,93 @@
+import { Sankey, type CustomSankeyLayerProps, type DefaultLink } from '@nivo/sankey';
+import { chartDefaults } from '../../lib/charts';
+import { palettes } from '../../lib/taste';
+import '../../lib/typeface';
+
+type Node = { id: string; fill: string };
+const data = {
+  nodes: [
+    { id: 'Web', fill: '#526579' },
+    { id: 'Email', fill: '#526579' },
+    { id: 'Automated', fill: '#2458C7' },
+    { id: 'Specialist', fill: '#2458C7' },
+    { id: 'Resolved', fill: '#526579' },
+    { id: 'Escalated', fill: '#98451F' },
+  ],
+  links: [
+    { source: 'Web', target: 'Automated', value: 50 },
+    { source: 'Web', target: 'Specialist', value: 20 },
+    { source: 'Email', target: 'Automated', value: 30 },
+    { source: 'Email', target: 'Specialist', value: 20 },
+    { source: 'Automated', target: 'Resolved', value: 70 },
+    { source: 'Automated', target: 'Escalated', value: 10 },
+    { source: 'Specialist', target: 'Resolved', value: 20 },
+    { source: 'Specialist', target: 'Escalated', value: 20 },
+  ],
+};
+
+function DirectLabels({ nodes, links }: CustomSankeyLayerProps<Node, DefaultLink>) {
+  return <g fill="#172331" fontFamily="IBM Plex Sans" fontSize={30} fontWeight={500}>
+    {links.map(link => {
+      // Label close to the source: crossing ribbons remain individually identifiable.
+      const t = 0.24;
+      const x = link.source.x1 + (link.target.x0 - link.source.x1) * t;
+      const curveT = (t - 0.5) * 2;
+      // Invert the symmetric cubic's x coordinate to find its corresponding y.
+      let u = t;
+      for (let i = 0; i < 8; i++) {
+        u -= (3 * u - 3 * u * u + 2 * u * u * u - (curveT + 1)) / (3 - 6 * u + 6 * u * u);
+      }
+      const y = link.pos0 + (link.pos1 - link.pos0) * (3 * u * u - 2 * u * u * u);
+      return <g key={`${link.source.id}-${link.target.id}`} data-flow={`${link.source.id}-${link.target.id}`}
+        data-count={link.value} data-thickness={link.thickness}>
+        <rect x={x - 27} y={y - 23} width={54} height={46} rx={9} fill="white" />
+        <text x={x} y={y + 10} textAnchor="middle">{link.value}</text>
+      </g>;
+    })}
+    {nodes.map(node => {
+      const middle = node.depth === 1;
+      const x = node.depth === 0 ? node.x0 - 20 : middle ? (node.x0 + node.x1) / 2 : node.x1 + 20;
+      const y = middle ? node.y0 - 18 : (node.y0 + node.y1) / 2 - 6;
+      return <text key={node.id} x={x} y={y} textAnchor={node.depth === 0 ? 'end' : middle ? 'middle' : 'start'}
+        data-node={node.id} data-total={node.value} data-height={node.height}
+        stroke="white" strokeWidth={7} paintOrder="stroke" strokeLinejoin="round">
+        {middle ? `${node.id} · ${node.value}` : node.id}
+        {!middle && <tspan x={x} dy={38} fontSize={34} fontWeight={600}>{node.value}</tspan>}
+      </text>;
+    })}
+  </g>;
+}
+
+const Brook = () => <svg xmlns="http://www.w3.org/2000/svg" width={1920} height={1080}
+  viewBox="0 0 1920 1080" fontFamily="IBM Plex Sans" role="img" aria-labelledby="brook-title brook-description">
+  <title id="brook-title">Specialist handling accounts for 20 of 30 escalations</title>
+  <desc id="brook-description">Brook, a fictional support team. 120 tickets in one synthetic week.
+    Web 70: 50 automated, 20 specialist. Email 50: 30 automated, 20 specialist.
+    Automated 80: 70 resolved, 10 escalated. Specialist 40: 20 resolved, 20 escalated.
+    Resolved total 90; escalated total 30. Each stage conserves 120 tickets.
+    Complexity and routing criteria are unknown; this does not establish causation or relative performance.
+    Channel-to-outcome breakdowns are not supplied and cannot be inferred through merged flows.</desc>
+  <rect width={1920} height={1080} fill="white" />
+  <text x={100} y={122} fill="#172331" fontSize={60} fontWeight={600}>Specialist handling accounts for</text>
+  <text x={100} y={193} fill="#172331" fontSize={60} fontWeight={600}>20 of 30 escalations</text>
+  <text x={100} y={255} fill="#475564" fontSize={30}>Brook support · 120 tickets · One fictional week · Synthetic, hand-authored counts</text>
+  <g fill="#475564" fontSize={27} fontWeight={500}>
+    <text x={280} y={321}>Intake · 120</text>
+    <text x={940} y={321} textAnchor="middle">Handling · 120</text>
+    <text x={1620} y={321} textAnchor="end">Outcome · 120</text>
+  </g>
+  <g transform="translate(100 345)">
+    <Sankey<Node, DefaultLink> {...chartDefaults(palettes.paper)} data={data}
+      width={1720} height={485} margin={{ top: 42, right: 200, bottom: 0, left: 180 }}
+      colors={node => node.fill} sort="input" align="justify" nodeThickness={24}
+      nodeSpacing={95} nodeBorderWidth={0} nodeBorderRadius={0} linkContract={0}
+      linkOpacity={0.28} linkBlendMode="normal" enableLinkGradient={false}
+      labelTextColor="#172331" layers={['links', 'nodes', DirectLabels]} />
+  </g>
+  <text x={100} y={883} fill="#172331" fontSize={29} fontWeight={500}>Every ticket follows one route per stage; no loops, duplicates or omissions.</text>
+  <text x={100} y={939} fill="#475564" fontSize={28}>Complexity and routing criteria are unknown; these counts do not establish cause or performance.</text>
+  <text x={100} y={986} fill="#475564" fontSize={28}>Channel-to-outcome breakdowns are not supplied and cannot be inferred through the merged flows.</text>
+</svg>;
+
+export const meta = { title: 'Brook — support ticket flow' };
+export default [Brook];

package/slides/teaching/PROMPT.md

@@ -0,0 +1,45 @@
+Make a four-page explanation of optimistic concurrency for junior backend
+engineers who know HTTP and basic database updates. Use a worked editing
+conflict to show why checking a revision and writing must be one atomic action.
+
+Use sequence diagrams to show the two clients' saves: first the successful
+atomic update and rejected stale save, then the contrasting race when checking
+and writing are separate. Make the request order and stored revisions visible.
+
+---
+
+The fictional application Folio stores a document's title and integer revision.
+Document 42 initially has title “Launch notes” and revision 7. Leena and Omar
+both read that state before either saves.
+
+Leena changes the title to “Launch checklist”. Omar changes it to “Release notes”.
+With an unconditional update, Leena's save can succeed and then Omar's stale
+save can replace it. The application loses Leena's title without warning.
+
+In the revised contract, each save supplies the revision it read. The server
+performs one atomic conditional update: match document ID and expected revision,
+write the new title and increment the revision. It reports success only when
+one row changed. Every title writer uses this contract; a revision is never reused
+for this document, including after any restoration. Assume no deletion here.
+
+Leena's request expects revision 7 and succeeds, storing “Launch checklist”
+at revision 8. Omar's request also expects 7 and changes zero rows. The server
+returns HTTP 409 Conflict and leaves revision 8 untouched.
+
+After a conflict, the client fetches the current document and shows the user
+both versions. It does not silently retry the stale title with revision 8.
+The user decides whether to keep, revise or replace the current title; a new
+save must use the newly fetched revision and can still conflict again.
+
+---
+
+Contrast the atomic update with a separate read-then-write check: both requests
+could read revision 7, both pass the check and then overwrite one another.
+The correctness comes from the database's atomic condition, not the revision
+number merely appearing in the request.
+
+This prevents silent lost updates under the stated contract. It does not merge
+edits, choose the better title or make a multi-document change atomic. If a
+successful response is lost, retrying with the old revision can return a
+conflict even though the first save succeeded; revision checks alone do not
+provide request deduplication or an exactly-once acknowledgement.

package/slides/teaching/index.tsx

@@ -0,0 +1,124 @@
+import type { ReactNode } from 'react';
+import '../../lib/typeface.ts';
+
+const ink = '#172B3A';
+const muted = '#495D6C';
+const accent = '#006B75';
+const line = '#A8B6BE';
+
+function Text({ x, y, children, size = 34, weight = 400, color = ink, anchor = 'start' }: {
+  x: number; y: number; children: ReactNode; size?: number; weight?: number; color?: string;
+  anchor?: 'start' | 'middle' | 'end';
+}) {
+  return <text x={x} y={y} fontSize={size} fontWeight={weight} fill={color} textAnchor={anchor}>{children}</text>;
+}
+
+function Frame({ page, title, description, children }: { page: number; title: string; description: string; children: ReactNode }) {
+  return <svg xmlns="http://www.w3.org/2000/svg" width="1920" height="1080" viewBox="0 0 1920 1080"
+    fontFamily="IBM Plex Sans" role="img" aria-labelledby={`title-${page} desc-${page}`}>
+    <title id={`title-${page}`}>{title}</title><desc id={`desc-${page}`}>{description}</desc>
+    <rect width="1920" height="1080" fill="#FFFFFF" />
+    <Text x={100} y={140} size={66} weight={600}>{title}</Text>
+    {children}
+    <Text x={1820} y={1024} size={28} color={muted} anchor="end">{page} / 4</Text>
+  </svg>;
+}
+
+function Arrow({ from, to, y, label, detail }: { from: number; to: number; y: number; label: string; detail?: string }) {
+  const sign = to > from ? 1 : -1;
+  return <g>
+    <Text x={(from + to) / 2} y={y - (detail ? 55 : 20)} anchor="middle" size={32} weight={500}>{label}</Text>
+    {detail && <Text x={(from + to) / 2} y={y - 17} anchor="middle" size={30} color={muted}>{detail}</Text>}
+    <path d={`M${from} ${y} H${to} M${to - sign * 16} ${y - 10} L${to} ${y} L${to - sign * 16} ${y + 10}`}
+      fill="none" stroke={accent} strokeWidth={3} strokeLinejoin="round" />
+  </g>;
+}
+
+function Lanes({ middle = 'Server + database', bottom = 795 }: { middle?: string; bottom?: number }) {
+  return <g>{[[200, 'Leena'], [960, middle], [1720, 'Omar']].map(([x, label]) => <g key={label}>
+    <Text x={Number(x)} y={280} size={36} weight={600} anchor="middle">{label}</Text>
+    <line x1={Number(x)} x2={Number(x)} y1={303} y2={bottom} stroke={line} strokeWidth={2} strokeDasharray="6 8" />
+  </g>)}</g>;
+}
+
+function State({ y, children }: { y: number; children: ReactNode }) {
+  return <g><rect x={650} y={y - 33} width={620} height={50} fill="#FFFFFF" stroke={accent} strokeWidth={2} />
+    <Text x={960} y={y} size={30} weight={500} anchor="middle" color={accent}>{children}</Text></g>;
+}
+
+const LostUpdate = () => <Frame page={1} title="A stale save can erase someone else’s edit"
+  description="Folio is fictional. Document 42 initially stores Launch notes, revision 7. Leena and Omar both read it. Leena drafts Launch checklist; Omar drafts Release notes. With unconditional updates, Leena saves first and Omar saves second, silently replacing Leena's title. Revisions alone cannot protect a write that does not check them.">
+  <Text x={100} y={219} color={muted}>Folio · fictional document editor · document 42</Text>
+  <Text x={100} y={333} size={36} weight={600}>Both read before either saves</Text>
+  <Text x={100} y={405} size={48}>“Launch notes”</Text>
+  <Text x={100} y={462} color={accent} weight={500}>Stored revision 7</Text>
+  <Text x={870} y={333} size={36} weight={600}>Leena’s draft</Text>
+  <Text x={870} y={395} size={40}>“Launch checklist”</Text>
+  <Text x={1430} y={333} size={36} weight={600}>Omar’s draft</Text>
+  <Text x={1430} y={395} size={40}>“Release notes”</Text>
+  <Text x={100} y={591} size={36} weight={600}>Without a revision condition</Text>
+  <line x1={100} x2={1820} y1={630} y2={630} stroke={line} strokeWidth={2} />
+  <Text x={100} y={697} weight={500}>1. Leena saves</Text>
+  <Text x={670} y={697}>Stored title becomes “Launch checklist”.</Text>
+  <line x1={100} x2={1820} y1={737} y2={737} stroke={line} strokeWidth={2} />
+  <Text x={100} y={807} weight={500}>2. Omar saves stale draft</Text>
+  <Text x={670} y={807}>Stored title becomes “Release notes”.</Text>
+  <line x1={100} x2={1820} y1={847} y2={847} stroke={line} strokeWidth={2} />
+  <Text x={100} y={939} size={40} color={accent} weight={500}>Leena’s title is lost. Both saves can appear successful.</Text>
+</Frame>;
+
+const Atomic = () => <Frame page={2} title="Make the revision check and write atomic"
+  description="Time flows down. Both clients read revision 7. Leena sends Launch checklist with expected revision 7. The database atomically matches document 42 and revision 7, writes the title and increments to 8. One row changes, so the server reports success. Omar sends Release notes expecting 7. Zero rows change, so the server returns HTTP 409 Conflict and preserves Launch checklist at revision 8. Every title writer must follow the contract, revisions are never reused even after restoration, and no deletion is assumed.">
+  <Text x={100} y={212} size={32} color={muted}>One database action: match ID + expected revision → write title + increment revision</Text>
+  <Lanes />
+  <Arrow from={200} to={960} y={378} label="Save “Launch checklist”" detail="document 42 · expected revision 7" />
+  <State y={423}>1 row changed · “Launch checklist” · rev 8</State>
+  <Arrow from={960} to={200} y={500} label="Success: one row changed" />
+  <Arrow from={1720} to={960} y={608} label="Save “Release notes”" detail="document 42 · expected revision 7" />
+  <State y={653}>0 rows changed · “Launch checklist” · rev 8</State>
+  <Arrow from={960} to={1720} y={774} label="HTTP 409 Conflict" detail="Expected 7 no longer matches stored 8" />
+  <Text x={100} y={863} size={36} weight={600}>Success means exactly one row changed.</Text>
+  <Text x={100} y={920} size={30}>All writers use this contract; revisions are never reused, even after restoration. Assume no deletion.</Text>
+  <Text x={100} y={969} size={30} color={muted}>Prevents silent lost updates; does not merge edits, choose a better title or make multi-document changes atomic.</Text>
+</Frame>;
+
+const Race = () => <Frame page={3} title="Separate checks leave a race between writes"
+  description="Counterexample; time flows down. Stored revision begins at 7. Leena's separate check reads revision 7 and passes. Omar's separate check also reads 7 and passes before any write. Leena then writes Launch checklist unconditionally and increments to revision 8. Omar writes Release notes unconditionally and increments to revision 9, replacing Leena's edit. The illustrated writes increment the current stored revision but do not condition the write on it. Both checks passed; only an atomic database condition closes the race.">
+  <Text x={100} y={212} size={32} color={muted}>Counterexample · stored revision starts at 7 · time flows downward</Text>
+  <Lanes bottom={821} />
+  <Arrow from={200} to={960} y={374} label="Check expected 7" detail="Read stored 7 → passes" />
+  <Arrow from={1720} to={960} y={481} label="Check expected 7" detail="Read stored 7 → passes" />
+  <Arrow from={200} to={960} y={601} label="Write “Launch checklist”" detail="Unconditional write + increment" />
+  <State y={646}>“Launch checklist” · rev 8</State>
+  <Arrow from={1720} to={960} y={761} label="Write “Release notes”" detail="Unconditional write + increment" />
+  <State y={806}>“Release notes” · rev 9 · Leena’s edit lost</State>
+  <Text x={100} y={904} size={38} weight={500} color={accent}>Both checks passed. Neither constrained the later write.</Text>
+  <Text x={100} y={963} size={30} color={muted}>This example increments the stored revision on each write; the missing atomic condition causes the loss.</Text>
+</Frame>;
+
+const Recovery = () => <Frame page={4} title="After a conflict, let Omar choose what to save"
+  description="On HTTP 409, fetch the current document and show both versions: current Launch checklist at revision 8, and Omar's Release notes. Keep means leave Launch checklist unchanged with no write. Revise means edit a new title using both versions. Replace means deliberately save Release notes. Any new save must use the newly fetched revision, here 8, and can conflict again. Never silently retry Omar's stale title with revision 8. Under the contract this prevents silent lost updates, but does not merge edits, choose the better title, or make multi-document changes atomic. If a successful response is lost, retrying the old revision can conflict despite the first save succeeding; revision checks alone provide neither request deduplication nor exactly-once acknowledgement.">
+  <Text x={100} y={224} size={34}>Fetch the current document and show both titles before any new save.</Text>
+  <Text x={100} y={334} size={32} weight={600}>Current · revision 8</Text>
+  <Text x={100} y={391} size={41} color={accent}>“Launch checklist”</Text>
+  <Text x={1030} y={334} size={32} weight={600}>Omar’s draft</Text>
+  <Text x={1030} y={391} size={41}>“Release notes”</Text>
+  <line x1={100} x2={1820} y1={437} y2={437} stroke={line} strokeWidth={2} />
+  <Text x={100} y={502} weight={600}>Keep</Text>
+  <Text x={550} y={502} size={36}>Leave “Launch checklist” unchanged. No new save.</Text>
+  <line x1={100} x2={1820} y1={540} y2={540} stroke={line} strokeWidth={2} />
+  <Text x={100} y={604} weight={600}>Revise</Text>
+  <Text x={550} y={604} size={36}>Edit a new title using both versions, then save it.</Text>
+  <line x1={100} x2={1820} y1={642} y2={642} stroke={line} strokeWidth={2} />
+  <Text x={100} y={706} weight={600}>Replace</Text>
+  <Text x={550} y={706} size={36}>Deliberately save “Release notes” over the current title.</Text>
+  <line x1={100} x2={1820} y1={744} y2={744} stroke={line} strokeWidth={2} />
+  <Text x={100} y={810} size={36} weight={500} color={accent}>A deliberate new save uses the fetched revision, here 8. It can conflict again.</Text>
+  <Text x={100} y={865} size={32}>Never silently retry Omar’s stale title with revision 8.</Text>
+  <Text x={100} y={937} size={30} color={muted}>If a successful reply is lost, retrying the old revision may conflict even though the save succeeded.</Text>
+  <Text x={100} y={979} size={30} color={muted}>Revision checks alone provide neither request deduplication nor exactly-once acknowledgement.</Text>
+</Frame>;
+
+export const meta = { title: 'Folio — optimistic concurrency' };
+const pages = [LostUpdate, Atomic, Race, Recovery];
+export default pages;

package/slides/vertical-bar-charts/PROMPT.md

@@ -0,0 +1,13 @@
+Make a two-page engineering briefing for fictional document workspace Fieldnote. Page 1 should demonstrate a vertical bar chart. Page 2 should demonstrate two vertical bar charts side by side: throughput on the left, search visibility delay on the right.
+
+---
+
+Each configuration processed the same 60,000 document updates on the same machine, starting with an empty queue and identical index. Individual updates took 300 seconds with a p95 visibility delay of 2.4 seconds; batches of 20 took 200 seconds with p95 delay of 4.1 seconds; batches of 100 took 150 seconds with p95 delay of 11.8 seconds. Visibility delay runs from submission until the updated document appears in search. All final document versions were correct.
+
+These are synthetic, hand-authored results, with one run per configuration and no production measurements or uncertainty estimates.
+
+---
+
+Page 1 compares derived throughput: 200, 300 and 400 updates per second. Page 2 compares throughput against the proposed minimum of 250 updates per second and p95 visibility delay against the maximum of 5 seconds. Use zero-based axes, direct values and consistent category order. Each chart needs its own clearly labeled units and scale.
+
+Recommend batches of 20 for follow-up testing, not production adoption. Explain why maximum throughput alone is insufficient. Preserve the single-run limitation and the need to repeat tests with sparse arrivals and bursts.