Document tooling adapter matrix

.ai-context/overview.md

@@ -28,6 +28,13 @@ similar tools. Use that policy when interpreting the local `.mise.toml`,
 command-level `runner: uv`, `infra/compose.yaml`, and `.ai-context/` examples
 in this repository.
 
+Local tooling-testbed policy lives in `docs/tooling-testbed.md`. It keeps
+Brewfile, mise, uv, Docker Compose, and VS Code manifest fields in the active
+Baseline while treating `devcontainer`, `devenv-report`, Nix/devenv, just,
+Taskfile, direnv, asdf, chezmoi, dotbot, mani, gita, vcs2l, west, and future
+docker-service work as optional, reference-only, or blocked until their issue
+slice promotes them.
+
 ## Purpose
 
 - Show what a well-structured `base_manifest.yaml` looks like
@@ -63,6 +70,7 @@ in this repository.
 | `demo/demo.sh` | Interactive walkthrough |
 | `tests/validate.sh` | Baseline validation (the declared test command) |
 | `docs/representative-environment.md` | Direction for the multi-language representative environment |
+| `docs/tooling-testbed.md` | Local matrix for active, optional, reference-only, and future external tool examples |
 
 ## Quick Loop
 

CHANGELOG.md

@@ -45,6 +45,9 @@ and versions are tracked in the repo-root `VERSION` file.
 - Added `.github/pull_request_template.md` for consistent PR descriptions.
 - Added WSL2 readiness guidance for the Ubuntu/Debian Base path and exposed
   `BASE_HOST_ENV` in the demo `env` command.
+- Added `docs/tooling-testbed.md` and a tooling PR-train plan to separate
+  active baseline tools from optional wrappers, reference-only examples, and
+  future Base contracts.
 
 ### Changed
 

README.md

@@ -18,6 +18,12 @@ Binding promises between the manifest, demo, services, installer, CI, and docs
 are tracked in [Contracts](docs/contracts.md). Update that registry whenever a
 new invariant becomes part of the reference project.
 
+The external tooling direction is tracked in
+[Tooling Test Bed](docs/tooling-testbed.md). That matrix separates active
+baseline tools from optional wrappers, reference-only examples, and future Base
+contracts so `base-demo` can test adoption paths without hiding new
+requirements in the default demo.
+
 ## Platform Requirements
 
 macOS is the supported platform for the full interactive demo: setup,
@@ -250,6 +256,9 @@ deterministic without needing an interactive activated shell.
   `environments/prod.json` model environment-specific configuration. Only
   `dev` is operational by default.
 - `.mise.toml` declares tool versions (Python 3.13) managed by mise.
+- `docs/tooling-testbed.md` defines how base-demo represents tools such as
+  direnv, asdf, chezmoi, dotbot, just, Taskfile, mani, gita, vcs2l, west,
+  devcontainers, Nix/devenv, and future Docker service support.
 - `demo/demo.sh` is the interactive walkthrough.
 - `tests/validate.sh` verifies that the repository baseline is intact.
 

docs/contracts.md

@@ -29,6 +29,7 @@ depend on.
 | `ubuntu-ci` | The repository has an Ubuntu job that runs `basectl setup base --yes --no-notify`, validates `basectl setup base --profile dev --yes --no-notify`, verifies `bats`/`gh`/`shellcheck`, and runs `basectl check --ci base-demo --format json` against the pinned Base checkout. | `.github/workflows/tests.yml` | `tests/validate.sh`, GitHub Actions `validate-ubuntu` | Ubuntu support can drift from the documented Base setup, dev-profile, and read-only project health boundary. | CI |
 | `platform-boundary` | README and CONTRIBUTING document macOS full-demo support plus Ubuntu/Debian and WSL2 support for Base setup, dev-profile prerequisites, read-only project health checks, repo-location guidance, and the native-Windows non-goal. | `README.md`, `CONTRIBUTING.md` | `tests/validate.sh` | Developers on Linux or WSL2 follow macOS-only project setup or demo steps without a documented boundary. | Docs |
 | `ci-json-check` | The demo shows `basectl check --ci base-demo --format json` and asserts JSON status output. | `demo/demo.sh`, `README.md` | `tests/validate.sh`, `tests/demo_test.bats`, `.github/workflows/tests.yml` | The reference project stops demonstrating Base's CI-safe machine-readable check path. | CI |
+| `tooling-testbed-boundary` | The tooling matrix separates active baseline tools, optional live wrappers, reference-only examples, Base-generated environment views, and blocked future Docker service support. | `docs/tooling-testbed.md`, `README.md`, `.ai-context/overview.md` | `tests/validate.sh` | base-demo can accidentally make external tools required, duplicate Base-owned behavior, or imply support before Base publishes the contract. | Docs |
 
 ## How To Use This Registry
 

docs/superpowers/plans/2026-07-25-base-demo-tooling-testbed-train.md

@@ -0,0 +1,32 @@
+# Base Demo Tooling Test Bed Train
+
+Goal: keep `base-demo` in lockstep with Base while making it a practical test
+bed for external development tools.
+
+Architecture: Base stays the operator-facing surface. Tools that are already
+part of the Base path can be active in the baseline. Tools that alter shell
+state, dotfiles, checkout synchronization, or package-manager behavior stay
+reference-only until a separate issue promotes them.
+
+## Issue And PR Order
+
+| Order | Issue | PR intent | Notes |
+| --- | --- | --- | --- |
+| 1 | #178 Define base-demo tooling adapter matrix | Document the policy, register the contract, and add validation guards. | Foundation for the rest of the train. |
+| 2 | #182 Demonstrate devcontainer and devenv-report against base-demo | Add CI-safe `basectl devcontainer` and `basectl devenv-report` examples. | Should not make containers or Nix/devenv the baseline runtime. |
+| 3 | #180 Add optional just and Taskfile wrappers for Base commands | Add optional wrappers that delegate to `basectl`. | Keep Base commands authoritative. |
+| 4 | #179 Add reference-only direnv asdf and dotfile tooling examples | Add inactive examples for `direnv`, `asdf`, `chezmoi`, and `dotbot`. | Avoid root-level files that mutate developer shell or home state. |
+| 5 | #181 Add read-only multi-repo manager examples | Add inactive examples for `mani`, `gita`, `vcs2l`, and `west`. | Align examples to `workspace.yaml.example`. |
+| Hold | #163 Track future Base docker-service adoption in base-demo | Adopt the future Base Docker service contract. | Blocked by basefoundry/base#124. |
+
+## Validation Pattern
+
+Each PR should update only the files needed for its slice and run:
+
+```bash
+./tests/validate.sh
+git diff --check
+```
+
+Add focused BATS or command-level validation when a slice changes demo behavior
+or executable wrappers.

docs/tooling-testbed.md

@@ -0,0 +1,63 @@
+# Tooling Test Bed
+
+`base-demo` is the reference project for Base-managed repositories and the
+place where Base proves how it coexists with common local development tools.
+This document defines the adapter boundary for that test bed.
+
+Base remains the operator-facing entry point. External tools can be represented
+in this repository when they teach a real adoption path, but they should not
+become hidden requirements for the baseline demo unless Base itself owns that
+contract.
+
+## Boundary Rules
+
+- Baseline tools are allowed in root-level active configuration when they are
+  already part of the supported Base path and are validated by CI.
+- Optional live tools may add convenience wrappers or generated artifacts, but
+  they must delegate back to `basectl` and remain optional for the default
+  validation loop.
+- Reference-only tools live under examples or docs until there is a deliberate
+  decision to make them active. Do not add root-level files that can change a
+  developer shell, home directory, checkout graph, or package manager behavior
+  without a separate issue.
+- External tool configuration remains authoritative to the external tool. Base
+  can check, report, generate, or invoke it; Base should not silently import or
+  synchronize that state.
+- The macOS full-demo path and the Ubuntu/Debian/WSL2 read-only health path are
+  the current platform boundary. Native Windows and future Docker service
+  support should stay explicitly scoped until Base publishes the contract.
+
+## Adapter Matrix
+
+| Layer | Tools | Current base-demo stance | Next action |
+| --- | --- | --- | --- |
+| Baseline | Brewfile, mise, uv, Docker Compose, VS Code manifest fields | Active. `Brewfile`, `.mise.toml`, command-level `runner: uv`, `infra/compose.yaml`, and `base_manifest.yaml` are part of the committed demo contract. | Keep validated through `tests/validate.sh`, BATS suites, and Base-backed CI. |
+| Base-generated environment views | `basectl devcontainer`, `basectl devenv-report`, Nix/devenv policy | Not yet demonstrated locally. These should prove Base can describe the project for container and Nix/devenv-style environments without making either the baseline runtime. | Issue #182: add generated or dry-run artifacts and CI checks for the reports. |
+| Optional live task wrappers | just, Taskfile | Not present. They are useful as ergonomic aliases, but they must call `basectl` rather than create a second command contract. | Issue #180: add optional wrappers and validation that they delegate to Base commands. |
+| Reference-only shell and dotfile tools | direnv, asdf, chezmoi, dotbot | Not present. These tools can teach adoption boundaries, but root-level activation files would change developer state too aggressively for the baseline. | Issue #179: add reference examples and docs under an examples path, not active root files. |
+| Reference-only multi-repo managers | mani, gita, vcs2l, west | Not present. Base's current workspace view is `workspace.yaml.example`; multi-repo managers should illustrate coexistence without owning checkout synchronization. | Issue #181: add read-only example configs that point at the Base workspace shape. |
+| Future Docker service | `basectl docker-service` | Blocked upstream. `base-demo` already has Compose-backed services, but it should not invent a Base docker-service contract before Base lands it. | Issue #163 remains blocked on basefoundry/base#124. |
+
+## PR Train
+
+| Order | Issue | Purpose | Expected PR shape |
+| --- | --- | --- | --- |
+| 1 | #178 | Define the tooling adapter matrix. | Docs, contract registry, AI context, and validation guards. |
+| 2 | #182 | Demonstrate Base-generated environment reports. | Add `devcontainer` and `devenv-report` dry-run or generated artifacts with CI-safe checks. |
+| 3 | #180 | Add optional task-runner aliases. | Add `just` and Taskfile examples that delegate to `basectl` and are not required for baseline CI. |
+| 4 | #179 | Add reference env and dotfile examples. | Add inactive examples for `direnv`, `asdf`, `chezmoi`, and `dotbot` with docs that explain trust and activation boundaries. |
+| 5 | #181 | Add read-only multi-repo manager examples. | Add inactive examples for `mani`, `gita`, `vcs2l`, and `west` aligned to `workspace.yaml.example`. |
+| Hold | #163 | Adopt future Base Docker service support. | Wait for basefoundry/base#124, then wire the contract through service docs and validation. |
+
+## Acceptance Policy
+
+A new tool graduates into the baseline only when all of these are true:
+
+- Base has a documented contract for the behavior.
+- `base-demo` can demonstrate it without requiring privileged local state or a
+  long-running service by default.
+- README, AI context, and `docs/contracts.md` describe the same boundary.
+- `tests/validate.sh` or a focused test fails when the contract drifts.
+
+Until then, the tool belongs in optional wrappers, generated artifacts, or
+reference-only examples.

tests/validate.sh

@@ -24,6 +24,7 @@ required_files=(
   workspace.yaml.example
   docs/contracts.md
   docs/representative-environment.md
+  docs/tooling-testbed.md
   base_manifest.yaml
   Brewfile
   .mise.toml
@@ -766,14 +767,54 @@ for contract in \
   ci-pinned-dependencies \
   ubuntu-ci \
   platform-boundary \
-  ci-json-check
+  ci-json-check \
+  tooling-testbed-boundary
 do
   grep -Fq "| \`$contract\` |" docs/contracts.md || {
     printf 'docs/contracts.md does not list contract %s.\n' "$contract" >&2
     exit 1
   }
 done
 
+grep -Fq 'docs/tooling-testbed.md' README.md || {
+  printf 'README.md does not reference docs/tooling-testbed.md.\n' >&2
+  exit 1
+}
+
+grep -Fq 'docs/tooling-testbed.md' .ai-context/overview.md || {
+  printf '.ai-context/overview.md does not reference docs/tooling-testbed.md.\n' >&2
+  exit 1
+}
+
+for tooling_section in Baseline 'Optional live' 'Reference-only'; do
+  grep -Fq "$tooling_section" docs/tooling-testbed.md || {
+    printf 'docs/tooling-testbed.md does not document tooling section: %s.\n' "$tooling_section" >&2
+    exit 1
+  }
+done
+
+for tooling_token in \
+  direnv \
+  asdf \
+  chezmoi \
+  dotbot \
+  just \
+  Taskfile \
+  mani \
+  gita \
+  vcs2l \
+  west \
+  devcontainer \
+  devenv-report \
+  'Nix/devenv' \
+  docker-service
+do
+  grep -Fq "$tooling_token" docs/tooling-testbed.md || {
+    printf 'docs/tooling-testbed.md does not document tooling token: %s.\n' "$tooling_token" >&2
+    exit 1
+  }
+done
+
 grep -Fq 'BASE_OS' README.md && grep -Fq 'BASE_PLATFORM' README.md && grep -Fq 'BASE_HOST_ENV' README.md && grep -Fq 'BASE_HOST' README.md || {
   printf 'README.md does not document the env command BASE_OS/BASE_PLATFORM/BASE_HOST_ENV/BASE_HOST output.\n' >&2
   exit 1