From 890211275fae9b548dd932500a6d71b4ed66ea6c Mon Sep 17 00:00:00 2001
From: John Fawcett <john@kilocode.ai>
Date: Thu, 7 May 2026 10:16:31 -0500
Subject: [PATCH] docs(kilo-docs): scaffold Wasteland docs section + register
 in nav (#10028)

* docs(kilo-docs): scaffold Wasteland docs section

Add stub pages for the Wasteland federated work protocol under
gastown/wasteland/ and register them in the code-with-ai nav.

SideNav only renders one level of subLinks, so Wasteland pages are
flattened into the Gastown subLinks list with a 'Wasteland: ' prefix.

Content for each stub will be filled in by later beads in the convoy.

* docs(kilo-docs): noindex Wasteland stub pages until content lands

Adds a noindex frontmatter flag (read by _app.tsx, emits a robots
noindex,nofollow meta tag) and applies it to the 7 Wasteland stub
pages. Stubs are intentionally thin in this scaffolding PR;
follow-up beads will flesh them out and remove the flag.
---
 packages/kilo-docs/lib/nav/code-with-ai.ts    |  7 ++++++
 packages/kilo-docs/pages/_app.tsx             |  2 ++
 .../code-with-ai/gastown/wasteland/admin.md   | 18 +++++++++++++++
 .../gastown/wasteland/concepts.md             | 22 +++++++++++++++++++
 .../code-with-ai/gastown/wasteland/index.md   | 17 ++++++++++++++
 .../gastown/wasteland/quick-start.md          | 19 ++++++++++++++++
 .../gastown/wasteland/settings.md             | 18 +++++++++++++++
 .../gastown/wasteland/troubleshooting.md      | 18 +++++++++++++++
 .../gastown/wasteland/workflow.md             | 19 ++++++++++++++++
 9 files changed, 140 insertions(+)
 create mode 100644 packages/kilo-docs/pages/code-with-ai/gastown/wasteland/admin.md
 create mode 100644 packages/kilo-docs/pages/code-with-ai/gastown/wasteland/concepts.md
 create mode 100644 packages/kilo-docs/pages/code-with-ai/gastown/wasteland/index.md
 create mode 100644 packages/kilo-docs/pages/code-with-ai/gastown/wasteland/quick-start.md
 create mode 100644 packages/kilo-docs/pages/code-with-ai/gastown/wasteland/settings.md
 create mode 100644 packages/kilo-docs/pages/code-with-ai/gastown/wasteland/troubleshooting.md
 create mode 100644 packages/kilo-docs/pages/code-with-ai/gastown/wasteland/workflow.md

diff --git a/packages/kilo-docs/lib/nav/code-with-ai.ts b/packages/kilo-docs/lib/nav/code-with-ai.ts
index 59f6d8a4bd2..08dae741ba5 100644
--- a/packages/kilo-docs/lib/nav/code-with-ai.ts
+++ b/packages/kilo-docs/lib/nav/code-with-ai.ts
@@ -34,6 +34,13 @@ export const CodeWithAiNav: NavSection[] = [
           { href: "/code-with-ai/gastown/code-review", children: "Code Review" },
           { href: "/code-with-ai/gastown/settings", children: "Settings" },
           { href: "/code-with-ai/gastown/troubleshooting", children: "Troubleshooting" },
+          { href: "/code-with-ai/gastown/wasteland", children: "Wasteland" },
+          { href: "/code-with-ai/gastown/wasteland/quick-start", children: "Wasteland: Quick Start" },
+          { href: "/code-with-ai/gastown/wasteland/concepts", children: "Wasteland: Concepts" },
+          { href: "/code-with-ai/gastown/wasteland/workflow", children: "Wasteland: Workflow" },
+          { href: "/code-with-ai/gastown/wasteland/admin", children: "Wasteland: Administration" },
+          { href: "/code-with-ai/gastown/wasteland/settings", children: "Wasteland: Settings" },
+          { href: "/code-with-ai/gastown/wasteland/troubleshooting", children: "Wasteland: Troubleshooting" },
         ],
       },
     ],
diff --git a/packages/kilo-docs/pages/_app.tsx b/packages/kilo-docs/pages/_app.tsx
index 245ab29af70..2739752f3a6 100644
--- a/packages/kilo-docs/pages/_app.tsx
+++ b/packages/kilo-docs/pages/_app.tsx
@@ -126,6 +126,7 @@ export default function MyApp({ Component, pageProps }: AppProps<MyAppProps>) {
       description = markdoc.frontmatter.description
     }
   }
+  const noindex = markdoc?.frontmatter?.noindex === true
 
   const toc = pageProps.markdoc?.content ? collectHeadings(pageProps.markdoc.content) : []
 
@@ -139,6 +140,7 @@ export default function MyApp({ Component, pageProps }: AppProps<MyAppProps>) {
         <meta name="referrer" content="strict-origin" />
         <meta name="title" content={title} />
         <meta name="description" content={description} />
+        {noindex && <meta name="robots" content="noindex, nofollow" />}
         <link rel="icon" href="/docs/favicon/favicon.ico" sizes="48x48" type="image/x-icon" />
         <link rel="shortcut icon" href="/docs/favicon/favicon.ico" />
         <link rel="icon" href="/docs/favicon/favicon.svg" type="image/svg+xml" />
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/admin.md b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/admin.md
new file mode 100644
index 00000000000..c3f6489e85e
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/admin.md
@@ -0,0 +1,18 @@
+---
+title: "Wasteland Administration"
+description: "Running a Wasteland: posting wanted items, reviewing submissions, stamping, merging, and managing members"
+noindex: true
+---
+
+# {% $markdoc.frontmatter.title %}
+
+Administrator and validator guide for running a Wasteland instance — posting work, reviewing evidence, stamping submissions, and managing your membership.
+
+<!-- TODO: Why run your own wasteland - team-private boards, scoped reputation, controlled validators -->
+<!-- TODO: Spinning up a wasteland in Gas Town -->
+<!-- TODO: Posting wanted items - via Mayor, via dashboard UI, fields -->
+<!-- TODO: The review inbox - BrowserFrame wl-admin-review-inbox.png -->
+<!-- TODO: Stamping work - dimensions, confidence, justification, yearbook rule -->
+<!-- TODO: Managing members - validator vs member, inviting, removing, permissions -->
+<!-- TODO: Moderation - removing wanted items, banning, escalation -->
+<!-- TODO: Federation choices - federate with Commons, accept incoming reputation -->
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
new file mode 100644
index 00000000000..75cab11f0a6
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/concepts.md
@@ -0,0 +1,22 @@
+---
+title: "Wasteland Concepts"
+description: "Core concepts: Wasteland instances, federation, Wanted Board, claims, evidence, stamps, reputation, DoltHub PRs, validators, and rig identity"
+noindex: true
+---
+
+# {% $markdoc.frontmatter.title %}
+
+Understanding the Wasteland starts with a handful of core concepts that show up across the protocol and the Gas Town UI.
+
+<!-- TODO: Wasteland instance - federated deployment backed by DoltHub database -->
+<!-- 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" /%} -->
+<!-- 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 -->
+<!-- TODO: Reputation ledger - built from stamps, portable, evidence-backed -->
+<!-- TODO: Validators - who can stamp, role permissions -->
+<!-- TODO: DoltHub PRs - how the protocol uses Dolt's Git-style semantics -->
+<!-- TODO: Cross-links to /docs/code-with-ai/gastown/wasteland/workflow and /admin -->
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
new file mode 100644
index 00000000000..9107d9b7eae
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/index.md
@@ -0,0 +1,17 @@
+---
+title: "Wasteland"
+description: "Federated work protocol connecting Gas Towns into a shared network of tasks, reputation, and collaboration"
+noindex: true
+---
+
+# {% $markdoc.frontmatter.title %}
+
+The Wasteland is a federated work protocol built into Gas Town by Kilo that connects towns together into a shared network of tasks, reputation, and evidence-backed collaboration.
+
+<!-- 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" /%} -->
+<!-- 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 -->
+<!-- TODO: BrowserFrame placeholders for Wasteland settings, Wanted Board, Mayor claiming, claim detail drawer -->
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/quick-start.md b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/quick-start.md
new file mode 100644
index 00000000000..001643127c4
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/quick-start.md
@@ -0,0 +1,19 @@
+---
+title: "Wasteland Quick Start"
+description: "Connect your town to the Commons wasteland, claim your first wanted item, and submit evidence"
+noindex: true
+---
+
+# {% $markdoc.frontmatter.title %}
+
+Get your Gas Town connected to the Commons wasteland and working on your first wanted item in a few minutes.
+
+<!-- TODO: Before you start - prerequisites (Gas Town, DoltHub account, rig connected) -->
+<!-- TODO: Connect your town to the Commons wasteland - BrowserFrame gt-wasteland-connect-dialog.png -->
+<!-- TODO: Browse the Wanted Board - BrowserFrame wl-wanted-board.png -->
+<!-- TODO: Claim your first wanted item - BrowserFrame wl-claim-drawer.png -->
+<!-- TODO: Let agents do the work -->
+<!-- TODO: Submit evidence - BrowserFrame wl-evidence-submitted.png -->
+<!-- TODO: Get stamped -->
+<!-- TODO: What's next -->
+<!-- TODO: Security callout recommending fine-grained DoltHub PATs -->
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/settings.md b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/settings.md
new file mode 100644
index 00000000000..bb0dba4ea34
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/settings.md
@@ -0,0 +1,18 @@
+---
+title: "Wasteland Settings"
+description: "Wasteland connection settings in the Gas Town dashboard, DoltHub token setup, and rig identity"
+noindex: true
+---
+
+# {% $markdoc.frontmatter.title %}
+
+Reference for every Wasteland-related setting in your Gas Town dashboard, from upstream selection to DoltHub PAT management.
+
+<!-- TODO: Wasteland connection - view connected wastelands, disconnecting -->
+<!-- TODO: Upstream - what upstream means, switching, Commons vs own -->
+<!-- TODO: Rig handle - town's identity on the wasteland, org/repo format -->
+<!-- TODO: DoltHub PAT - where to get, scope needed, rotation, fine-grained PAT recommendation -->
+<!-- TODO: Wanted item filters (verify from cloud repo WastelandSettingsSection.tsx) -->
+<!-- TODO: Evidence auto-submit - whether Mayor auto-submits on bead close -->
+<!-- TODO: Wasteland admin settings - link to admin page -->
+<!-- TODO: BrowserFrame placeholders for each tab -->
diff --git a/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/troubleshooting.md b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/troubleshooting.md
new file mode 100644
index 00000000000..357db0b8534
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/troubleshooting.md
@@ -0,0 +1,18 @@
+---
+title: "Wasteland Troubleshooting"
+description: "Common Wasteland problems: connection failures, claim conflicts, DoltHub auth issues, and stuck evidence"
+noindex: true
+---
+
+# {% $markdoc.frontmatter.title %}
+
+When Wasteland work goes sideways, start here — symptoms, diagnoses, and fixes for the most common problems.
+
+<!-- TODO: Still stuck? callout at top linking to Kilo support channels -->
+<!-- TODO: Connection problems (PAT invalid, connect dialog hangs, half-connected) -->
+<!-- TODO: DoltHub authentication (wrong scope, revoked, fine-grained PAT missing access) -->
+<!-- TODO: Claiming problems (conflicts, stuck, stale wanted items) -->
+<!-- TODO: Work execution problems (bead not linked, Mayor won't auto-submit, PRECONDITION_FAILED) -->
+<!-- TODO: Evidence problems (rejected format, PR closed/out-of-sync, can't find submitted) -->
+<!-- TODO: Stamping problems (missing permissions, reputation didn't update, yearbook-rule violation) -->
+<!-- TODO: Admin problems (can't post wanted item, stale review inbox, federation sync lag) -->
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
new file mode 100644
index 00000000000..74e2e62c7b6
--- /dev/null
+++ b/packages/kilo-docs/pages/code-with-ai/gastown/wasteland/workflow.md
@@ -0,0 +1,19 @@
+---
+title: "Wasteland Workflow"
+description: "End-to-end workflow for working on Wasteland items: browse, claim, work, submit evidence, and get stamped"
+noindex: true
+---
+
+# {% $markdoc.frontmatter.title %}
+
+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" /%} -->
+<!-- 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) -->
+<!-- TODO: Step 4 - Submit evidence (types, Mayor formats via wl done, DoltHub PR) -->
+<!-- TODO: Step 5 - Stamping (asynchronous, multi-dimensional) -->
+<!-- TODO: Checking your reputation -->
+<!-- TODO: Canceling/abandoning claims -->
+<!-- TODO: What can go wrong - link to Troubleshooting -->