From 297a0227bbfcd8574b82298e4f6e14ebbb853e50 Mon Sep 17 00:00:00 2001 From: John Fawcett Date: Thu, 7 May 2026 10:48:26 -0500 Subject: [PATCH] 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. --- .../FlowDiagram/diagrams/claim-to-stamp.ts | 213 ++++++++++++++++++ .../components/FlowDiagram/diagrams/index.ts | 6 + .../FlowDiagram/diagrams/wanted-lifecycle.ts | 170 ++++++++++++++ .../diagrams/wasteland-federation.ts | 186 +++++++++++++++ .../gastown/wasteland/concepts.md | 2 +- .../code-with-ai/gastown/wasteland/index.md | 2 +- .../gastown/wasteland/workflow.md | 2 +- 7 files changed, 578 insertions(+), 3 deletions(-) create mode 100644 packages/kilo-docs/components/FlowDiagram/diagrams/claim-to-stamp.ts create mode 100644 packages/kilo-docs/components/FlowDiagram/diagrams/wanted-lifecycle.ts create mode 100644 packages/kilo-docs/components/FlowDiagram/diagrams/wasteland-federation.ts diff --git a/packages/kilo-docs/components/FlowDiagram/diagrams/claim-to-stamp.ts b/packages/kilo-docs/components/FlowDiagram/diagrams/claim-to-stamp.ts new file mode 100644 index 00000000000..d992b00ec18 --- /dev/null +++ b/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", +} diff --git a/packages/kilo-docs/components/FlowDiagram/diagrams/index.ts b/packages/kilo-docs/components/FlowDiagram/diagrams/index.ts index 547f5b8b83a..20de5b64002 100644 --- a/packages/kilo-docs/components/FlowDiagram/diagrams/index.ts +++ b/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 = { "bead-lifecycle": beadLifecycle, "adversarial-loop": adversarialLoop, "convoy-execution": convoyExecution, + "wasteland-federation": wastelandFederation, + "wanted-lifecycle": wantedLifecycle, + "claim-to-stamp": claimToStamp, } diff --git a/packages/kilo-docs/components/FlowDiagram/diagrams/wanted-lifecycle.ts b/packages/kilo-docs/components/FlowDiagram/diagrams/wanted-lifecycle.ts new file mode 100644 index 00000000000..4fd486192ee --- /dev/null +++ b/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)", +} diff --git a/packages/kilo-docs/components/FlowDiagram/diagrams/wasteland-federation.ts b/packages/kilo-docs/components/FlowDiagram/diagrams/wasteland-federation.ts new file mode 100644 index 00000000000..300551a3326 --- /dev/null +++ b/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", +} diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/concepts.md b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/concepts.md index 75cab11f0a6..13f9cb40f20 100644 --- a/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/concepts.md +++ b/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 - +{% flowDiagram name="wanted-lifecycle" height="400px" /%} diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/index.md b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/index.md index 9107d9b7eae..76c4b5e79ec 100644 --- a/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/index.md +++ b/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 - +{% flowDiagram name="wasteland-federation" height="500px" /%} diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/workflow.md b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/workflow.md index 74e2e62c7b6..ecb13914fd1 100644 --- a/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/workflow.md +++ b/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. - +{% flowDiagram name="claim-to-stamp" height="550px" /%}