MkDocs Material docs site + GitHub Pages publish

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+# Builds the MkDocs Material docs site with `--strict` and publishes it to GitHub
+# Pages. The strict build runs on every PR as a check so a broken nav entry or
+# internal link fails before merge; on push to the stable branch (main) the built
+# site deploys to Pages.
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+# Allow only one concurrent deployment; do not cancel an in-progress run so a
+# deploy completes before the next starts.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Strict build. Runs on PRs and pushes alike, so the same gate that protects
+  # merges also produces the artifact the deploy job publishes.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Build the site (strict)
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  # Deploy only on push to the stable branch. PRs run the build gate above but
+  # never deploy.
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -6,6 +6,10 @@ __pycache__/
 # goreleaser build output (binaries, tarballs, checksums, generated cask).
 dist/
 
+# MkDocs build output. The docs Pages workflow rebuilds `site/` from `docs/site/`
+# + mkdocs.yml on every run; it is a generated artifact, never committed.
+/site/
+
 # Split-root state checkouts are linked worktrees on an orphan state branch, never
 # committed to the code branch (zero code-branch churn). A fresh clone re-creates
 # the checkout with `spacedock state init`.

README.md

@@ -74,7 +74,7 @@ spacedock claude "/spacedock:survey"
 Using Codex or Pi instead? Swap the subcommand: `spacedock codex "/spacedock:survey"`
 or `spacedock pi "/spacedock:survey"`.
 
-See [`docs/install-journey.md`](docs/install-journey.md) for the full first-run
+See [`docs/site/get-started/install.md`](docs/site/get-started/install.md) for the full first-run
 walkthrough, the Codex and Pi paths, and a from-source build for development.
 
 ## Quick start

docs/requirements.txt

@@ -0,0 +1,5 @@
+# Pinned build dependencies for the Spacedock docs site.
+# Installed by the Pages workflow and locally for `mkdocs build --strict`.
+mkdocs==1.6.1
+mkdocs-material==9.6.21
+mkdocs-llmstxt==0.3.0

docs/site/advanced/external-tracker.md

@@ -0,0 +1 @@
+../../specs/state-behavior-extension.md

docs/site/advanced/mods-and-standing-teammates.md

@@ -0,0 +1,3 @@
+# Mods & standing teammates
+
+[TODO] — lifecycle hooks (startup/idle/merge) under `_mods/`, and standing teammates like the comm-officer prose-polisher (which defers to the [Voice & tone](../contributing/voice-and-tone.md) guide).

docs/site/advanced/split-root-state.md

@@ -0,0 +1,3 @@
+# Multi-workflow & split-root state
+
+[TODO] — separating workflow definition from runtime state: the two roots (`definition_dir` / `state_dir`), declaring `state:` in the README, and concurrency-safe path-scoped state commits. See the [external-tracker bridge](external-tracker.md).

docs/site/advanced/sprints-and-roadmap.md

@@ -0,0 +1,3 @@
+# Sprints & roadmap
+
+[TODO] — the roadmap as the strategy layer above the workflow, the shaping-FO/Commander split, the sprint lifecycle (shape → drive → close), and the convention-only `status --where` sprint grouping.

docs/site/concepts/gates-and-decisions.md

@@ -0,0 +1,3 @@
+# Gates & decisions
+
+[TODO] — what a gate carries, the three calls (approve / redo with feedback / reject), feedback cycles and the loop cap, and the detached adversarial audit.

docs/site/concepts/operating-model.md

@@ -0,0 +1,3 @@
+# The operating model
+
+[TODO] — the three roles (Captain, First Officer, Ensign), the shaping/driving split, and how batched, evidenced decisions serve the captain.

docs/site/concepts/stage-lifecycle.md

@@ -0,0 +1,3 @@
+# The stage lifecycle
+
+[TODO] — the stages (backlog → ideation → implementation → validation → done), fresh context at validation, worktree vs. inline, and what each stage declares.

docs/site/concepts/worked-example.md

@@ -0,0 +1,3 @@
+# A worked example
+
+[TODO] — a walkthrough of one concrete, in-repo Spacedock workflow from commission to a delivered entity, tracing a single work item through the stages with real artifacts. This is the slot the `readme-real-workflow-example-link` task (e6) fills.

docs/site/concepts/workflows-and-entities.md

@@ -0,0 +1,3 @@
+# Workflows & entities
+
+[TODO] — what a workflow is (a directory plus a README), what an entity/work item is, entity frontmatter, and the state checkout. See the [Frontmatter contract](../reference/frontmatter-contract.md) for the field reference.

docs/site/contributing/adding-a-runtime.md

@@ -0,0 +1,3 @@
+# Adding a runtime
+
+[TODO] — what "supported" means, adding support in layers (skill adapters → dispatch mode → registries → launch/install UX → live runner), and the "manifesting from void" operating prompt. The full guide is [Multi-host support](../reference/multi-host.md).

docs/site/contributing/agent-development.md

@@ -0,0 +1 @@
+../../../AGENTS.md

docs/site/contributing/architecture-notes.md

@@ -0,0 +1,3 @@
+# Architecture notes
+
+[TODO] — the project shape (`cmd/`, `internal/cli`, `internal/status`, `docs/specs`, `skills/`), the design contracts under `docs/specs/`, and the runtime live CI model. See [Proof policy](proof-policy.md).

docs/site/contributing/development-workflow.md

@@ -0,0 +1 @@
+../../dev/README.md

docs/site/contributing/proof-policy.md

@@ -0,0 +1,3 @@
+# Proof policy
+
+[TODO] — behavior is proven by exercising it (not prose-grep), acceptance criteria as end-state properties with an independent source of truth, and the detached adversarial audit. The authoritative statement lives in [The development workflow](development-workflow.md).

docs/site/contributing/releasing.md

@@ -0,0 +1 @@
+../../releasing.md

docs/site/contributing/voice-and-tone.md

@@ -0,0 +1,51 @@
+# Voice & tone
+
+This is the writing-style guide for Spacedock's public documentation. It is grounded in two real voice signals, not invented:
+
+- **The root `README.md`** — Spacedock's actual public voice: direct, anti-hype, claim-first ("Spacedock is a multi-agent orchestrator where nothing ships without a decision"), concrete over abstract, second person addressed to the reader.
+- **The `comm-officer` mod** (`docs/dev/_mods/comm-officer.md`) — the project's prose discipline. It applies the `elements-of-style:writing-clearly-and-concisely` skill (Strunk) and is **light-touch by default**: "Preserve the caller's voice, rhythm, and technical vocabulary. Cut empty words, tighten sentences, fix clear grammar errors." Critically, it **defers to a project voice guide when one exists**. This page is that guide — so the comm-officer and any doc-writer apply it.
+
+## Voice
+
+- **Precise, honest, technical.** State what is true and what a thing does. Spacedock's own pitch leads with the claim, not the adjective.
+- **No marketing or hype adjectives.** Avoid "powerful", "seamless", "revolutionary", "effortless", "blazing-fast", "game-changing". If a sentence still carries its meaning with the adjective removed, remove it. The product ethos — evidence over assertion — is the writing ethos.
+- **Concrete over abstract.** Name the command, the file, the outcome. Prefer "`spacedock status --next` lists the items ready to dispatch" over "Spacedock surfaces actionable work."
+- **Claim-first, then support.** Lead a section with the load-bearing sentence; follow with the detail. Mirrors the README's "what's different" bullets (bold claim, then the mechanism).
+
+## Tone and register per audience
+
+- **New-user pages (Get started): welcoming and encouraging, still precise.** Assume no prior Spacedock knowledge; define a term on first use; show the command and the output to expect. Confidence-building, never breezy.
+- **Operator pages (Concepts, Running workflows): direct and operational.** The reader is doing the work; tell them the steps and the decision points plainly.
+- **Contributor pages (Contributing, Reference): exact and unembellished.** Precision outranks warmth. Name the contract, the test, the failure mode.
+- **Person and tense.** Second person ("you run", "you approve") and present tense for how-to and instructions — the README's register. Imperative for steps ("Run `spacedock doctor`."). Describe the system in the present tense ("the first officer dispatches an ensign"), not the future.
+
+## Canonical terminology and capitalization
+
+Pinned from how the README and skills actually use these forms — not an imposed guess. Use them consistently.
+
+| Term | Form | Notes (grounded in real usage) |
+|------|------|--------------------------------|
+| Spacedock | `Spacedock` | The product. Always capitalized. `spacedock` (lowercase, code font) only as the literal command/binary. |
+| Captain | `Captain` (role) / `the captain` (prose) | README roles table capitalizes the role name; running prose uses lowercase "the captain" (skills use `{captain}`). The human operator. |
+| First Officer | `First Officer` (role) / `the first officer` (prose) | Same pattern: Title Case in the roles table / when naming the role; lowercase in running prose ("the first officer reads the README"). The orchestrator agent. |
+| Ensign | `Ensign` (role) / `the ensign`, `ensigns` (prose) | Same pattern. The worker agent that moves one item through one stage. |
+| workflow | `workflow` | Common noun, lowercase. A directory of markdown entities + a README. |
+| entity | `entity` | Common noun, lowercase. One work item (a markdown file or folder). The README also says "work item" — prefer "entity" in docs, gloss it as "work item" on first use for new users. |
+| stage | `stage` | Common noun, lowercase. backlog → ideation → implementation → validation → done. |
+| gate | `gate` | Common noun, lowercase. The decision point at the end of a stage. |
+| sprint | `sprint` | Common noun, lowercase. A grouped set of entities driven to a deliverable. |
+| worktree, mod, safehouse | lowercase | Common nouns. `safehouse` is also the sandbox profile filename `.safehouse`. |
+
+Rule of thumb: capitalize a **role** when you name it as a role (the roles table, a definition); use lowercase for the same word in ordinary running prose; never capitalize the common-noun primitives (workflow, entity, stage, gate, sprint).
+
+## Formatting conventions
+
+- **Commands and code.** Inline code font for commands, flags, filenames, and identifiers: `spacedock claude`, `--strict`, `mkdocs.yml`. Multi-line commands and config in fenced code blocks with a language tag (` ```bash `, ` ```yaml `).
+- **Show expected output.** For a command a reader runs, name the result, as `install.md` does ("Prints the installed version, e.g. `spacedock 0.20.0`").
+- **Headings.** Sentence case ("Get started", "Your first workflow"), not Title Case. One `#` h1 per page (the page title); section headings start at `##`.
+- **Links.** Descriptive link text, never "click here" / "this link". Internal links are relative so `mkdocs build --strict` can resolve them.
+- **Lists and emphasis.** Bullets for parallel items; bold for the load-bearing claim of a bullet (the README pattern). Use emphasis sparingly — if everything is bold, nothing is.
+
+## How this guide is applied
+
+The `comm-officer` mod loads a project voice guide on first use and defers to it over plain Strunk. Once this page ships, it is that guide: doc contributions and comm-officer polish follow these rules. When this guide is silent on a question, fall back to Strunk via `elements-of-style:writing-clearly-and-concisely`.

docs/site/get-started/first-launch.md

@@ -0,0 +1,3 @@
+# Your first launch
+
+[TODO] — launching the first officer with `spacedock claude "/spacedock:survey"`, the front-door command grammar, and what survey reports.

docs/site/get-started/first-workflow.md

@@ -0,0 +1,3 @@
+# Your first workflow
+
+[TODO] — commissioning your first workflow with `/spacedock:commission`, the design and review gates, and what happens after.

docs/site/index.md

@@ -0,0 +1,9 @@
+# Spacedock
+
+**Spacedock is a multi-agent orchestrator where nothing ships without a decision.** It lives within your existing harness — Claude Code, Codex, or Pi.
+
+[TODO] — the Home page: the pitch, what's different, and where to go next (Get started, Concepts, Running workflows, Contributing).
+
+## For agents using Spacedock
+
+Spacedock's docs are read by agents too — a user's first officer parsing these docs is itself an agent. The build emits a curated `llms.txt` index of the docs at the site root for product-using agents. (Repo-development guidance for an agent working ON Spacedock lives under Contributing → [Agent development](contributing/agent-development.md).)

docs/site/reference/command-reference.md

@@ -0,0 +1,3 @@
+# Command reference
+
+[TODO] — the `spacedock` command surface grouped into Launch (`claude`/`codex`/`pi`), Setup (`install`/`doctor`), and Workflow (`status`/`new`/`state`/`completion`/`dispatch`), plus `--version` and the `status` query forms.

docs/site/reference/frontmatter-contract.md

@@ -0,0 +1,3 @@
+# Frontmatter contract
+
+[TODO] — the entity frontmatter field reference (surfacing the development workflow's "Schema / Field Reference" table) plus the external-tracker `issue`/`source` fields. The always-current schema is in [The development workflow](../contributing/development-workflow.md); a standalone `docs/specs/frontmatter-contract.md` is a planned follow-up.

docs/site/reference/multi-host.md

@@ -0,0 +1 @@
+../../runtime-support.md

docs/site/running-workflows/commission.md

@@ -0,0 +1,3 @@
+# Commission a workflow
+
+[TODO] — generating a workflow from a description with `/spacedock:commission`: the four things to name (stages, entity, gated stages, per-stage rules) and what the first officer does next.

docs/site/running-workflows/debrief-and-refit.md

@@ -0,0 +1,3 @@
+# Debrief & refit
+
+[TODO] — `/spacedock:debrief` (capture a session into a record the next one resumes from) and `/spacedock:refit` (upgrade workflow scaffolding to the current release while keeping local edits).

docs/site/running-workflows/operating.md

@@ -0,0 +1,3 @@
+# Operating a workflow
+
+[TODO] — the day-to-day loop (see what's ready, dispatch, handle gates), the `spacedock status` queries (`--next`, `--where`), and handling gate decisions. See the [Command reference](../reference/command-reference.md).

docs/site/running-workflows/survey.md

@@ -0,0 +1,3 @@
+# Survey an existing project
+
+[TODO] — reading a brownfield project's agent history with `/spacedock:survey` (read-only), what it reports, and how it offers to commission a workflow from what it found.

install.sh

@@ -41,7 +41,7 @@ detect_os() {
 	case "$(uname -s)" in
 		Darwin) echo darwin ;;
 		Linux) echo linux ;;
-		*) die "unsupported OS $(uname -s); see docs/install-journey.md for source build" ;;
+		*) die "unsupported OS $(uname -s); see docs/site/get-started/install.md for source build" ;;
 	esac
 }
 

internal/release/install_doc_test.go

@@ -27,7 +27,7 @@ func TestInstallJourneyDocumentsLinuxPath(t *testing.T) {
 		}
 	}
 	if !found {
-		t.Errorf("docs/install-journey.md has no runnable `curl … install.sh | sh` Linux install line")
+		t.Errorf("docs/site/get-started/install.md has no runnable `curl … install.sh | sh` Linux install line")
 	}
 }
 
@@ -64,7 +64,7 @@ func TestInstallJourneyDoesNotOverclaimLinuxSandbox(t *testing.T) {
 
 func readInstallJourney(t *testing.T) string {
 	t.Helper()
-	data, err := os.ReadFile(filepath.Join("..", "..", "docs", "install-journey.md"))
+	data, err := os.ReadFile(filepath.Join("..", "..", "docs", "site", "get-started", "install.md"))
 	if err != nil {
 		t.Fatal(err)
 	}

mkdocs.yml

@@ -0,0 +1,99 @@
+site_name: Spacedock
+site_description: A multi-agent orchestrator where nothing ships without a decision.
+site_url: https://spacedock-dev.github.io/spacedock/
+repo_url: https://github.com/spacedock-dev/spacedock
+repo_name: spacedock-dev/spacedock
+copyright: Spacedock is released under the Apache License 2.0.
+
+docs_dir: docs/site
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - content.code.copy
+    - content.tabs.link
+    - search.suggest
+    - search.highlight
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.instant
+
+plugins:
+  - search
+  - llmstxt:
+      markdown_description: >-
+        Documentation for Spacedock, a multi-agent orchestrator where nothing
+        ships without a decision. It lives within your existing coding harness
+        (Claude Code, Codex, or Pi), breaks work into stages, and surfaces an
+        evidenced decision at each gate.
+      sections:
+        Get started:
+          - index.md
+          - get-started/*.md
+        Concepts:
+          - concepts/*.md
+        Running workflows:
+          - running-workflows/*.md
+        Advanced topics:
+          - advanced/*.md
+        Reference:
+          - reference/*.md
+        Contributing:
+          - contributing/*.md
+
+nav:
+  - Home: index.md
+  - Get started:
+      - Install: get-started/install.md
+      - Your first launch: get-started/first-launch.md
+      - Your first workflow: get-started/first-workflow.md
+  - Concepts:
+      - The operating model: concepts/operating-model.md
+      - Workflows & entities: concepts/workflows-and-entities.md
+      - The stage lifecycle: concepts/stage-lifecycle.md
+      - Gates & decisions: concepts/gates-and-decisions.md
+      - A worked example: concepts/worked-example.md
+  - Running workflows:
+      - Commission a workflow: running-workflows/commission.md
+      - Survey an existing project: running-workflows/survey.md
+      - Operating a workflow: running-workflows/operating.md
+      - Debrief & refit: running-workflows/debrief-and-refit.md
+  - Advanced topics:
+      - Sprints & roadmap: advanced/sprints-and-roadmap.md
+      - Mods & standing teammates: advanced/mods-and-standing-teammates.md
+      - External-tracker bridge: advanced/external-tracker.md
+      - Multi-workflow & split-root state: advanced/split-root-state.md
+  - Reference:
+      - Command reference: reference/command-reference.md
+      - Frontmatter contract: reference/frontmatter-contract.md
+      - Multi-host support: reference/multi-host.md
+  - Contributing:
+      - The development workflow: contributing/development-workflow.md
+      - Agent development: contributing/agent-development.md
+      - Proof policy: contributing/proof-policy.md
+      - Adding a runtime: contributing/adding-a-runtime.md
+      - Releasing: contributing/releasing.md
+      - Voice & tone: contributing/voice-and-tone.md
+      - Architecture notes: contributing/architecture-notes.md
+
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - toc:
+      permalink: true