docs: design self-contained install docs fixtures

docs/superpowers/specs/2026-08-20-workspace-install-docs-fixture-self-containment-design.md

@@ -0,0 +1,97 @@
+# Workspace Install Docs Fixture Self-Containment — Design
+
+**Date:** 2026-08-20
+
+**Status:** Approved for implementation
+
+## Purpose
+
+Restore the documented direct invocation of `scripts/verify-workspace-install-docs.sh` so it passes
+in a clean environment without inheriting `TMPDIR` or `THT_AUTH_CONFIG_ROOT` from the operator.
+The verifier must prove that its generated local/server installation fixtures are complete by
+themselves.
+
+## Observed regression
+
+Two independent gaps stop the current `--fixtures-only` path:
+
+1. several `mktemp` calls expand `TMPDIR` under `set -u` without a default;
+2. the authentication lifecycle commit made `THT_AUTH_CONFIG_ROOT` mandatory in `compose.yaml`,
+   while the local, server, and canonical Compose fixture environments still omit it.
+
+The failure is unrelated to the PSD checklist commits. Supplying both values externally makes the
+entire fixture suite pass, which confirms the missing-input boundary but is not an acceptable
+long-term workaround.
+
+## Scope
+
+Modify only:
+
+- `scripts/verify-workspace-install-docs.sh`
+- `scripts/test-verify-workspace-install-docs.sh`
+
+Do not modify Compose, authentication runtime code, documentation examples, the PSD server, Docker
+resources, or the legacy stack.
+
+## Required behavior
+
+### Temporary directory contract
+
+Every `mktemp` call in the production verifier must use `/tmp` when `TMPDIR` is absent. An explicitly
+provided `TMPDIR` remains supported. The verifier must not mutate or export the caller's environment.
+
+### Authentication fixture contract
+
+Each Compose-rendering fixture owns a distinct authentication configuration directory inside its
+fixture root:
+
+- local installation example fixture;
+- server installation example fixture;
+- canonical local/server Compose fixture.
+
+Each generated fixture environment sets `THT_AUTH_CONFIG_ROOT` to that directory. The directory is
+created before Compose rendering and contains no real credential. Tests assert that the rendered
+core service mounts the expected source at `/run/thothii-auth` read-only, so an ambient host value
+cannot mask an incomplete fixture.
+
+### Regression-test contract
+
+The test runner invokes the production `--fixtures-only` verifier with both `TMPDIR` and
+`THT_AUTH_CONFIG_ROOT` explicitly absent. This test must fail on the current source for the observed
+reason and pass only after both self-containment gaps are fixed.
+
+## TDD sequence
+
+1. Change only the test runner so it removes both variables for the production-verifier call.
+2. Run the focused test and retain the expected RED result.
+3. Add the `/tmp` fallback to the production verifier; rerun and confirm the remaining RED result is
+   the missing auth root.
+4. Add fixture-owned auth directories, environment entries, and rendered-mount assertions.
+5. Run the focused test and direct clean-environment verifier to GREEN.
+6. Run shell syntax checks, documentation smoke checks, and `git diff --check`.
+
+## Failure handling
+
+- A missing fixture auth directory or environment entry fails before a PASS is printed.
+- A rendered auth mount with the wrong source, target, or read-only flag fails the fixture.
+- A scanner or Compose error remains an error; it is not reclassified as an expected negative.
+- Temporary fixture cleanup remains bounded to paths created by `mktemp`.
+
+## Acceptance
+
+All of the following must pass from the repository root:
+
+```bash
+env -u TMPDIR -u THT_AUTH_CONFIG_ROOT \
+  bash scripts/verify-workspace-install-docs.sh --fixtures-only
+
+env -u TMPDIR -u THT_AUTH_CONFIG_ROOT \
+  bash scripts/test-verify-workspace-install-docs.sh
+
+bash -n scripts/verify-workspace-install-docs.sh
+bash -n scripts/test-verify-workspace-install-docs.sh
+bash scripts/auth-docs-smoke.sh
+git diff --check
+```
+
+No acceptance command starts, stops, reloads, builds, or otherwise mutates the PSD server stack.