diff --git a/.github/workflows/docs-index.yml b/.github/workflows/docs-index.yml
new file mode 100644
index 0000000..15d67a1
--- /dev/null
+++ b/.github/workflows/docs-index.yml
@@ -0,0 +1,20 @@
+name: docs-index-fresh
+on:
+  push:
+    paths: ['docs/contract-additions/**', 'docs/surfaces/README.md', 'tools/build_docs_index.py', 'docs/surfaces/data/docs-index.json']
+  pull_request:
+    paths: ['docs/contract-additions/**', 'docs/surfaces/README.md', 'tools/build_docs_index.py', 'docs/surfaces/data/docs-index.json']
+jobs:
+  fresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.11' }
+      - name: Regenerate the grounded docs index from source
+        run: python tools/build_docs_index.py
+      - name: Fail if the committed index drifted from source
+        run: |
+          if ! git diff --exit-code docs/surfaces/data/docs-index.json; then
+            echo "::error::docs-index.json is stale — run tools/build_docs_index.py and commit"; exit 1
+          fi
diff --git a/docs/surfaces/README.md b/docs/surfaces/README.md
index df51ebe..d4904f1 100644
--- a/docs/surfaces/README.md
+++ b/docs/surfaces/README.md
@@ -43,6 +43,9 @@ the real SociOS/GNOME chrome (top bar, launcher card) so they read as in-shell,
 - **`lampstand-launcher.html`** — Tier 2, *actionable*. The Spotlight replacement: natural
   language → typed intents/entities/relations (the annotation tree) → **governed actions**
   (purpose-bound, consent-gated, receipted), ranked by sherlock (IR). Not web search — typed acts.
+- **`docs-support.html`** — Tier 2, *grounded NLQA + support*. Answers only from the
+  auto-generated docs index (`tools/build_docs_index.py`), cites every source, and **abstains**
+  to support when a question isn't in the docs. A CI drift-guard keeps the index fresh from source.
 - **`model-governance.html`** — Tier 2, *regulated model registry*. Business targets (fraud/churn/
   credit/AML/propensity) with champion-vs-challenger, historic version comparison, PSI drift, and the
   DataClass classifiers per target. Model risk management as a witness surface.
diff --git a/docs/surfaces/data/docs-index.json b/docs/surfaces/data/docs-index.json
new file mode 100644
index 0000000..99a7d9b
--- /dev/null
+++ b/docs/surfaces/data/docs-index.json
@@ -0,0 +1,1157 @@
+{
+  "provenance": "live",
+  "generated_by": "tools/build_docs_index.py",
+  "doc_count": 43,
+  "docs": [
+    {
+      "path": "docs/contract-additions/2026-04-fog-contract-index.md",
+      "title": "Fog contract additions index",
+      "summary": "- **Status:** bootstrap index",
+      "headings": [
+        "New schema types",
+        "FogVault (storage + topics)",
+        "FogCompute (offers + execution evidence)",
+        "Matching examples",
+        "Why these additions exist",
+        "Relationship to existing schema families",
+        "Intended next updates"
+      ],
+      "keywords": [
+        "json",
+        "examples",
+        "additions",
+        "schema",
+        "fog",
+        "contract",
+        "execution",
+        "these",
+        "topic",
+        "index",
+        "fogvault",
+        "storage"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/2026-04-triune-exodus-contract-index.md",
+      "title": "Triune / Exodus contract additions index",
+      "summary": "- **Status:** bootstrap index",
+      "headings": [
+        "New schema types",
+        "Replay and anchoring",
+        "Quorum / review",
+        "Time-boxed bypass governance",
+        "Matching examples",
+        "Why these additions exist",
+        "Relationship to existing schema families",
+        "Intended next updates"
+      ],
+      "keywords": [
+        "json",
+        "examples",
+        "additions",
+        "contract",
+        "index",
+        "schema",
+        "these",
+        "replay",
+        "triune",
+        "exodus",
+        "anchoring",
+        "quorum"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/2026-05-agent-machine-model-carry-contracts.md",
+      "title": "Agent Machine and Model Carry Contract Additions — May 2026",
+      "summary": "Status: Draft additive contract family",
+      "headings": [
+        "Purpose",
+        "Added schemas",
+        "Boundary rules",
+        "Integration path",
+        "Validation posture",
+        "Non-goals"
+      ],
+      "keywords": [
+        "model",
+        "runtime",
+        "urn",
+        "not",
+        "agent",
+        "contract",
+        "agentplane",
+        "srcos",
+        "machine",
+        "path",
+        "sourceos",
+        "evidence"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/agent-machine-local-data-plane.md",
+      "title": "Agent Machine Local Data Plane and TopoLVM Mount Contracts",
+      "summary": "This contract addition defines the shared mount semantics for SourceOS Agent Machine local workspaces and their cluster-local TopoLVM analogue.",
+      "headings": [
+        "Why this exists",
+        "New schema types",
+        "Local mode",
+        "Cluster mode",
+        "Security invariants",
+        "Example files",
+        "Implementation owners",
+        "Current status"
+      ],
+      "keywords": [
+        "mount",
+        "agent",
+        "local",
+        "machine",
+        "topolvm",
+        "downloads",
+        "mode",
+        "workspace",
+        "host",
+        "not",
+        "json",
+        "cluster"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/browser-write-accountability.md",
+      "title": "SourceOS Browser Write Accountability v0.1",
+      "summary": "This contract specializes SourceOS Mutation and Evidence Accountability for browser write-pressure incidents.",
+      "headings": [
+        "Purpose",
+        "Decision",
+        "Required actor classes",
+        "Extension inventory states",
+        "Normative rule",
+        "Evidence-quality rule",
+        "Design consequence"
+      ],
+      "keywords": [
+        "browser",
+        "extension",
+        "profile",
+        "storage",
+        "inventory",
+        "state",
+        "evidence",
+        "class",
+        "sourceos",
+        "accountability",
+        "write-pressure",
+        "visible"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/command-bus.md",
+      "title": "CommandBus contract addition",
+      "summary": "This addition introduces `CommandBus` as the typed routing contract for keyboard-first",
+      "headings": [
+        "Why this contract exists",
+        "Intended use",
+        "Relationship to InteractionSurface"
+      ],
+      "keywords": [
+        "contract",
+        "commandbus",
+        "addition",
+        "interactionsurface",
+        "routing",
+        "typed",
+        "command",
+        "dispatch",
+        "surfaces",
+        "why",
+        "exists",
+        "intended"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/compression-evaluation-v0-placement.md",
+      "title": "CompressionEvaluation v0 placement note",
+      "summary": "This note turns the Compression Commons design assessment into an exact `sourceos-spec` landing plan.",
+      "headings": [
+        "Purpose",
+        "New top-level schema",
+        "Reused existing contracts",
+        "Proposed schema outline",
+        "Proposed REST addition",
+        "Not in v0",
+        "Semantic overlay impact",
+        "First real PR file list",
+        "Rationale"
+      ],
+      "keywords": [
+        "schema",
+        "compressionevaluation",
+        "first",
+        "top-level",
+        "semantic",
+        "existing",
+        "not",
+        "schemas",
+        "should",
+        "note",
+        "purpose",
+        "proposed"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/digital-soul-identity-reputation.md",
+      "title": "Contract additions — digital soul: identity & reputation",
+      "summary": "Adds the two-layer \"digital soul\" contract family: a private, given **identity**",
+      "headings": [
+        "Why (the three forks this closes)",
+        "Contracts",
+        "URN identifiers",
+        "Binding to the evidence fabric",
+        "Cross-plane anchoring (verified vs constitutional identity)",
+        "Enforced invariants (machine-checked)",
+        "Validate",
+        "CHANGELOG entry (ready to merge into [Unreleased] → Added)"
+      ],
+      "keywords": [
+        "identity",
+        "reputation",
+        "urn",
+        "soul",
+        "srcos",
+        "digital",
+        "inner",
+        "contract",
+        "spine",
+        "reputationdimension",
+        "ascensionreading",
+        "fabric"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/e11-consent-receipts-ux.md",
+      "title": "E11 — Consent & Receipts UX (Privacy/Security Center)",
+      "summary": "**Gap #2 of the feature-gaps-zero campaign.**",
+      "headings": [
+        "Regions (normative)",
+        "Binding to what exists (build, don't rebuild)",
+        "Done-definition",
+        "Non-goals"
+      ],
+      "keywords": [
+        "consent",
+        "purpose",
+        "e11",
+        "surface",
+        "receipt",
+        "governor",
+        "receipts",
+        "privacy",
+        "action",
+        "consent-plane",
+        "deny",
+        "region"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/e12-ota-backup.md",
+      "title": "E12 — Sovereign OTA + Snapshot/Backup (Software Update + Time Machine)",
+      "summary": "**Gap #5 of the feature-gaps-zero campaign.**",
+      "headings": [
+        "Update model — signed atomic generations",
+        "Backup model — generations to a sovereign store",
+        "Governance",
+        "Superiority over macOS",
+        "Done-definition",
+        "Non-goals"
+      ],
+      "keywords": [
+        "update",
+        "generation",
+        "restore",
+        "sovereign",
+        "backup",
+        "generations",
+        "model",
+        "signed",
+        "consent",
+        "ota",
+        "snapshot",
+        "software"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/e3-mesh-transport.md",
+      "title": "E3 — Personal Mesh Transport (Continuity / Handoff / AirDrop / AirPlay parity)",
+      "summary": "**Gap #3 of the feature-gaps-zero campaign.**",
+      "headings": [
+        "Layered model",
+        "The `MeshTransfer` envelope (normative, schema to follow)",
+        "Consent binding (build, don't rebuild)",
+        "Superiority over Continuity (why it's a superset)",
+        "Done-definition",
+        "Non-goals"
+      ],
+      "keywords": [
+        "mesh",
+        "transfer",
+        "continuity",
+        "handoff",
+        "egress",
+        "airdrop",
+        "airplay",
+        "meshtransfer",
+        "consent",
+        "fabric",
+        "not",
+        "personal"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/focus-state.md",
+      "title": "FocusState contract addition",
+      "summary": "This addition introduces `FocusState` as the typed ownership/state record for",
+      "headings": [
+        "Why this contract exists",
+        "Intended use",
+        "Relationship to the other keyboard-navigation contracts"
+      ],
+      "keywords": [
+        "focusstate",
+        "contract",
+        "addition",
+        "ownership",
+        "keyboard-navigation",
+        "typed",
+        "state",
+        "record",
+        "surface",
+        "what",
+        "why",
+        "exists"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/focus-transition.md",
+      "title": "FocusTransition contract addition",
+      "summary": "This addition introduces `FocusTransition` as the typed transition edge between",
+      "headings": [
+        "Why this contract exists",
+        "Intended use",
+        "Relationship to the other keyboard-navigation contracts"
+      ],
+      "keywords": [
+        "focustransition",
+        "transition",
+        "contract",
+        "addition",
+        "ownership",
+        "how",
+        "why",
+        "exists",
+        "intended",
+        "use",
+        "relationship",
+        "other"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/immutable-node-profiles.md",
+      "title": "Immutable Node Profile Contracts",
+      "summary": "This contract addition defines the first SourceOS machine-readable surface for immutable Linux node and agent-runtime substrate profiles.",
+      "headings": [
+        "Why this exists",
+        "Added schemas",
+        "Added examples",
+        "Validation",
+        "Downstream implementation map",
+        "Non-goals"
+      ],
+      "keywords": [
+        "node",
+        "substrate",
+        "json",
+        "immutable",
+        "schemas",
+        "examples",
+        "sourceos",
+        "evidence",
+        "posture",
+        "desktop",
+        "state",
+        "added"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/inference-gateway-intersection.md",
+      "title": "InferenceGateway — the cloud ∩ local intersection (model serving)",
+      "summary": "**Campaign gap #8, done the right way: start at the intersection, then fan out.**",
+      "headings": [
+        "The shared seam",
+        "Intersection-first, then fan out",
+        "Every model + capability gets a surface across the estate",
+        "Positioning (governs-people vs governs-agents)",
+        "Done-definition",
+        "The governed model plane — beyond foundation models"
+      ],
+      "keywords": [
+        "model",
+        "cloud",
+        "local",
+        "out",
+        "plane",
+        "inferencegateway",
+        "intersection",
+        "shared",
+        "fan",
+        "both",
+        "then",
+        "capability"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/integrated-agent-native-stack.md",
+      "title": "SourceOS Integrated Agent-Native Stack v0.1",
+      "summary": "macOS wins because it is **one integrated system**, not a pile of apps. SourceOS",
+      "headings": [
+        "Purpose",
+        "Decision — one integrated, agent-native, owned stack",
+        "Per-app feature-modification matrix (agent-native integration)",
+        "Intelligence layer — Siri + Apple Intelligence, native and *extended*",
+        "Accessibility — first-class defaults (opt-in for agent modes)",
+        "Semantic grounding & ontology bindings",
+        "Security seams (the enforcement boundaries)",
+        "Purple-team tests (mandatory, must fire)",
+        "Implementation boundary"
+      ],
+      "keywords": [
+        "seam",
+        "agent",
+        "not",
+        "stack",
+        "accessibility",
+        "every",
+        "each",
+        "agent-native",
+        "intelligence",
+        "app",
+        "receipted",
+        "action"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/interaction-surface.md",
+      "title": "InteractionSurface contract addition",
+      "summary": "This addition introduces `InteractionSurface` as the first canonical contract for",
+      "headings": [
+        "Why this contract exists",
+        "Intended use",
+        "Current scope"
+      ],
+      "keywords": [
+        "contract",
+        "interactionsurface",
+        "addition",
+        "scope",
+        "first",
+        "canonical",
+        "policy",
+        "may",
+        "why",
+        "exists",
+        "intended",
+        "use"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/isolation-spaces-and-taints.md",
+      "title": "SourceOS Isolation Spaces and Taints v0.1",
+      "summary": "This contract makes the isolation **spaces** used by the consent-plane",
+      "headings": [
+        "Purpose",
+        "Decision",
+        "Admission (taint ⇄ toleration)",
+        "Accountability",
+        "Implementation boundary",
+        "Cross-references"
+      ],
+      "keywords": [
+        "space",
+        "toleration",
+        "consent-plane",
+        "isolation",
+        "spaces",
+        "ring",
+        "taint",
+        "surface",
+        "sourceos",
+        "docs",
+        "adr",
+        "noentry"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/keymap-profile.md",
+      "title": "KeymapProfile contract addition",
+      "summary": "`KeymapProfile` is the typed mapping profile for keyboard-first interaction in SourceOS and SociOS.",
+      "headings": [],
+      "keywords": [
+        "keymapprofile",
+        "profile",
+        "contract",
+        "addition",
+        "typed",
+        "mapping",
+        "keyboard-first",
+        "interaction",
+        "sourceos",
+        "socios",
+        "records",
+        "platform"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/macos-replacement-matrix.md",
+      "title": "macOS → SourceOS/SociOS replacement & enhancement matrix",
+      "summary": "**The census.** The integrated-agent-native-stack contract",
+      "headings": [
+        "Status legend",
+        "Core apps & shell",
+        "System & intelligence subsystems",
+        "Hardware-gap register — where Apple silicon wins, honestly",
+        "How to use this matrix",
+        "Long tail (audit-flagged as unspecified — now enumerated, mostly `gap`)"
+      ],
+      "keywords": [
+        "partial",
+        "gap",
+        "agent",
+        "macos",
+        "owned",
+        "not",
+        "source-os",
+        "mesh",
+        "sourceos",
+        "replacement",
+        "built",
+        "sovereign"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/mutation-evidence-accountability.md",
+      "title": "SourceOS Mutation and Evidence Accountability v0.1",
+      "summary": "This contract defines the minimum evidence model for mutation, resource pressure, policy denials, evidence routing, media/codec work, temporary artifacts, service lifecycle, and compromise assessment in SourceOS.",
+      "headings": [
+        "Purpose",
+        "Normative principles",
+        "Required event families",
+        "Minimum event envelope",
+        "Required evidence-quality states",
+        "Required compromise-assessment states",
+        "Required artifact classes",
+        "Required operator queries",
+        "Initial repo placement"
+      ],
+      "keywords": [
+        "evidence",
+        "sourceos",
+        "required",
+        "must",
+        "compromise",
+        "explain",
+        "event",
+        "policy",
+        "routing",
+        "media",
+        "degraded",
+        "mutation"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/network-assistant-model-doors.md",
+      "title": "Network, Mesh, BYOM, and Native Assistant Door contracts",
+      "summary": "This contract addition defines the SourceOS boundary for enterprise networking, user firewalls, service mesh integrations, bring-your-own-model endpoints, and native assistant bridges such as Apple App Intents/Siri/Shortcuts.",
+      "headings": [
+        "Why this exists",
+        "New schema types",
+        "Profile separation",
+        "Firewall and mesh posture",
+        "BYOM posture",
+        "Native assistant posture",
+        "Examples",
+        "Implementation owners",
+        "Non-goals"
+      ],
+      "keywords": [
+        "profile",
+        "firewall",
+        "enterprise",
+        "mesh",
+        "policy",
+        "network",
+        "native",
+        "assistant",
+        "user",
+        "json",
+        "byom",
+        "app"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/onboarding-control-plane.md",
+      "title": "Onboarding Control-Plane Contract Additions",
+      "summary": "This note documents the additive SourceOS/SociOS onboarding and agent-workbench control-plane contract family introduced by ADR-0012.",
+      "headings": [
+        "Contract family",
+        "Example payloads",
+        "Validation",
+        "Reuse boundaries",
+        "Follow-on work"
+      ],
+      "keywords": [
+        "json",
+        "onboarding",
+        "urn",
+        "contract",
+        "family",
+        "schemas",
+        "srcos",
+        "examples",
+        "sourceos",
+        "workspace",
+        "remains",
+        "control-plane"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/ops-history-catalog.md",
+      "title": "OpsHistory Contract Catalog",
+      "summary": "Status: additive contract catalog for OpsHistory, BearHistory, local-first service manifests, operational receipts, context-pack references, and redaction tombstones.",
+      "headings": [
+        "Schema additions",
+        "Example additions",
+        "Validation",
+        "Consumer repos",
+        "Contract discipline"
+      ],
+      "keywords": [
+        "json",
+        "urn",
+        "srcos",
+        "contract",
+        "opshistory",
+        "catalog",
+        "schema",
+        "additions",
+        "context-pack",
+        "socioprophet",
+        "local-first",
+        "service"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/ops-history.md",
+      "title": "OpsHistory and Local-First Service Contracts",
+      "summary": "Initial additive contract seed for SourceOS/SociOS spec issue #84.",
+      "headings": [
+        "Status",
+        "Purpose",
+        "Contract family",
+        "Downstream consumers",
+        "Non-negotiables",
+        "Linux service mapping",
+        "Initial service endpoints",
+        "Implementation posture"
+      ],
+      "keywords": [
+        "sourceos",
+        "service",
+        "policy",
+        "redaction",
+        "org",
+        "opshistory",
+        "contract",
+        "owns",
+        "local",
+        "export",
+        "initial",
+        "posture"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/os-build-cybernetic-boundary.md",
+      "title": "OS Build / Cybernetic Boundary — additive contract note",
+      "summary": "Merged into `main` via PR #26.",
+      "headings": [
+        "Status",
+        "Purpose",
+        "Intent",
+        "Where to look",
+        "What this note does not do",
+        "Why this note exists"
+      ],
+      "keywords": [
+        "note",
+        "json",
+        "build",
+        "cybernetic",
+        "additive",
+        "not",
+        "osimage",
+        "nodebinding",
+        "cyberneticassignment",
+        "schemas",
+        "examples",
+        "does"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/radio-spatial-derived-context.md",
+      "title": "Radio-Spatial, Learned Location, and Home Context Boundaries",
+      "summary": "Status: additive security-contract placement note.",
+      "headings": [
+        "Summary",
+        "Security rule",
+        "Claim discipline",
+        "Required receipt family",
+        "Required user-visible controls",
+        "Integration points",
+        "Acceptance tests",
+        "Non-goals"
+      ],
+      "keywords": [
+        "context",
+        "receipts",
+        "radio-spatial",
+        "location",
+        "home",
+        "derived",
+        "routine",
+        "model",
+        "wi-fi",
+        "state",
+        "protected",
+        "required"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/reasoning-run-contracts.md",
+      "title": "Reasoning Run Contract Additions",
+      "summary": "This tranche adds the first canonical SourceOS/SociOS contracts for governed recursive reasoning runs.",
+      "headings": [
+        "Purpose",
+        "Added schemas",
+        "Boundary",
+        "Safe trace rule",
+        "Open item"
+      ],
+      "keywords": [
+        "reasoning",
+        "owns",
+        "run",
+        "urn",
+        "schemas",
+        "safe",
+        "tranche",
+        "srcos",
+        "socioprophet",
+        "canonical",
+        "contracts",
+        "superconscious"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/runtime-causality-contracts-v0.md",
+      "title": "Runtime Causality Contracts v0",
+      "summary": "This additive contract slice introduces runtime-causality records derived from ordered diagnostic evidence. The goal is to collapse opaque operating-system log storms into typed, bounded, user-explainable evidence objects.",
+      "headings": [
+        "Added schemas",
+        "Added examples",
+        "Design intent",
+        "Observed failure classes covered",
+        "Downstream consumers",
+        "Implementation notes",
+        "Follow-up work"
+      ],
+      "keywords": [
+        "json",
+        "schemas",
+        "examples",
+        "runtime",
+        "state",
+        "urn",
+        "srcos",
+        "evidence",
+        "broker",
+        "session",
+        "records",
+        "browser"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/shared-content-build-release-family-v0.md",
+      "title": "Shared Content / Build / Release Family v0",
+      "summary": "This additive contract family introduces shared object shapes that can be reused across:",
+      "headings": [
+        "Design intent",
+        "Object family",
+        "Boundaries",
+        "Follow-on"
+      ],
+      "keywords": [
+        "family",
+        "build",
+        "object",
+        "shared",
+        "content",
+        "release",
+        "additive",
+        "can",
+        "evidence",
+        "catalog",
+        "design",
+        "intent"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/sourceos-interaction-catalog.md",
+      "title": "SourceOS Interaction Substrate Catalog",
+      "summary": "Status: Informational",
+      "headings": [
+        "Purpose",
+        "Contract objects",
+        "Generated type consumption",
+        "Required downstream bindings",
+        "Payload posture",
+        "Operational flow",
+        "Completion status"
+      ],
+      "keywords": [
+        "generated",
+        "sourceos",
+        "interaction",
+        "noetica",
+        "agentterm",
+        "python",
+        "socioprophet",
+        "schema",
+        "sourceosinteractionevent",
+        "typescript",
+        "downstream",
+        "artifacts"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/sourceos-interaction-implementation-ledger.md",
+      "title": "SourceOS Interaction Substrate Implementation Ledger",
+      "summary": "Status: implementation ledger",
+      "headings": [
+        "Purpose",
+        "Canonical contract estate",
+        "Downstream implementation estate",
+        "Validation lanes",
+        "Authority boundaries",
+        "Non-goals of the completed tranche",
+        "Remaining non-blocking future work"
+      ],
+      "keywords": [
+        "sourceos",
+        "interaction",
+        "contract",
+        "noetica",
+        "sourceos-linux",
+        "reference-flow",
+        "socioprophet",
+        "adds",
+        "substrate",
+        "implementation",
+        "downstream",
+        "superconscious"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/sourceos-interaction-noetica-placement-addendum.md",
+      "title": "SourceOS Interaction Noetica Placement Addendum",
+      "summary": "Status: placement addendum",
+      "headings": [
+        "Purpose",
+        "Placement rule",
+        "Transitional fallback",
+        "Fixture relationship",
+        "Non-goals"
+      ],
+      "keywords": [
+        "noetica",
+        "interaction",
+        "placement",
+        "addendum",
+        "transport",
+        "boundary",
+        "authority",
+        "fallback",
+        "shell",
+        "owns",
+        "sourceos",
+        "status"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/sourceos-interaction-reference-flow.md",
+      "title": "SourceOS Interaction Reference Flow v0.1",
+      "summary": "Status: Informational reference packet",
+      "headings": [
+        "Purpose",
+        "Authority map",
+        "Pinned implementation commits",
+        "Payload posture",
+        "Validation"
+      ],
+      "keywords": [
+        "reference",
+        "authority",
+        "interaction",
+        "socioprophet",
+        "packet",
+        "artifacts",
+        "flow",
+        "implementation",
+        "commits",
+        "validation",
+        "evidence",
+        "sourceos-linux"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/sourceos-interaction-runtime-bridge-ledger.md",
+      "title": "SourceOS Interaction Runtime Bridge Ledger",
+      "summary": "Status: implementation ledger",
+      "headings": [
+        "Purpose",
+        "Completed bridge tranches",
+        "Current implementation shape",
+        "Validation lanes",
+        "Boundary posture",
+        "Follow-up issue routing",
+        "Remaining work"
+      ],
+      "keywords": [
+        "noetica",
+        "bridge",
+        "added",
+        "runtime",
+        "socioprophet",
+        "artifact",
+        "export",
+        "sourceos",
+        "import",
+        "validation",
+        "agentterm",
+        "interaction"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/sourceos-interaction-substrate.md",
+      "title": "SourceOS Interaction Substrate v0.1",
+      "summary": "Status: Proposed",
+      "headings": [
+        "Purpose",
+        "Relationship to OpsHistory",
+        "Normative boundaries",
+        "Required producers",
+        "Minimum event content",
+        "Surface obligations",
+        "Non-goals",
+        "Acceptance criteria"
+      ],
+      "keywords": [
+        "surface",
+        "memory",
+        "event",
+        "policy",
+        "not",
+        "noetica",
+        "agentterm",
+        "evidence",
+        "matrix",
+        "owns",
+        "task",
+        "replay"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/sourceos-interaction-top-level-index.md",
+      "title": "SourceOS Interaction Substrate Top-Level Index",
+      "summary": "Status: informational index",
+      "headings": [],
+      "keywords": [
+        "interaction",
+        "sourceos",
+        "generated",
+        "python",
+        "reference",
+        "substrate",
+        "index",
+        "noetica",
+        "chat",
+        "task-boundary",
+        "evidence",
+        "json"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/sovereign-shell-assembly.md",
+      "title": "Sovereign Shell Assembly — how the OS is built from the parts",
+      "summary": "The build index for the SociOS/SourceOS agentic shell: every component the",
+      "headings": [
+        "Components (built this campaign)",
+        "Vendored dependencies (consumed, not forked)",
+        "Build order (bottom-up)",
+        "What remains to a bootable image"
+      ],
+      "keywords": [
+        "build",
+        "source-os",
+        "surfaces",
+        "shell",
+        "vendored",
+        "hellgraph",
+        "built",
+        "not",
+        "image",
+        "sourceos-spec",
+        "replacement",
+        "sourceos-shell"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/systema-capability-radius.md",
+      "title": "Systema: Capability Radius Mapping to SourceOS Typed Contracts",
+      "summary": "Systema's `capability_radius_profile.yaml` models the bounded scope within which an agent or component may exercise capabilities: a spatial/contextual radius beyond which capability requests are automatically denied, regardless of individual capability grants.",
+      "headings": [
+        "What Systema defines",
+        "Existing SourceOS/SociOS coverage",
+        "Gap: radius boundary document",
+        "Mapping rules",
+        "No new schemas required"
+      ],
+      "keywords": [
+        "radius",
+        "systema",
+        "capability",
+        "sourceos",
+        "which",
+        "agentcapabilitylease",
+        "mapping",
+        "new",
+        "profile",
+        "scope",
+        "agent",
+        "capabilitygrantstate"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/systema-membrane-boundary.md",
+      "title": "Systema: Membrane Boundary Mapping to SourceOS Typed Contracts",
+      "summary": "Systema's `membrane_boundary_profile.yaml` defines isolation boundaries between system zones: what may cross a membrane (data, events, capability grants), under what conditions, and what evidence is required to authorize a crossing.",
+      "headings": [
+        "What Systema defines",
+        "Existing SourceOS/SociOS coverage",
+        "Gap: membrane crossing event record",
+        "Mapping rules",
+        "No new schemas required"
+      ],
+      "keywords": [
+        "membrane",
+        "systema",
+        "crossing",
+        "what",
+        "boundary",
+        "capabilitygrantstate",
+        "sourceos",
+        "mapping",
+        "defines",
+        "event",
+        "required",
+        "capability"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/systema-projection-loss.md",
+      "title": "Systema: Projection Loss Mapping to SourceOS Typed Contracts",
+      "summary": "Systema's `projection_loss_profile.yaml` models the degradation between a source truth and its projected representation: information loss during transformation, summarization, embedding, or model inference. A `projectionLoss` score of 0.0 is lossless; 1.0 is total loss.",
+      "headings": [
+        "What Systema defines",
+        "Existing SourceOS/SociOS coverage",
+        "Gap: projection-loss scalar on emitted artifacts",
+        "Mapping rules",
+        "No new schemas required"
+      ],
+      "keywords": [
+        "systema",
+        "loss",
+        "projection",
+        "sourceos",
+        "projectionloss",
+        "mapping",
+        "projection-loss",
+        "schemas",
+        "score",
+        "reasoningassay",
+        "localreasoningfailure",
+        "socios"
+      ]
+    },
+    {
+      "path": "docs/contract-additions/systema-source-confidence.md",
+      "title": "Systema: Source Confidence Mapping to SourceOS Typed Contracts",
+      "summary": "Systema's `source_confidence_profile.yaml` models the trustworthiness of a data source across axes: recency, provenance, verifiability, and authority. It produces a scalar confidence score and a named confidence tier (`high`, `medium`, `low`, `unverified`).",
+      "headings": [
+        "What Systema defines",
+        "Existing SourceOS/SociOS coverage",
+        "Gap: runtime source-confidence metadata on local objects",
+        "Mapping rules",
+        "No new schemas required"
+      ],
+      "keywords": [
+        "confidence",
+        "systema",
+        "source",
+        "sourceos",
+        "schemas",
+        "authority",
+        "mapping",
+        "source-confidence",
+        "axes",
+        "tier",
+        "existing",
+        "socios"
+      ]
+    },
+    {
+      "path": "docs/surfaces/README.md",
+      "title": "Surfaces — the diagram is a witness, not an illustration",
+      "summary": "Canonical visual surfaces for the estate. **The rule:** a diagram of a governed,",
+      "headings": [
+        "Live-feed wiring",
+        "Three tiers",
+        "Style is validated against source",
+        "In this directory",
+        "Provenance note",
+        "Backlog (to finish Tier 1)"
+      ],
+      "keywords": [
+        "tier",
+        "html",
+        "surface",
+        "surfaces",
+        "not",
+        "source",
+        "canonical",
+        "every",
+        "diagram",
+        "live",
+        "state",
+        "instrument"
+      ]
+    }
+  ]
+}
diff --git a/docs/surfaces/docs-support.html b/docs/surfaces/docs-support.html
new file mode 100644
index 0000000..ebb8b96
--- /dev/null
+++ b/docs/surfaces/docs-support.html
@@ -0,0 +1,142 @@
+<title>SociOS — Docs &amp; Support (grounded NLQA)</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+:root{
+  --bg:#0a0e18;--panel:#111726;--panel2:#161e30;--line:#212b42;--line2:#2c3854;
+  --text:#e8edf7;--muted:#8b96b0;--faint:#586179;--cyan:#4fd0e0;--cyan2:#7aa2ff;
+  --ground:#43c68a;--partial:#e0a83a;--abstain:#e5594f;
+  --sans:"Cantarell","Noto Sans",system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
+  --mono:ui-monospace,"SF Mono",Menlo,Consolas,monospace;
+}
+@media (prefers-color-scheme:light){:root{--bg:#eceff5;--panel:#fff;--panel2:#f5f7fb;--line:#dde3ef;--line2:#c8d1e2;--text:#141b2c;--muted:#54607a;--faint:#8792ab;--cyan:#1787a0;--cyan2:#3762d6;--ground:#1f9e63;--partial:#a6791b;--abstain:#c23a31}}
+:root[data-theme="light"]{--bg:#eceff5;--panel:#fff;--panel2:#f5f7fb;--line:#dde3ef;--line2:#c8d1e2;--text:#141b2c;--muted:#54607a;--faint:#8792ab;--cyan:#1787a0;--cyan2:#3762d6;--ground:#1f9e63;--partial:#a6791b;--abstain:#c23a31}
+:root[data-theme="dark"]{--bg:#0a0e18;--panel:#111726;--panel2:#161e30;--line:#212b42;--line2:#2c3854;--text:#e8edf7;--muted:#8b96b0;--faint:#586179;--cyan:#4fd0e0;--cyan2:#7aa2ff;--ground:#43c68a;--partial:#e0a83a;--abstain:#e5594f}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font-family:var(--sans);font-size:13.5px;line-height:1.55;-webkit-font-smoothing:antialiased}
+.mono{font-family:var(--mono)}
+.wrap{max-width:820px;margin:0 auto;padding:24px 18px 60px}
+header.top{display:flex;align-items:baseline;gap:12px;flex-wrap:wrap;border-bottom:1px solid var(--line);padding-bottom:14px;margin-bottom:4px}
+header.top h1{font-size:20px;margin:0;font-weight:700;letter-spacing:.3px}
+header.top .id{font-family:var(--mono);color:var(--cyan);font-size:12.5px}
+.prov{font-family:var(--mono);font-size:9.5px;font-weight:700;letter-spacing:.5px;padding:2px 7px;border-radius:5px;border:1px solid var(--line2);color:var(--muted)}
+.prov.sample{color:var(--partial);border-color:color-mix(in srgb,var(--partial) 42%,transparent);background:color-mix(in srgb,var(--partial) 12%,transparent)}
+.prov.live{color:var(--ground);border-color:color-mix(in srgb,var(--ground) 42%,transparent);background:color-mix(in srgb,var(--ground) 12%,transparent)}
+.tgl{margin-left:auto;background:none;border:1px solid var(--line2);border-radius:8px;width:32px;height:32px;color:var(--muted);cursor:pointer}
+.sub{color:var(--muted);margin:14px 0 16px}
+.qbar{display:flex;align-items:center;gap:11px;background:var(--panel);border:1px solid var(--line2);border-radius:12px;padding:13px 15px;margin-bottom:12px}
+.qbar .mag{color:var(--faint);font-size:17px}
+.qbar input{flex:1;border:none;background:none;outline:none;font:inherit;font-size:16px;color:var(--text)}
+.exs{display:flex;flex-wrap:wrap;gap:7px;margin-bottom:18px}
+.ex{font-size:12px;border:1px solid var(--line2);background:var(--panel);border-radius:16px;padding:5px 12px;cursor:pointer;color:var(--muted)}
+.ex:hover{border-color:var(--cyan);color:var(--cyan)}
+.card{background:var(--panel);border:1px solid var(--line);border-radius:14px;overflow:hidden;margin-bottom:14px}
+.card h2{font-size:10.5px;letter-spacing:.9px;text-transform:uppercase;color:var(--faint);font-weight:700;margin:0;padding:12px 16px;border-bottom:1px solid var(--line);display:flex;align-items:center;gap:8px}
+.badge{font-family:var(--mono);font-size:9.5px;font-weight:700;letter-spacing:.4px;padding:2px 8px;border-radius:5px}
+.badge.ground{background:color-mix(in srgb,var(--ground) 16%,transparent);color:var(--ground)}
+.badge.partial{background:color-mix(in srgb,var(--partial) 16%,transparent);color:var(--partial)}
+.badge.abstain{background:color-mix(in srgb,var(--abstain) 16%,transparent);color:var(--abstain)}
+.ans{padding:15px 16px;font-size:14px;line-height:1.65}
+.ans sup{font-family:var(--mono);font-size:9.5px;color:var(--cyan);font-weight:700;cursor:pointer;padding:0 1px}
+.src{display:block;padding:11px 16px;border-top:1px solid var(--line);text-decoration:none;color:inherit}
+.src:hover{background:var(--panel2)}
+.src .st{font-weight:600;font-size:12.5px;display:flex;gap:8px;align-items:baseline}
+.src .st .cn{font-family:var(--mono);font-size:9.5px;color:var(--cyan)}
+.src .sp{font-family:var(--mono);font-size:10.5px;color:var(--faint);margin-top:1px}
+.src .sn{color:var(--muted);font-size:12px;margin-top:4px}
+.abstain-box{padding:15px 16px}
+.abstain-box .big{font-size:14px;font-weight:600;color:var(--abstain);margin:0 0 8px}
+.abstain-box p{color:var(--muted);margin:0 0 12px;font-size:13px}
+.ticket{display:inline-flex;align-items:center;gap:8px;background:var(--cyan);color:#08152e;border:none;border-radius:9px;padding:8px 15px;font:inherit;font-weight:650;font-size:13px;cursor:pointer}
+.chips{display:flex;flex-wrap:wrap;gap:6px;margin-top:12px}
+.chips .c{font-size:11px;font-family:var(--mono);color:var(--muted);border:1px solid var(--line2);border-radius:14px;padding:3px 10px;cursor:pointer}
+.route{display:flex;align-items:center;gap:8px;padding:11px 16px;font-size:11px;color:var(--faint);font-family:var(--mono);border-top:1px solid var(--line);background:var(--panel2)}
+.route b{color:var(--muted)}
+.foot{margin-top:18px;color:var(--faint);font-size:11.5px;text-align:center;line-height:1.7}
+.toast{position:fixed;left:50%;bottom:24px;transform:translateX(-50%);background:var(--text);color:var(--bg);padding:11px 16px;border-radius:10px;font-size:13px;opacity:0;pointer-events:none;transition:.2s}
+.toast.show{opacity:1;transform:translateX(-50%) translateY(-4px)}
+</style>
+
+<div class="wrap">
+  <header class="top"><h1>Docs &amp; Support</h1><span class="id">grounded NLQA</span>
+    <span class="prov" id="prov"></span>
+    <button class="tgl" id="tgl" aria-label="Toggle theme">◑</button></header>
+  <p class="sub">Ask in plain language. Answers come <b>only from the auto-generated documentation</b> — every claim is cited back to a source doc, and if the answer isn't in the docs the assistant <b>abstains</b> and opens support rather than guessing. Grounded, not generative-from-nowhere.</p>
+
+  <div class="qbar"><span class="mag">⌕</span>
+    <input id="q" placeholder="e.g. how does consent work? what replaces Time Machine?" spellcheck="false" value="how does consent work?"></div>
+  <div class="exs" id="exs"></div>
+
+  <div id="out"></div>
+
+  <p class="foot">Docs auto-generated from source specs by <span class="mono">build_docs_index.py</span> (a doc is a witness of source). Retrieval: <span class="mono">lampstand → sherlock (IR) → InferenceGateway</span> over the grounded corpus; every answer is receipted, every abstention is honest.</p>
+</div>
+<div class="toast" id="toast"></div>
+
+<script>
+let __prov='sample';
+async function loadFeed(name){try{const base=(window.SURFACE_FEED_URL||'./data/');const r=await fetch(base+name+'.json',{cache:'no-store'});if(!r.ok)throw 0;const j=await r.json();__prov=j.provenance||'live';return j;}catch(e){__prov='sample';return null;}}
+function setProv(){const b=document.getElementById('prov');if(b){b.textContent=(__prov==='live'?'LIVE · autogen':'SAMPLE DATA');b.className='prov '+(__prov==='live'?'live':'sample');}}
+
+// embedded fallback = a real subset of the generated docs-index (docs/surfaces/data/docs-index.json)
+let DOCS=[
+ {path:"docs/contract-additions/e11-consent-receipts-ux.md",title:"E11 — Consent & Receipts UX (Privacy/Security Center)",
+  summary:"macOS surfaces privacy as a per-app checkbox; E11 makes the consent-plane legible: which purpose each app may act under, plus a hash-sealed receipt of every action.",
+  headings:["Regions","Binding to what exists","Done-definition"],keywords:["consent","purpose","receipts","privacy","surface","warrant","gdpr","governed"]},
+ {path:"docs/contract-additions/e12-ota-backup.md",title:"E12 — Sovereign OTA + Snapshot/Backup (Software Update + Time Machine)",
+  summary:"Replaces Software Update and Time Machine with signed, reproducible, rollbackable generations. No vendor cloud; every update and restore is consent-gated and receipted.",
+  headings:["Update model","Backup model","Superiority over macOS"],keywords:["ota","backup","time","machine","update","generation","rollback","snapshot","restore","signed"]},
+ {path:"docs/contract-additions/e3-mesh-transport.md",title:"E3 — Personal Mesh Transport (Continuity / Handoff / AirDrop / AirPlay parity)",
+  summary:"A sovereign personal mesh: your devices form one fabric with no vendor cloud, and every cross-device transfer is an egress-purpose act, consent-gated and receipted.",
+  headings:["Layered model","MeshTransfer envelope","Superiority over Continuity"],keywords:["mesh","transport","handoff","airdrop","airplay","continuity","device","transfer","egress","wireguard"]},
+ {path:"docs/contract-additions/inference-gateway-intersection.md",title:"InferenceGateway — the cloud ∩ local intersection (model serving)",
+  summary:"Both the cloud plane and the local plane serve inference through one InferenceGateway contract, emitting the GatewayCallAudit receipt on every call, consent-gated fail-closed.",
+  headings:["The shared seam","Intersection-first, then fan out","The governed model plane"],keywords:["inference","model","serving","gateway","cloud","local","intersection","llm","champion","challenger","fraud","churn","classifiers","leaderboard","sovereignty"]},
+ {path:"docs/contract-additions/macos-replacement-matrix.md",title:"macOS → SourceOS/SociOS replacement & enhancement matrix",
+  summary:"The census: every stock-macOS app and subsystem, its SourceOS replacement, the enhancement that makes it a superset, and an honest status, plus a hardware-gap register.",
+  headings:["Core apps & shell","Hardware-gap register","Long tail"],keywords:["macos","replacement","census","finder","safari","spotlight","lampstand","hardware","asahi","superset"]},
+ {path:"docs/surfaces/README.md",title:"Surfaces — the diagram is a witness, not an illustration",
+  summary:"Canonical visual surfaces: a diagram of a governed, provenance-bearing system must be truthful, legible, version-controlled, and rendered from the source of truth.",
+  headings:["Three tiers","Live-feed wiring","Style is validated against source"],keywords:["surfaces","diagram","witness","tokens","theme","live","feed","b11","turn-witness","leaderboard"]},
+];
+const STOP=new Set("the a an and or of to in for is are on with by as it be this that from at into how does do what when where which why can i my our we you your".split(" "));
+function toks(s){return (s.toLowerCase().match(/[a-z][a-z0-9-]{1,}/g)||[]).filter(w=>!STOP.has(w));}
+function score(doc,qt){let s=0;const t=doc.title.toLowerCase(),h=doc.headings.join(" ").toLowerCase(),k=new Set(doc.keywords),sm=doc.summary.toLowerCase();
+  qt.forEach(w=>{if(t.includes(w))s+=3;if(h.includes(w))s+=1.6;if(k.has(w))s+=1.4;if(sm.includes(w))s+=0.6;});return s;}
+const el=id=>document.getElementById(id);
+function answer(q){
+  const qt=[...new Set(toks(q))];
+  const ranked=DOCS.map(d=>({d,s:score(d,qt)})).filter(x=>x.s>0).sort((a,b)=>b.s-a.s);
+  const top=ranked.slice(0,3);
+  const best=top[0]?top[0].s:0;
+  // grounding decision — fail-closed: no real match ⇒ abstain
+  const level = best>=3.0?"ground":best>=1.4?"partial":"abstain";
+  if(level==="abstain"){
+    el('out').innerHTML=`<div class="card"><h2>Answer <span class="badge abstain">ABSTAINED</span></h2>
+      <div class="abstain-box"><p class="big">Not grounded in the documentation.</p>
+      <p>I won't answer what I can't cite. This question isn't covered by the current specs — rather than guess, I'll route it to support and log the gap so a doc can be written.</p>
+      <button class="ticket" onclick="ticket()">◈ Open support ticket</button>
+      <div class="chips">${DOCS.slice(0,5).map(d=>`<span class="c" onclick="ask('${d.title.split('—')[0].trim().replace(/'/g,'')}')">${d.title.split('—')[0].trim()}</span>`).join('')}</div>
+      </div><div class="route"><b>route</b> lampstand → sherlock (IR) → <b>abstain</b> → support · gap logged</div></div>`;
+    return;
+  }
+  const badge = level==="ground"?'<span class="badge ground">GROUNDED</span>':'<span class="badge partial">PARTIAL · verify</span>';
+  const a=top[0].d, b=top[1]&&top[1].s>=1.4?top[1].d:null;
+  let ans=`${a.summary} <sup>[1]</sup>`;
+  const relH=a.headings.find(h=>qt.some(w=>h.toLowerCase().includes(w)));
+  if(relH) ans+=` See <b>${relH}</b> in the source doc. <sup>[1]</sup>`;
+  if(b) ans+=` Related: ${b.title.split('—')[0].trim()}. <sup>[2]</sup>`;
+  const cites=[a,...(b?[b]:[])];
+  el('out').innerHTML=`<div class="card"><h2>Answer ${badge}</h2>
+    <div class="ans">${ans}</div>
+    ${cites.map((d,i)=>`<a class="src" href="https://github.com/SourceOS-Linux/sourceos-spec/blob/main/${d.path}" target="_blank" rel="noopener">
+      <div class="st"><span class="cn">[${i+1}]</span>${d.title}</div><div class="sp">${d.path}</div><div class="sn">${d.summary}</div></a>`).join('')}
+    <div class="route"><b>route</b> lampstand → sherlock (IR) → InferenceGateway → grounded · <span style="margin-left:auto">sealed sha256 · receipted</span></div></div>`;
+}
+function ask(q){el('q').value=q;answer(q);}
+function ticket(){const t=el('toast');t.textContent="Support ticket opened + documentation gap logged";t.classList.add('show');clearTimeout(window._t);window._t=setTimeout(()=>t.classList.remove('show'),2600);}
+el('q').addEventListener('keydown',e=>{if(e.key==='Enter')answer(el('q').value);});
+el('q').addEventListener('input',()=>{if(el('q').value.length>4)answer(el('q').value);});
+el('tgl').onclick=()=>{const r=document.documentElement;const c=r.getAttribute('data-theme')||(matchMedia('(prefers-color-scheme:dark)').matches?'dark':'light');r.setAttribute('data-theme',c==='dark'?'light':'dark');};
+(async()=>{const f=await loadFeed('docs-index');if(f&&Array.isArray(f.docs)&&f.docs.length)DOCS=f.docs;setProv();
+  el('exs').innerHTML=['how does consent work?','what replaces Time Machine?','how do models run locally?','what is champion challenger?','how is the shell built?','what is the capital of France?'].map(q=>`<button class="ex" onclick="ask('${q}')">${q}</button>`).join('');
+  answer(el('q').value);})();
+</script>
diff --git a/tools/build_docs_index.py b/tools/build_docs_index.py
new file mode 100644
index 0000000..f3b0672
--- /dev/null
+++ b/tools/build_docs_index.py
@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Auto-generate the grounded documentation index from source specs.
+
+Scans docs/contract-additions/*.md (+ the surfaces README) and emits a grounded
+corpus: {path, title, summary, headings, keywords} per doc. The NLQA/support surface
+answers ONLY from this index and cites back to it — a doc is a witness of source, and
+an answer is a witness of the docs. Regenerate whenever the specs change; the surface's
+LIVE/SAMPLE badge reflects whether it is reading a freshly generated index.
+"""
+from __future__ import annotations
+import json, re, sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+STOP = set("the a an and or of to in for is are on with by as it be this that from at into your you our we".split())
+
+
+def _keywords(text, k=12):
+    words = re.findall(r"[A-Za-z][A-Za-z0-9-]{2,}", text.lower())
+    freq = {}
+    for w in words:
+        if w not in STOP:
+            freq[w] = freq.get(w, 0) + 1
+    return [w for w, _ in sorted(freq.items(), key=lambda x: -x[1])[:k]]
+
+
+def index_doc(p: Path) -> dict:
+    text = p.read_text(encoding="utf-8", errors="replace")
+    lines = text.splitlines()
+    title = next((l.lstrip("# ").strip() for l in lines if l.startswith("# ")), p.stem)
+    headings = [l.lstrip("# ").strip() for l in lines if re.match(r"^#{2,3} ", l)]
+    # first non-heading, non-blank paragraph as summary
+    summary = ""
+    for l in lines:
+        s = l.strip()
+        if s and not s.startswith("#") and not s.startswith("|") and not s.startswith(">"):
+            summary = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", s)  # strip md links
+            break
+    return {
+        "path": str(p.relative_to(ROOT)),
+        "title": title,
+        "summary": summary[:280],
+        "headings": headings[:12],
+        "keywords": _keywords(title + " " + " ".join(headings) + " " + summary + " " + text),
+    }
+
+
+def main() -> int:
+    docs = sorted((ROOT / "docs" / "contract-additions").glob("*.md"))
+    readme = ROOT / "docs" / "surfaces" / "README.md"
+    if readme.exists():
+        docs.append(readme)
+    index = [index_doc(p) for p in docs if p.name != "README.md" or p == readme]
+    out = ROOT / "docs" / "surfaces" / "data" / "docs-index.json"
+    out.write_text(json.dumps({
+        "provenance": "live",
+        "generated_by": "tools/build_docs_index.py",
+        "doc_count": len(index),
+        "docs": index,
+    }, ensure_ascii=False, indent=2) + "\n")
+    print(f"docs-index: {len(index)} docs → {out.relative_to(ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())