# 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.