spacedock-dev · clkao · Jun 13, 2026 · Jun 13, 2026 · Jun 13, 2026 · Jun 13, 2026
diff --git a/README.md b/README.md
@@ -74,71 +74,16 @@ spacedock claude "/spacedock:survey"
 Using Codex or Pi instead? Swap the subcommand: `spacedock codex "/spacedock:survey"`
 or `spacedock pi "/spacedock:survey"`.
 
-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
-
-Commission a workflow by describing what you want:
-
-```bash
-spacedock claude "/spacedock:commission Dev task workflow: design -> plan ->
-implement -> review, with the design and implementation plan inlined in each work
-item, implementation on isolated worktrees with strict TDD, design and review
-gated for approval."
-```
-
-The first officer commissions the workflow and opens a worktree for the
-implementation stage. It pauses at the design and review gates for your call.
-
-The same shape drives non-dev work. This example triages a Gmail inbox. It
-requires a Gmail integration set up before you run it:
-
-```bash
-spacedock claude "/spacedock:commission Email triage: fetch, categorize, and act
-on my Gmail inbox. Entity: a batch of up to 50 emails. Stages: intake (triage
-in:inbox, categorize, propose an action per email as a table) -> approval
-(Captain reviews the proposal) -> execute (carry out approved actions). Walk me
-through Gmail setup if needed."
-```
-
-## How it works
-
-A workflow is a directory of plain-text work item files plus a README that
-defines the stages, the schema, and the gates. Everything about a work item lives
-in the file itself: the problem, the design notes, the bar for done, the stage
-reports. State survives a session; the next one picks up where you left off.
-Three roles:
-
-| Role | Who |
-|------|-----|
-| **Captain** | You. You define the mission and make the calls at approval gates unless delegated. |
-| **First Officer** | The orchestrator agent that runs the workflow and reports to you at gates. |
-| **Ensign** | The worker agent that moves one item forward through one stage. |
-
-The first officer reads the workflow README, checks which items are ready to
-advance, and dispatches ensigns. Stages that need isolation run in their own git
-worktree; lightweight stages run inline. At a gate, the first officer pauses and
-presents the stage report for a decision: approve, redo with feedback, or
-reject. Some gates wait on you; others resolve through a delegated agent review.
-Rejected work bounces back to an earlier stage for revision. A hard cap prevents
-loops.
-
-When you end a session, `/spacedock:debrief` captures what happened: commits,
-state changes, decisions, open issues, all in a record the next session picks up.
-When a new Spacedock release is out, `/spacedock:refit` upgrades your workflow
-scaffolding while keeping local modifications.
-
-## Usage
-
-```bash
-spacedock claude "task" [--safehouse…] [-- host-flags…]   # launch the first officer in Claude Code
-spacedock codex  "task" [--safehouse…] [-- host-flags…]   # launch the first officer in Codex
-spacedock pi     "task" [--safehouse…] [-- host-flags…]   # launch the first officer in Pi
-spacedock doctor                                          # plugin compatibility check
-spacedock --version                                       # print the installed version
-```
+Full docs — the install walkthrough, the Codex and Pi paths, concepts, and the
+command reference — live at **[spacedock.md/docs](https://spacedock.md/docs/)**.
+Browsing the repo on GitHub? The same install guide is at
+[`docs/site/get-started/install.md`](docs/site/get-started/install.md).
 
 ## License
 
 Spacedock is released under the [Apache License 2.0](LICENSE).
+
+## Contributing
+
+Spacedock is early; we welcome proposals as [GitHub issues](https://github.com/spacedock-dev/spacedock/issues).
+See [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/docs/releasing.md b/docs/releasing.md
@@ -14,8 +14,13 @@ marketplace source.
 - publishes the GitHub Release with those assets;
 - bumps BOTH `spacedock-dev/homebrew-tap` casks (`spacedock` stable +
   `spacedock@next` edge) via `HOMEBREW_TAP_TOKEN`;
-- stamps the plugin manifests' `version` on `main`;
-- keeps the marketplace entry serving the stable plugin from `main`.
+- stamps the plugin manifests' `version` on `main`.
+
+The marketplace manifest no longer lives in the plugin branch. It is the
+standalone `spacedock-dev/marketplace` repo, whose entries pin each channel by
+ref — `spacedock` (stable, repointed to the released tag) and `spacedock-edge`
+(edge, tracking `next`). Repointing the stable entry is a commit in that repo,
+not a manifest stamp on `main`.
 
 The tag triggers the release, but goreleaser publishes only after the `e2e-gate`
 job confirms the tagged commit has a green Runtime Live E2E run (or a recorded
@@ -34,15 +39,16 @@ a reviewable annotated-tag changelog and manifest diff before the tag is pushed.
    ```
 
 3. Bump the version stamps with the release tool, then commit. `stamp-version`
-   writes the release `X.Y.Z` into the plugin manifests; `bump-calendar` advances
-   the marketplace entry's separate `0.0.YYYYMMDDNN` calendar key:
+   writes the release `X.Y.Z` into the plugin manifests:
 
    ```bash
    go run ./cmd/spacedock-release stamp-version X.Y.Z .claude-plugin/plugin.json .codex-plugin/plugin.json
-   go run ./cmd/spacedock-release bump-calendar .claude-plugin/marketplace.json
-   git commit -m "release: bump version to spacedock@X.Y.Z" -- .claude-plugin/plugin.json .codex-plugin/plugin.json .claude-plugin/marketplace.json
+   git commit -m "release: bump version to spacedock@X.Y.Z" -- .claude-plugin/plugin.json .codex-plugin/plugin.json
    ```
 
+   The marketplace entry is no longer stamped here — repoint the `spacedock`
+   stable entry's ref in the standalone `spacedock-dev/marketplace` repo.
+
 4. Write a changelog. Summarize the commits since the last tag into plain text:
 
    ```bash

diff --git a/docs/site/contributing/build-from-source.md b/docs/site/contributing/build-from-source.md
@@ -30,5 +30,7 @@ effect immediately. For a normal install, see [Install Spacedock](../get-started
     first-officer and ensign agents from your checkout instead of the installed
     plugin. Edits to the repo are live.
 
-The `next` branch is the development channel. It has no Homebrew release; use the
-[Homebrew install](../get-started/install.md) for a stable build.
+The `next` branch is the development channel. If you want the bleeding edge
+without building from source, install the **edge channel** (`spacedock-edge`)
+instead — it tracks `next` and ships through the same install path as stable.
+For a stable build, use the [Homebrew install](../get-started/install.md).
diff --git a/docs/site/get-started/install.md b/docs/site/get-started/install.md
@@ -10,6 +10,10 @@ Pi. Install one of those first.
     brew install spacedock
     ```
 
+    `brew install` also pulls in `agentsview` (it powers `/spacedock:survey`).
+    The optional sandbox, safehouse, is installed separately — see
+    [Sandboxing](../reference/sandbox.md).
+
 === "Binary (macOS / Linux)"
 
     ```bash

diff --git a/docs/site/reference/command-reference.md b/docs/site/reference/command-reference.md
@@ -2,6 +2,20 @@
 
 The `spacedock` binary groups its subcommands into Launch, Setup, and Workflow, plus a top-level `spacedock --version` (the binary version and contract level). For the exact flags of any command, run `spacedock <command> --help`, the always-current source of truth; `spacedock` with no arguments prints the grouped help.
 
+## --version
+
+`spacedock --version` prints the version and contract level, the sandbox posture, then a per-runtime line reporting the installed spacedock plugin version:
+
+```
+spacedock 0.20.1 (contract 1)
+Sandbox: available, not enabled (no .safehouse profile)
+claude: spacedock 0.20.1
+codex: spacedock 0.20.0 (disabled)
+pi: spacedock ready
+```
+
+The `Sandbox:` line is one of `enabled (safehouse)`, `available, not enabled (no .safehouse profile)`, or `unavailable (safehouse not on PATH)`. Each runtime line reads the plugin installed for that host: `spacedock <version>` when a plugin is installed (with ` (disabled)` appended only when the host reports it disabled), `spacedock ready` for pi (which launches from skills, not a versioned plugin), `spacedock not installed` when the host is present but carries no plugin, and `not installed` when the host binary itself is absent.
+
 ## Launch
 
 `spacedock claude`, `spacedock codex`, and `spacedock pi` start a host with the first officer loaded. Claude Code is the primary surface; Codex and Pi are experimental. The grammar is the same for all three:
@@ -12,14 +26,16 @@ spacedock claude [task] [spacedock-flags] [-- host-flags]
 
 The task comes first and becomes the launch prompt. Anything after `--` forwards verbatim to the host (`--model`, `--resume`, and the like). When no plugin is installed, the launcher auto-installs it and launches, so the single command yields a working session; a contract mismatch fails fast. The sandbox flags (`--safehouse` and its knobs) and the contract-gate flags are listed by `spacedock claude --help`.
 
+An unsandboxed launch carries no safehouse isolation, so per-action permission prompting is friction without a matching safety gain: `spacedock claude` starts in `--permission-mode auto` and `spacedock codex` in `--ask-for-approval on-request`. A sandboxed launch instead skips/bypasses approvals (`--dangerously-skip-permissions` for claude, `--dangerously-bypass-approvals-and-sandbox` for codex) since the sandbox is the gate. Either posture is suppressed when you pass your own mode or a resume.
+
 ## Setup
 
 | Command | What it does |
 |---------|--------------|
 | `spacedock install` | Install the per-host plugin, then run the compatibility check |
 | `spacedock doctor` | Run the compatibility check alone |
 
-Both take `--host claude|codex|pi` (default `claude`). When `doctor` reports the plugin is out of date, refresh it with `spacedock install`. See [Install Spacedock](../get-started/install.md) for the full setup path.
+Both take `--host claude|codex|pi` (default `claude`). When `doctor` reports the plugin is out of date, refresh it with `spacedock install`. When the plugin is still contract-compatible but a newer one is available, `doctor` and the front-door launch print an opt-in upgrade hint (`run spacedock install --host <host> to refresh`); the hint never blocks the launch. See [Install Spacedock](../get-started/install.md) for the full setup path.
 
 ## Workflow
 

diff --git a/internal/release/install_doc_test.go b/internal/release/install_doc_test.go