docs: add serving-phase diagram to the introduction page (#264)

* feat(docs): add serving-phase diagram to the introduction page

The introduction's "How ktx works" section described both the ingest and serve sides but only rendered the ingestion diagram. Add a live, theme-aware React Flow diagram for the serving phase (agent <-> ktx via MCP -> context layer + database) so both phases are shown, with a matching content test.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(diagram-studio): relabel context edge and use right-angle routing

The hub->context edge searches and reads definitions, not just searches; relabel it "search + read". Route the serving search/read-only edges with smoothstep (right angles) to match the docs diagram. (The README PNG is a baked export and is unchanged until re-exported from the studio.)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(docs): point product-mechanics assertions at the FlowCanvas wrapper

product-mechanics renders via the shared FlowCanvas wrapper, so the ReactFlow config (nodesDraggable, zoomOnScroll, etc.) lives there now. Update the stale assertions that still expected those literals inline, fixing a pre-existing test failure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(serving-diagram): shrink the boxes and drop OpenCode from the agent list

Reduce node dimensions, font sizes, padding, and the canvas height so the serving diagram renders ~25% smaller and more compact. Remove OpenCode from the agent's listed clients.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

docs-site/tests/product-mechanics-content.test.mjs

@@ -85,7 +85,7 @@ test("product mechanics component explains ingestion outputs", async () => {
     "compile into SQL",
     '"use client"',
     "@xyflow/react",
-    "<ReactFlow",
+    "<FlowCanvas",
     "getSmoothStepPath",
     "animateMotion",
     "mechanics-particle",
@@ -97,21 +97,21 @@ test("product mechanics component explains ingestion outputs", async () => {
     );
   }
 
-  assert.match(
-    component,
+  // The ReactFlow canvas config lives in the shared FlowCanvas wrapper, which
+  // product-mechanics renders. Assert the static read-only behavior there.
+  const flowCanvas = await readDocsFile("components/flow-canvas.tsx");
+  for (const guard of [
     /nodesDraggable=\{false\}/,
-    "ReactFlow canvas should disable node dragging",
-  );
-  assert.match(
-    component,
-    /panOnDrag=\{false\}/,
-    "ReactFlow canvas should disable panning",
-  );
-  assert.match(
-    component,
+    /nodesConnectable=\{false\}/,
     /zoomOnScroll=\{false\}/,
-    "ReactFlow canvas should disable scroll zoom",
-  );
+    /elementsSelectable=\{false\}/,
+  ]) {
+    assert.match(
+      flowCanvas,
+      guard,
+      `shared FlowCanvas should enforce static read-only behavior: ${guard}`,
+    );
+  }
 
   assert.doesNotMatch(component, /raw-sources/);
   assert.doesNotMatch(component, /\.ktx/);

docs-site/tests/product-runtime-content.test.mjs

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+const docsSiteDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+async function readDocsFile(path) {
+  return readFile(join(docsSiteDir, path), "utf8");
+}
+
+test("docs introduction renders the serving phase after ingestion", async () => {
+  const introduction = await readDocsFile(
+    "content/docs/getting-started/introduction.mdx",
+  );
+
+  assert.match(
+    introduction,
+    /import\s+\{\s*ProductRuntime\s*\}\s+from\s+"@\/components\/product-runtime";/,
+  );
+  assert.match(introduction, /<ProductRuntime\s*\/>/);
+
+  const mechanicsIndex = introduction.indexOf("<ProductMechanics />");
+  const runtimeIndex = introduction.indexOf("<ProductRuntime />");
+  const useCaseIndex = introduction.indexOf("## Use it for");
+
+  assert.ok(
+    runtimeIndex > mechanicsIndex,
+    "serving diagram should appear after the ingestion diagram",
+  );
+  assert.ok(
+    runtimeIndex < useCaseIndex,
+    "serving diagram should appear before use-case sections",
+  );
+});
+
+test("product runtime component explains the serving cycle", async () => {
+  const component = await readDocsFile("components/product-runtime.tsx");
+
+  for (const expectedText of [
+    "How serving works",
+    "Serving flow",
+    "From an agent request to a governed answer",
+    "Your agent",
+    "Claude Code",
+    "Cursor",
+    "Codex",
+    "Search wiki + semantic layer",
+    "Return approved metrics",
+    "Compile metrics → SQL",
+    "Context layer",
+    "Database",
+    "search + read",
+    "read-only",
+    "wiki/*.md",
+    "semantic-layer/*.yaml",
+    '"use client"',
+    "@xyflow/react",
+    "FlowCanvas",
+    "getSmoothStepPath",
+    "animateMotion",
+    "runtime-particle",
+    "buildCyclePath",
+  ]) {
+    assert.ok(
+      component.includes(expectedText),
+      `component should include: ${expectedText}`,
+    );
+  }
+
+  assert.doesNotMatch(component, /raw-sources/);
+  assert.doesNotMatch(component, /<img/);
+});