feat(docs): add Wasteland Flow diagrams (#10030)

* feat(docs): add Wasteland Flow diagrams (federation, lifecycle, claim-to-stamp)

* fix(docs): add px units to flowDiagram height attributes

Reviewers flagged that unitless height values render as invalid CSS
because Markdoc supplies them as strings. Adding px suffix matches
all existing FlowDiagram usages in the codebase.

packages/kilo-docs/components/FlowDiagram/diagrams/claim-to-stamp.ts

@@ -0,0 +1,213 @@
+import type { Node, Edge, Position } from "@xyflow/react"
+import type { DiagramDefinition } from "./index"
+
+const laneStyle = (rgb: string, color: string) => ({
+  padding: "10px 18px",
+  borderRadius: "8px",
+  fontSize: "12px",
+  fontFamily: "'JetBrains Mono', monospace",
+  fontWeight: 600,
+  textAlign: "center" as const,
+  minWidth: "140px",
+  background: `rgba(${rgb},0.1)`,
+  border: `1px solid rgba(${rgb},0.5)`,
+  color,
+})
+
+const gt = laneStyle("59,130,246", "#3b82f6")
+const wl = laneStyle("248,160,32", "#f8a020")
+const val = laneStyle("167,139,250", "#a78bfa")
+const rep = laneStyle("34,197,94", "#22c55e")
+
+const nodes: Node[] = [
+  {
+    id: "browse",
+    position: { x: 0, y: 0 },
+    data: { label: "Mayor browse" },
+    sourcePosition: "right" as Position,
+    targetPosition: "left" as Position,
+    style: gt,
+  },
+  {
+    id: "wl-return",
+    position: { x: 250, y: 0 },
+    data: { label: "Wasteland returns\nwanted items" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "left" as Position,
+    style: wl,
+  },
+  {
+    id: "claim",
+    position: { x: 0, y: 100 },
+    data: { label: "Mayor claim" },
+    sourcePosition: "right" as Position,
+    targetPosition: "left" as Position,
+    style: gt,
+  },
+  {
+    id: "wl-lock",
+    position: { x: 250, y: 100 },
+    data: { label: "Wasteland locks\nitem → DoltHub PR" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "left" as Position,
+    style: wl,
+  },
+  {
+    id: "work",
+    position: { x: 0, y: 210 },
+    data: { label: "Polecats work\n→ push branch" },
+    sourcePosition: "right" as Position,
+    targetPosition: "top" as Position,
+    style: gt,
+  },
+  {
+    id: "done",
+    position: { x: 0, y: 320 },
+    data: { label: "Mayor done\n(evidence)" },
+    sourcePosition: "right" as Position,
+    targetPosition: "left" as Position,
+    style: gt,
+  },
+  {
+    id: "wl-attach",
+    position: { x: 250, y: 320 },
+    data: { label: "Wasteland attaches\nevidence to PR" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "left" as Position,
+    style: wl,
+  },
+  {
+    id: "review",
+    position: { x: 500, y: 320 },
+    data: { label: "Validator\nreviews PR" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "left" as Position,
+    style: val,
+  },
+  {
+    id: "stamp",
+    position: { x: 500, y: 450 },
+    data: { label: "Stamps:\nquality · reliability\n· creativity" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "top" as Position,
+    style: val,
+  },
+  {
+    id: "reputation",
+    position: { x: 250, y: 560 },
+    data: { label: "Reputation ledger\nupdates" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "top" as Position,
+    style: rep,
+  },
+  {
+    id: "identity",
+    position: { x: 0, y: 560 },
+    data: { label: "Portable\nidentity" },
+    sourcePosition: "top" as Position,
+    targetPosition: "right" as Position,
+    style: rep,
+  },
+]
+
+const labelStyle = { fontSize: 10, fontFamily: "'JetBrains Mono', monospace", fill: "#888" }
+
+const edges: Edge[] = [
+  {
+    id: "browse-return",
+    source: "browse",
+    target: "wl-return",
+    type: "smoothstep",
+    animated: true,
+    label: "1 browse",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#3b82f6" },
+  },
+  {
+    id: "claim-lock",
+    source: "claim",
+    target: "wl-lock",
+    type: "smoothstep",
+    animated: true,
+    label: "2 claim",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#3b82f6" },
+  },
+  {
+    id: "lock-work",
+    source: "wl-lock",
+    target: "work",
+    type: "smoothstep",
+    label: "3 work",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#f8a020" },
+  },
+  {
+    id: "work-done",
+    source: "work",
+    target: "done",
+    type: "smoothstep",
+    animated: true,
+    style: { strokeWidth: 2, stroke: "#3b82f6" },
+  },
+  {
+    id: "done-attach",
+    source: "done",
+    target: "wl-attach",
+    type: "smoothstep",
+    animated: true,
+    label: "4 evidence",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#3b82f6" },
+  },
+  {
+    id: "attach-review",
+    source: "wl-attach",
+    target: "review",
+    type: "smoothstep",
+    animated: true,
+    label: "5 review",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#a78bfa" },
+  },
+  {
+    id: "review-stamp",
+    source: "review",
+    target: "stamp",
+    type: "smoothstep",
+    animated: true,
+    style: { strokeWidth: 2, stroke: "#a78bfa" },
+  },
+  {
+    id: "stamp-rep",
+    source: "stamp",
+    target: "reputation",
+    type: "smoothstep",
+    animated: true,
+    label: "6 reputation",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#22c55e" },
+  },
+  {
+    id: "rep-identity",
+    source: "reputation",
+    target: "identity",
+    type: "smoothstep",
+    animated: true,
+    style: { strokeWidth: 2, stroke: "#22c55e" },
+  },
+  {
+    id: "return-claim",
+    source: "wl-return",
+    target: "wl-lock",
+    type: "smoothstep",
+    style: { strokeWidth: 1, stroke: "#f8a020", strokeDasharray: "4 4" },
+  },
+]
+
+export const claimToStamp: DiagramDefinition = {
+  nodes,
+  edges,
+  caption:
+    "Claim-to-stamp flow — from browsing wanted items through claiming, working, submitting evidence, and earning stamps",
+}

packages/kilo-docs/components/FlowDiagram/diagrams/index.ts

@@ -2,6 +2,9 @@ import type { Node, Edge } from "@xyflow/react"
 import { beadLifecycle } from "./bead-lifecycle"
 import { adversarialLoop } from "./adversarial-loop"
 import { convoyExecution } from "./convoy-execution"
+import { wastelandFederation } from "./wasteland-federation"
+import { wantedLifecycle } from "./wanted-lifecycle"
+import { claimToStamp } from "./claim-to-stamp"
 
 export interface DiagramDefinition {
   nodes: Node[]
@@ -13,4 +16,7 @@ export const diagrams: Record<string, DiagramDefinition> = {
   "bead-lifecycle": beadLifecycle,
   "adversarial-loop": adversarialLoop,
   "convoy-execution": convoyExecution,
+  "wasteland-federation": wastelandFederation,
+  "wanted-lifecycle": wantedLifecycle,
+  "claim-to-stamp": claimToStamp,
 }

packages/kilo-docs/components/FlowDiagram/diagrams/wanted-lifecycle.ts

@@ -0,0 +1,170 @@
+import type { Node, Edge, Position } from "@xyflow/react"
+import type { DiagramDefinition } from "./index"
+
+const stateStyle = (color: string, rgb: string) => ({
+  padding: "12px 20px",
+  borderRadius: "8px",
+  fontSize: "13px",
+  fontFamily: "'JetBrains Mono', monospace",
+  fontWeight: 600,
+  textAlign: "center" as const,
+  minWidth: "120px",
+  background: `rgba(${rgb},0.1)`,
+  border: `1px solid rgba(${rgb},0.5)`,
+  color,
+})
+
+const nodes: Node[] = [
+  {
+    id: "posted",
+    position: { x: 0, y: 0 },
+    data: { label: "posted" },
+    sourcePosition: "right" as Position,
+    targetPosition: "top" as Position,
+    style: stateStyle("#22c55e", "34,197,94"),
+  },
+  {
+    id: "claimed",
+    position: { x: 200, y: 0 },
+    data: { label: "claimed" },
+    sourcePosition: "right" as Position,
+    targetPosition: "left" as Position,
+    style: stateStyle("#3b82f6", "59,130,246"),
+  },
+  {
+    id: "in_progress",
+    position: { x: 400, y: 0 },
+    data: { label: "in_progress" },
+    sourcePosition: "right" as Position,
+    targetPosition: "left" as Position,
+    style: stateStyle("#f8a020", "248,160,32"),
+  },
+  {
+    id: "evidence_submitted",
+    position: { x: 600, y: 0 },
+    data: { label: "evidence_submitted" },
+    sourcePosition: "right" as Position,
+    targetPosition: "left" as Position,
+    style: stateStyle("#a78bfa", "167,139,250"),
+  },
+  {
+    id: "stamped",
+    position: { x: 850, y: 0 },
+    data: { label: "✓ stamped" },
+    sourcePosition: "top" as Position,
+    targetPosition: "left" as Position,
+    style: stateStyle("#22c55e", "34,197,94"),
+  },
+  {
+    id: "rejected",
+    position: { x: 600, y: 160 },
+    data: { label: "rejected" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "top" as Position,
+    style: stateStyle("#ef4444", "239,68,68"),
+  },
+  {
+    id: "abandoned",
+    position: { x: 200, y: 160 },
+    data: { label: "abandoned" },
+    sourcePosition: "top" as Position,
+    targetPosition: "top" as Position,
+    style: stateStyle("#888", "255,255,255"),
+  },
+]
+
+const labelStyle = { fontSize: 10, fontFamily: "'JetBrains Mono', monospace", fill: "#888" }
+
+const edges: Edge[] = [
+  {
+    id: "posted-claimed",
+    source: "posted",
+    target: "claimed",
+    type: "smoothstep",
+    animated: true,
+    label: "rig claims",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#3b82f6" },
+  },
+  {
+    id: "claimed-progress",
+    source: "claimed",
+    target: "in_progress",
+    type: "smoothstep",
+    animated: true,
+    label: "work starts",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#f8a020" },
+  },
+  {
+    id: "progress-evidence",
+    source: "in_progress",
+    target: "evidence_submitted",
+    type: "smoothstep",
+    animated: true,
+    label: "submit evidence",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#a78bfa" },
+  },
+  {
+    id: "evidence-stamped",
+    source: "evidence_submitted",
+    target: "stamped",
+    type: "smoothstep",
+    animated: true,
+    label: "validator approves",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#22c55e" },
+  },
+  {
+    id: "evidence-rejected",
+    source: "evidence_submitted",
+    target: "rejected",
+    type: "smoothstep",
+    label: "validator rejects",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#ef4444", strokeDasharray: "5 3" },
+  },
+  {
+    id: "rejected-progress",
+    source: "rejected",
+    target: "in_progress",
+    type: "smoothstep",
+    label: "rework",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#f8a020", strokeDasharray: "5 3" },
+  },
+  {
+    id: "rejected-posted",
+    source: "rejected",
+    target: "posted",
+    type: "smoothstep",
+    label: "release",
+    labelStyle,
+    style: { strokeWidth: 1, stroke: "#888", strokeDasharray: "4 4" },
+  },
+  {
+    id: "claimed-abandoned",
+    source: "claimed",
+    target: "abandoned",
+    type: "smoothstep",
+    label: "claim released",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#888", strokeDasharray: "5 3" },
+  },
+  {
+    id: "abandoned-posted",
+    source: "abandoned",
+    target: "posted",
+    type: "smoothstep",
+    label: "re-post",
+    labelStyle,
+    style: { strokeWidth: 1, stroke: "#888", strokeDasharray: "4 4" },
+  },
+]
+
+export const wantedLifecycle: DiagramDefinition = {
+  nodes,
+  edges,
+  caption: "Wanted item lifecycle — from posted through claimed, in-progress, evidence, and stamped (or rejected)",
+}

packages/kilo-docs/components/FlowDiagram/diagrams/wasteland-federation.ts

@@ -0,0 +1,186 @@
+import type { Node, Edge, Position } from "@xyflow/react"
+import type { DiagramDefinition } from "./index"
+
+const townStyle = {
+  padding: "10px 16px",
+  borderRadius: "8px",
+  fontSize: "12px",
+  fontFamily: "'JetBrains Mono', monospace",
+  fontWeight: 600,
+  textAlign: "center" as const,
+  minWidth: "130px",
+  background: "rgba(59,130,246,0.1)",
+  border: "1px solid rgba(59,130,246,0.5)",
+  color: "#3b82f6",
+}
+
+const wastelandStyle = {
+  padding: "14px 24px",
+  borderRadius: "10px",
+  fontSize: "13px",
+  fontFamily: "'JetBrains Mono', monospace",
+  fontWeight: 700,
+  textAlign: "center" as const,
+  minWidth: "180px",
+  background: "rgba(248,160,32,0.1)",
+  border: "1px solid rgba(248,160,32,0.5)",
+  color: "#f8a020",
+}
+
+const dbStyle = {
+  padding: "10px 18px",
+  borderRadius: "6px",
+  fontSize: "11px",
+  fontFamily: "'JetBrains Mono', monospace",
+  fontWeight: 600,
+  textAlign: "center" as const,
+  minWidth: "140px",
+  background: "rgba(139,92,246,0.08)",
+  border: "1px solid rgba(139,92,246,0.4)",
+  color: "#8b5cf6",
+}
+
+const nodes: Node[] = [
+  {
+    id: "town-you",
+    position: { x: 0, y: 0 },
+    data: { label: "Your Town" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "top" as Position,
+    style: townStyle,
+  },
+  {
+    id: "town-acme",
+    position: { x: 200, y: 0 },
+    data: { label: "Acme Eng Town" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "top" as Position,
+    style: townStyle,
+  },
+  {
+    id: "town-oss",
+    position: { x: 420, y: 0 },
+    data: { label: "Open Source Town" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "top" as Position,
+    style: townStyle,
+  },
+  {
+    id: "commons-wl",
+    position: { x: 120, y: 180 },
+    data: { label: "Commons Wasteland" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "top" as Position,
+    style: wastelandStyle,
+  },
+  {
+    id: "commons-db",
+    position: { x: 140, y: 340 },
+    data: { label: "DoltHub DB" },
+    sourcePosition: "top" as Position,
+    targetPosition: "top" as Position,
+    style: dbStyle,
+  },
+  {
+    id: "private-wl",
+    position: { x: 480, y: 180 },
+    data: { label: "Private Team\nWasteland" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "top" as Position,
+    style: wastelandStyle,
+  },
+  {
+    id: "private-town1",
+    position: { x: 440, y: 0 },
+    data: { label: "Private Town" },
+    sourcePosition: "bottom" as Position,
+    targetPosition: "top" as Position,
+    style: townStyle,
+  },
+  {
+    id: "private-db",
+    position: { x: 500, y: 340 },
+    data: { label: "DoltHub DB" },
+    sourcePosition: "top" as Position,
+    targetPosition: "top" as Position,
+    style: dbStyle,
+  },
+]
+
+const labelStyle = { fontSize: 10, fontFamily: "'JetBrains Mono', monospace", fill: "#888" }
+
+const edges: Edge[] = [
+  {
+    id: "town-you-wl",
+    source: "town-you",
+    target: "commons-wl",
+    type: "smoothstep",
+    animated: true,
+    label: "claim / submit",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#3b82f6" },
+  },
+  {
+    id: "town-acme-wl",
+    source: "town-acme",
+    target: "commons-wl",
+    type: "smoothstep",
+    animated: true,
+    label: "claim / submit",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#3b82f6" },
+  },
+  {
+    id: "town-oss-wl",
+    source: "town-oss",
+    target: "commons-wl",
+    type: "smoothstep",
+    animated: true,
+    label: "claim / submit",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#3b82f6" },
+  },
+  {
+    id: "commons-wl-db",
+    source: "commons-wl",
+    target: "commons-db",
+    type: "smoothstep",
+    label: "persist",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#8b5cf6" },
+  },
+  {
+    id: "private-town1-wl",
+    source: "private-town1",
+    target: "private-wl",
+    type: "smoothstep",
+    animated: true,
+    label: "claim / submit",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#3b82f6" },
+  },
+  {
+    id: "private-wl-db",
+    source: "private-wl",
+    target: "private-db",
+    type: "smoothstep",
+    label: "persist",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#8b5cf6" },
+  },
+  {
+    id: "wl-federation",
+    source: "commons-wl",
+    target: "private-wl",
+    type: "smoothstep",
+    label: "portable identity",
+    labelStyle,
+    style: { strokeWidth: 2, stroke: "#f8a020", strokeDasharray: "6 3" },
+  },
+]
+
+export const wastelandFederation: DiagramDefinition = {
+  nodes,
+  edges,
+  caption: "Federated Wasteland architecture — towns connect to shared Wasteland instances backed by DoltHub",
+}

packages/kilo-docs/pages/code-with-ai/gastown/wasteland/concepts.md

@@ -12,7 +12,7 @@ Understanding the Wasteland starts with a handful of core concepts that show up
 <!-- TODO: Federation - how instances share portable identity; what is NOT shared -->
 <!-- TODO: Rig identity - how a Gas Town rig is addressed (org/repo handle, DoltHub binding) -->
 <!-- TODO: Wanted Board - shared queue of tasks; BrowserFrame wl-wanted-board.png -->
-<!-- TODO: Wanted item lifecycle - include {% flowDiagram name="wanted-lifecycle" height="400" /%} -->
+{% flowDiagram name="wanted-lifecycle" height="400px" /%}
 <!-- TODO: Claims - exclusive locking, TTL, abandon semantics -->
 <!-- TODO: Evidence - what counts, who submits (mayor via wl done) -->
 <!-- TODO: Stamps - multi-dimensional (quality, reliability, creativity), confidence, yearbook rule -->

packages/kilo-docs/pages/code-with-ai/gastown/wasteland/index.md

@@ -10,7 +10,7 @@ The Wasteland is a federated work protocol built into Gas Town by Kilo that conn
 
 <!-- TODO: Hero paragraph positioning Wasteland as federated work protocol for Gas Towns -->
 <!-- TODO: What is the Wasteland? (from blog post source material) -->
-<!-- TODO: Federation model - include {% flowDiagram name="wasteland-federation" height="500" /%} -->
+{% flowDiagram name="wasteland-federation" height="500px" /%}
 <!-- TODO: Table of roles (Rig, Validator, Administrator, Commons) -->
 <!-- TODO: Why use it through Gas Town by Kilo? -->
 <!-- TODO: Where to go next - links to Quick Start, Concepts, Workflow, Admin -->

packages/kilo-docs/pages/code-with-ai/gastown/wasteland/workflow.md

@@ -8,7 +8,7 @@ noindex: true
 
 The worker-side flow for picking up a wanted item, doing the work in your Gas Town, and turning completion into stamped reputation.
 
-<!-- TODO: Overview diagram - {% flowDiagram name="claim-to-stamp" height="550" /%} -->
+{% flowDiagram name="claim-to-stamp" height="550px" /%}
 <!-- TODO: Step 1 - Browse wanted items -->
 <!-- TODO: Step 2 - Claim (exclusive semantics, race resolution, TTL, abandon) -->
 <!-- TODO: Step 3 - Work (Mayor creates bead with wasteland_wanted_id link) -->