docs site: address Karen's feedback — simplify, dedupe, fix rendering

[gcko]

Summary

Addresses Karen's feedback on the Spacedock docs. Her two headline asks — the docs are wordy / Spacedock feels complex, and apply the Recce doc-writing principle — drove the whole pass.

It does two things:

1. Makes the writing principle a standing rule. A new docs/site/CLAUDE.md authoring directive (adapted from Recce's doc.md) governs structure + simplicity for everything under docs/site/; it's auto-loaded when editing docs and defers to voice-and-tone.md for voice. Excluded from the published build via exclude_docs.
2. Acts on every feedback item, split into fixes that needed no decision and ones gated on a maintainer call (all resolved with @jared.scott).

Visual verification

The three issues Karen could see, before → after (slate theme, the live default):

"The layout is gone" (Home) + too many terms up front

The header rendered dark-on-dark in slate mode (Material colored header text with a dark ink while brand.css forced a dark header background). One line in brand.css restores it. The Home copy now leads with the problem before the "multi-agent orchestrator" claim and introduces 2 terms instead of 7.

Before	After

Install: numbered steps all rendered as "1", three repetitive sections

The steps restarted at "1" (3-space list indent — Python-Markdown needs 4). The three install paths are now tabs (pymdownx.tabbed), with shared Confirm / Launch steps appearing once.

Before	After

(Before = the currently-deployed spacedock.md/docs; after = this branch built locally. The header fix only becomes visible on the live site once it redeploys from this branch.)

Changes

Applied directly (writing / structure / rendering):

• Home — lead with the pain; cut the up-front term dump 7 → 2.
• Install — fix ordered-list numbering; collapse three install paths into tabs.
• Header CSS — fix dark-on-dark header/tabs in slate mode (brand.css).
• first-launch — move command grammar to the end; add internal links (workflow, commission, first officer, stage chain, approval gates).
• first-workflow — open with where a first workflow comes from; remove the duplicated gate definition.
• stage-lifecycle — reframe stages as workflow-defined, not a canonical fixed set.
• worked-example — show real z9 artifact excerpts instead of only narrating them.
• operating — dedupe "handle gate decisions" → link gates-and-decisions.
• command-reference — add a scannable command index; demote the prose lede.

Gated decisions (resolved with the maintainer):

• A Home header links are correct for spacedock.md (the landing page exists); "layout gone" was the CSS bug above.
• B Build from source moved to a new Contributing page; install keeps a pointer.
• C/D command grammar removed from install; command-reference is canonical.
• E worked-example links stay external; wording softened to "the project repo".
• F first-workflow corrected to the 4-thing design pass (+ ID style) and deduped against commission.
• G first-launch summarizes "what survey reports" and links survey for the full list.
• H removed the Sprints & roadmap page (documented an internal convention, no binary behavior).
• I merged reference/multi-host into Contributing → adding-a-runtime (it's a contributor build guide).
• J kept Command reference as-is (it is genuinely reference; the new index fixes scannability).
• K moved frontmatter-contract's rationale prose into concept pages; kept the tables.

Also: site_url set to the canonical https://spacedock.md/docs/.

How analysis was done

A multi-agent workflow read every page Karen linked against the doc-writing principle, classified each item as direct-vs-gated, and verified the rendering bugs (list-numbering reproduced through the exact Python-Markdown config; z9 artifacts confirmed real in docs/roadmap/0198-pre-flip-hardening/).

Verification

• mkdocs build --strict passes (deps pinned in docs/requirements.txt).
• All new internal cross-link anchors resolve in the built HTML.
• Header fix and install tabs confirmed in a local browser render (above).

🤖 Generated with Claude Code