roodboi · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026 · Oct 19, 2026
diff --git a/docs/env.md b/docs/env.md
@@ -262,6 +262,7 @@ into a host command, and `--target` on env and host commands chooses the `host`
 | `hack host shell` | `--env`, `--scope`, `--target` | When the shell starts. | Start a new shell. | Runs on the host, not in a container. |
 | `hack config validate` | `--env` | Per invocation; resolves the native selection without reading managed env documents. | Not needed. | Authored native projects only; cannot be combined with `--file`. |
 | `hack config plan` | `--env` | Per invocation; metadata only (names, scopes, secret flags), never decrypted. | Not needed. | Authored native projects only. |
+| `hack project target` | `--env`, `--service` | Per invocation, read-only; reports the overlay selection (explicit, project default or base) without reading env files or values. | Not needed. | Selection only: overlay existence is not checked; no runtime required. |
 | `hack session start` | `--env`, `--service` | When the workspace is created; the name gains `.env-<name>` (`.env-base` for base spellings), and `--up` runs `hack up -d` with the same selection. | Start a new workspace or pass `--env` to `hack session exec`. | Injects into the workspace shell, not into containers. |
 | `hack session exec` | `--env`, `--service` | Per command; omitted reuses the selection encoded in the workspace name. | Each command resolves again. | Injects into the workspace command, not into containers. |
 

diff --git a/docs/guides/candidate-install.md b/docs/guides/candidate-install.md
@@ -30,8 +30,10 @@ latest-version lookup or automatic updater.
 By default installation creates a private, current-user-owned mode-`0700`
 `~/.hack-next` directory. Each immutable version directory contains a complete
 bundle, its own `native-home`, and its own `cli-home`. An installation receipt binds
-the bundle hashes and both homes' filesystem identities. Stable Homebrew `hack`,
-its links, and `~/.hack` are untouched. No shell profile or PATH is edited.
+the bundle hashes and both homes' filesystem identities. Installation leaves stable
+Homebrew `hack`, its links, and `~/.hack` untouched; only an explicit
+[Compose test](#test-both-backends) uses your own Hack home. No shell profile or
+PATH is edited.
 
 Run the candidate explicitly:
 
@@ -41,9 +43,13 @@ Run the candidate explicitly:
 python3 "$HOME/.hack-next/manager.py" --root "$HOME/.hack-next" status
 ```
 
-`hack-next` selects the adjacent verified native executor and the selected version's
-private native and CLI homes. These settings override inherited installation
-selectors, including `HACK_GLOBAL_CONFIG_PATH`. Explicit native project adaptation,
+By default `hack-next` uses the native backend. It selects the adjacent verified
+native executor and the selected version's private native and CLI homes. These
+settings override inherited installation selectors, including `HACK_NATIVE_BINARY`,
+`HACK_NATIVE_HOME`, `HACK_HOME` and `HACK_GLOBAL_CONFIG_PATH`. To run the same
+verified candidate on the Compose backend, set `HACK_RUNTIME_BACKEND=compose`; see
+[Test both backends](#test-both-backends). Any other non-empty value refuses before
+the candidate starts. Explicit native project adaptation,
 dependency, AWS profile, routing, and source-sharing settings still reach the CLI.
 Arguments, standard input and output, exit codes, and signals reach the selected
 candidate. Concurrent observation and stop commands can accompany a foreground
@@ -63,7 +69,54 @@ Provider setup and actual application acceptance remain separate steps. Installa
 does not install the provider, boot a VM, enroll a project, move volumes, or activate
 system DNS or trust. Follow [native candidate preparation](native-candidate.md)
 using the selected bundle and its `native-home`. Candidate `hack-next update`
-retains the existing refusal; use the channel manager's explicit upgrade command.
+retains the existing refusal on both backends; use the channel manager's explicit
+upgrade command.
+
+## Test both backends
+
+The same selected candidate can run on either backend. You do not need to call the
+bundled `hack-cli` directly or create a private `HACK_HOME` to test Compose.
+
+| Backend | Command | Hack home | Routing, DNS and TLS |
+| --- | --- | --- | --- |
+| Native (default) | `"$HOME/.hack-next/bin/hack-next" up --path /absolute/project` | The version's private `cli-home` and `native-home` | The candidate's native routing, set up through [native candidate preparation](native-candidate.md) |
+| Compose | `HACK_RUNTIME_BACKEND=compose "$HOME/.hack-next/bin/hack-next" up --path /absolute/project` | Your own `HACK_HOME` (default `~/.hack`) and `HACK_GLOBAL_CONFIG_PATH` | Your existing global Caddy, CoreDNS and local CA |
+
+With `HACK_RUNTIME_BACKEND=compose`, `hack-next` verifies the selected bundle as
+usual and then runs its `hack-cli` on the Compose backend. It keeps your Hack home,
+so `https://<project>.hack` routes, container DNS and CA trust use the global
+services that `hack global install` already set up. It removes `HACK_NATIVE_BINARY`
+and `HACK_NATIVE_HOME` so native selections cannot reach Compose children. The
+candidate's private homes are not used. Compose `up` still uses the configurable
+Compose startup budget; a cold image build can need a larger
+`HACK_COMPOSE_STARTUP_TIMEOUT_MS`.
+
+Compose testing shares state with stable Hack:
+
+- The candidate reads and writes the same project registry, global configuration
+  and project `.hack/` files as stable `hack`. Stable v4 uses an older registry
+  lock protocol, so do not run stable `hack` and the candidate against the same
+  home at the same time. Stop one before you start the other.
+- `hack-next` does not set up the shared global services for you. Install or
+  change them with stable `hack global` commands.
+- To test Compose in isolation instead, set `HACK_HOME` to a separate private
+  directory. That home has no global services, so routing, container DNS and CA
+  trust are not tested.
+
+Leave `HACK_RUNTIME_BACKEND` unset, or set it to `native`, to return to the native
+default. A shell that exported `HACK_RUNTIME_BACKEND=compose` for other work also
+selects Compose for `hack-next`; unset it before native testing.
+
+Backend selection needs the current channel manager. The manager released with
+`5.0.0-next.3` through `5.0.0-next.5` always selects native, and ignores
+`HACK_RUNTIME_BACKEND=compose`. Run the reviewed `upgrade-manager` operation below
+once to receive backend selection. This works for every retained bundle, including
+`5.0.0-next.5`. Candidate CLIs from `5.0.0-next.5` and earlier refuse `update` only
+on the native backend; do not run `hack-next update` on Compose with those bundles.
+
+The bundled `hack-v5` entrypoint follows the same rule for manual bundles:
+unset selects native and requires `HACK_NATIVE_HOME`; `compose` needs no native
+home and uses your own Hack home.
 
 ## Upgrade and return to a retained candidate
 

diff --git a/docs/guides/native-candidate.md b/docs/guides/native-candidate.md
@@ -110,8 +110,14 @@ export HACK_NATIVE_HOME=/absolute/private/candidate-home
 ```
 
 Keep the bundle together and invoke this entrypoint by its full path (do not copy
-or symlink only the script). It selects the adjacent executor even if inherited
-backend variables select another binary. It preserves arguments, exit codes and
+or symlink only the script). With `HACK_RUNTIME_BACKEND` unset (or `native`) it
+selects the native backend and the adjacent executor, even if an inherited
+`HACK_NATIVE_BINARY` selects another binary. An explicit
+`HACK_RUNTIME_BACKEND=compose` runs the same bundled CLI on the Compose backend
+with your own Hack home and existing global routing services. It needs no
+`HACK_NATIVE_HOME` and removes the native selectors. Other values refuse with exit
+code 64. The [candidate installer guide](https://github.com/hack-dance/hack/blob/next/docs/guides/candidate-install.md#test-both-backends)
+describes Compose testing and its shared-state limits. It preserves arguments, exit codes and
 signals through `exec`, and never replaces the installed `hack`. Project-specific
 native adaptation, dependency and routing selections remain explicit; this entrypoint
 does not prepare a provider or migrate existing projects. An unversioned local

diff --git a/docs/guides/portable-bootstrap-qualification.md b/docs/guides/portable-bootstrap-qualification.md
@@ -56,6 +56,18 @@ available container capabilities, and any skips. Review the tested Install
 script and Start skill before publishing the private environment. A local or
 ordinary Linux-container result does not qualify Codex Cloud by itself.
 
+## Negative controls in Docker CI
+
+The hosted `docker-e2e` job also runs the `portable-bootstrap-negatives` scenario.
+On the slim path, it checks that a missing key, a wrong key, an overlay sealed
+under another key, a stale pinned image, a lockfile that no longer matches its
+manifest and a corrupted dependency cache each stop the bootstrap without
+changing a running app. It also checks that a second identical bootstrap leaves
+no diff and does not reinstall. Each stage records its time and byte counts in a
+value-free receipt. See
+[the e2e harness guide](../../tests/e2e/README.md#portable-bootstrap-negative-controls)
+for the stages and what they do not cover.
+
 ## Repeat maintenance
 
 `scripts/maintain-codex-slim.sh` installs dependencies with

diff --git a/docs/guides/v5-dogfooding.md b/docs/guides/v5-dogfooding.md
@@ -9,8 +9,9 @@ compatibility, lower resource use or whole-product readiness.
 
 The [version-pinned candidate installer](candidate-install.md) provides `hack-next`
 alongside stable `hack`. It does not replace Homebrew Hack, edit PATH, convert
-projects, move volumes, enable DNS or trust, or start a VM. Candidate homes and
-stable state are separate. Do not alias `hack` to `hack-next` as a rollout step.
+projects, move volumes, enable DNS or trust, or start a VM. On the default native
+backend, candidate homes and stable state are separate; an explicit Compose test
+uses your own Hack home. Do not alias `hack` to `hack-next` as a rollout step.
 
 Each candidate upgrade starts fresh native and CLI homes. Retained bundles keep
 their original homes; selecting another version does not migrate application data.
@@ -35,6 +36,11 @@ These commands do not establish that an arbitrary v4 project can run natively.
    the [candidate guide](native-candidate.md), with admitted storage and an explicitly
    approved source share and network policy. A refused guard is a result to inspect,
    not permission to change host security, erase evidence or raise resource limits.
+   Test the backend the project will use. `hack-next` runs native by default;
+   `HACK_RUNTIME_BACKEND=compose hack-next` runs the same candidate on Compose with
+   your own Hack home, so global routing, DNS and CA trust are checked too. See
+   [Test both backends](candidate-install.md#test-both-backends), including why
+   stable `hack` must not run against the same home at the same time.
 3. Exercise the project's supported command form: foreground start, readiness,
    status, finite logs, noninteractive exec, retaining stop and restart. Exercise
    one-off run only where admitted. For an authored project, check generated public

diff --git a/docs/reference.md b/docs/reference.md
@@ -30,3 +30,4 @@
 - [Integrations](./integrations.md)
 - [MCP tool contract](./reference/mcp-tools.md) — every MCP tool: annotations, inputs, argv, results, and the value-free env tools
 - [MCP logs contract](./reference/mcp-logs.md) — cutoff versus backend failure for the MCP log tools, and the cursor/handle decision
+- [AX target and result contract](./reference/ax-target-result-contract.md) — provisional target schema, closed refusals and the read-only `hack project target` inspector