Feature Matrix

This file is a contract, not a summary. scripts/qa/check-feature-matrix.sh parses it on every push and fails when:

• a command routed by lib/dot/data/routes.txt, or listed in docs/manual/command-index.md (old names included), has no row here;
• a row names a command that is neither routed nor listed there;
• a row names a regression test function that no tests/regression/test_feature_matrix_*.sh file defines, or that its file never calls;
• a row names a benchmark id that benches/dot_command_bench.sh --list-ids does not produce, or a routed command has no help:<cmd> cold-start benchmark;
• a row names an example file that does not exist under examples/.

So a new subcommand cannot merge without coverage, and coverage cannot be deleted without the matrix going red.

Totals

The gate prints the current row and command counts. Two things hold for every row:

• it names a benchmark and a runnable example;
• it is either regression (exercised end to end against the real CLI in a sandboxed HOME) or smoke.

A smoke row is one where the feature genuinely cannot be measured without changing the developer's machine, spending money on a model, or holding a terminal open. Its Coverage cell records the reason, and it still carries an integration smoke test asserting that dot <command> --help exits 0 and renders help for the right command without performing the command.

How to run the coverage this table names

# The regression rows (all of them):
./tests/framework/test_runner.sh --jobs auto

# One group:
bash tests/regression/test_feature_matrix_fleet_registry.sh

# The benchmarks (help cold-start for every command; --full adds the
# read-only invocations):
bash benches/dot_command_bench.sh --full --output bench.json

# The examples:
bash scripts/qa/validate-examples.sh

# This file's own drift gate:
bash scripts/qa/check-feature-matrix.sh

Reading a row

dispatcher: bin/dot

core.sh

diagnostics.sh

ai.sh

tools.sh / aliases.sh

lint.sh

appearance.sh

secrets.sh

security.sh

meta.sh / agent.sh

agents.sh

fleet.sh

registry.sh

patterns.sh

completion.sh

init.sh

manual.sh

system.sh

cross-cutting invariants

Rows recorded as unmeasurable

Each of these has a --help smoke test, so none is fully uncovered. They are listed together here so the reasons can be audited in one place rather than hunted through the table.

Findings this matrix produced

Building the coverage turned up defects in the CLI. Each was exercised by the row that found it, commented at that row, and reported rather than silently accommodated. Every one of them has since been fixed and pinned by a regression test; what remains below is the one entry that is working as designed.

Commands that write into the checkout

These commands resolve their write target through lib/dot/sdk.sh's resolve_source_dir, which probes the location of the sourced library BEFORE $CHEZMOI_SOURCE_DIR and $HOME. Running ./bin/dot from a checkout therefore writes into that checkout whatever HOME says, so a sandboxed HOME does not protect a working tree from them. The regression rows for these drive a throwaway copy of the repo instead, and then assert the checkout is still clean:

• dot fleet namespace set: defaults/.chezmoidata.toml
• dot fleet enforce set: defaults/dot_config/dotfiles/agent-profiles.json
• dot shell alias export with no --output (was dot aliases cheatsheet): docs/ALIASES_CHEATSHEET.md

dot theme set is NOT one of them, contrary to an earlier note here. scripts/theme/switch.sh and bin/dot-theme-sync resolve the data file from $CHEZMOI_SOURCE_DIR, then $HOME/.dotfiles, then $HOME/.local/share/chezmoi, and refuse with "Dotfiles source not found" when none exists — measured by pointing $HOME/.dotfiles at a synthetic tree while running the checkout's bin/dot: the synthetic tree was written and the checkout was untouched. It writes the checkout under this harness only because the harness points both CHEZMOI_SOURCE_DIR and $HOME/.dotfiles at it. It also drives the real OS appearance, which is why it stays a smoke row.

See also

• docs/manual/command-index.md — generated index of every routable command
• docs/manual/03-reference/01-dot-cli.md — the CLI reference
• docs/manual/03-reference/02-config-files.md — config file schemas
• docs/manual/03-reference/03-environment.md — environment variables
• CONTRIBUTING.md — the "Regression tests" trace-header convention