mayhem-cli 0.9.0__tar.gz → 0.9.1__tar.gz

{mayhem_cli-0.9.0 → mayhem_cli-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mayhem-cli
-Version: 0.9.0
+Version: 0.9.1
 Summary: General-purpose chaos engineering and resilience-testing framework: a chaos experiment orchestration engine.
 Author: Mayhem Engineering
 License: Proprietary
@@ -260,7 +260,9 @@ The full configuration reference is in
 
 The active CLI is workflow-oriented: `discover`, `prepare`, `experiment`, `run`, `inspect`, `recover`, and `extend`. Guided `init` and `doctor` are active, and all legacy root commands and aliases have been removed. Exit codes, machine-readable fields, and database migrations remain stable.
 
-See [`docs/product/cli-product-direction.md`](docs/product/cli-product-direction.md), [`docs/product/command-architecture.md`](docs/product/command-architecture.md), and [`docs/new-plan/README.md`](docs/new-plan/README.md).
+The command inventory, global options, and stable exit codes are generated from
+[`src/mayhem/cli/command_registry.py`](src/mayhem/cli/command_registry.py) and
+[`src/mayhem/cli/exit_codes.py`](src/mayhem/cli/exit_codes.py).
 
 Root options precede the command. Unique prefixes work at the root and in the workflow groups.
 
@@ -275,14 +277,12 @@ Root options precede the command. Unique prefixes work at the root and in the wo
 | `mayhem extend` | Inspect and extend faults, capabilities, dependencies, and providers. |
 | `mayhem game-day` | Plan and run controlled game-day sessions with named approvals. |
 | `mayhem bundle` | Verify a portable evidence bundle offline. |
+| `mayhem completion` | Print a bash/zsh/fish completion script. |
 | `mayhem campaign`, `mayhem commands`, `mayhem init`, `mayhem doctor`, `mayhem verify` | Manage campaigns, inspect the command map, onboard, diagnose, and verify evidence. |
 
-Use each command's current `--help` output for accepted arguments. The full
-sub-command inventory, root options, and stable exit codes are in
-[`docs/reference/cli.md`](docs/reference/cli.md); that inventory is compared
-against `src/mayhem/cli/command_registry.py` by
-`tests/unit/test_release_contract.py`, so a command that is not documented
-here fails the suite.
+Use each command's current `--help` output for accepted arguments. `mayhem commands show`
+prints the live command map, and `tests/unit/test_cli_exhaustive_matrix.py` fails
+when a registered command is missing from the active surface.
 
 ---
 
@@ -305,7 +305,7 @@ stored spec paths, `pause` and `resume` stop and continue a running campaign,
 and `archive` or `abort` sets the corresponding terminal status. The current
 command surface does not expose campaign scheduling, priority ordering, or
 policy/window editing. See the
-[command inventory](docs/reference/cli.md#command-inventory).
+`mayhem commands show`.
 
 ---
 
@@ -317,7 +317,7 @@ plan-only until explicitly executed, and every claim is recorded in evidence.
 
 | Area | What it gives you | Where |
 |------|-------------------|-------|
-| Explicit intent | Every mutating command needs an approval; `--dry-run` previews and returns before any engine exists. | `mayhem run --execute`, [`docs/reference/cli.md`](docs/reference/cli.md) |
+| Explicit intent | Every mutating command needs an approval; `--dry-run` previews and returns before any engine exists. | `mayhem run --execute`, `src/mayhem/cli/command_registry.py` |
 | Runtime context | Engine, target, and namespace resolved once and propagated; a target-type mismatch is refused **before** any lease or subprocess. | `mayhem doctor`, evidence `k8s_context` |
 | Capability truth | What each fault can actually do per engine, with a reason and a source of truth for every blocked row. | `mayhem discover capabilities [--explain] [--blocked]` |
 | Replay capsules | A versioned, digest-checked capsule per run; export and validate offline. | `mayhem inspect replay export\|validate RUN_ID` |
@@ -328,8 +328,8 @@ plan-only until explicitly executed, and every claim is recorded in evidence.
 | Campaign resume | Durable checkpoints; a verified experiment is never repeated without `--retry-verified`. | `mayhem campaign resume-plan` |
 | Residual impact | Before/after comparison proving the system came back; an unavailable source reads `unavailable`, never `clean`. | `mayhem inspect residual` |
 | Game days | Sessions with a freeze window, named approvers, and dual control for critical faults. | `mayhem game-day` |
-| Provider sandbox | Default grant is read-only; signed fault packs; unsigned is development-only. | [`docs/provider-sdk.md`](docs/provider-sdk.md) |
-| Observability | Read-only Prometheus/Loki connectors and local OpenTelemetry spans. | [`docs/observability.md`](docs/observability.md) |
+| Provider sandbox | Default grant is read-only; signed fault packs; unsigned is development-only. | `src/mayhem/providers/`(docs/provider-sdk.md) |
+| Observability | Read-only Prometheus/Loki connectors (bounded timeout, response-size cap, redacted errors) plus local OpenTelemetry spans. | `src/mayhem/observability/` |
 | Evidence bundles | Hash-chained, offline-verifiable bundles of a run's evidence. | `mayhem bundle verify PATH` |
 
 Two honesty rules are worth stating plainly, because they change what output
@@ -342,6 +342,23 @@ means:
   dashboard reports `live=false` for every row in this repository; `live=true`
   can only come from a recorded live run.
 
+### Shell completion
+
+`mayhem completion SHELL` prints a completion script to stdout. Nothing is
+installed and nothing is executed — you choose where it goes. Completion is
+dynamic, so the candidates always match the commands your installed version
+actually has:
+
+```bash
+mayhem completion bash >> ~/.bashrc
+mayhem completion zsh  > "${fpath[1]}/_mayhem"
+mayhem completion fish > ~/.config/fish/completions/mayhem.fish
+```
+
+`bash` needs **bash >= 4.4**; macOS ships 3.2, where dynamic completion is not
+available — use `zsh` or `fish` there, or install a newer bash. The generated
+bash script says so in its header.
+
 ```bash
 mayhem --version                     # installed version, or 0.0.0+source in a checkout
 mayhem discover capabilities --explain k8s.pod_kill
@@ -349,15 +366,20 @@ mayhem inspect replay export RUN_ID --out bundle/
 mayhem bundle verify bundle/
 ```
 
-### v0.9.0 documentation
+### v0.9.0 status
 
-| Document | Contents |
-|----------|----------|
-| [`docs/v0.9.0/01-vision-and-positioning.md`](docs/v0.9.0/01-vision-and-positioning.md) | What v0.9.0 is for |
-| [`docs/v0.9.0/04-architecture-and-decisions.md`](docs/v0.9.0/04-architecture-and-decisions.md) | ADRs and the decisions behind them |
-| [`docs/v0.9.0/06-core-implementation-plan.md`](docs/v0.9.0/06-core-implementation-plan.md) | Core tasks 1-10 and the core checkpoint |
-| [`docs/v0.9.0/07-expansion-implementation-plan.md`](docs/v0.9.0/07-expansion-implementation-plan.md) | Expansion tasks 11-20 and the expansion checkpoint |
-| [`docs/v0.9.0/08-release-readiness.md`](docs/v0.9.0/08-release-readiness.md) | Gate results and what is still excluded |
+The v0.9.0 planning package was scaffolding and has been removed; the behavior
+it described is what is implemented and documented above. What remains verified:
+
+| Gate | Result |
+|------|--------|
+| `pytest tests/unit tests/integration tests/e2e` | PASS |
+| Coverage of the v0.9.0 modules | 100% on 14 of 15; `domain/scenarios.py` 99% (3 unreachable defensive lines) |
+| `uv build --sdist --wheel` + `scripts/verify_release_artifacts.py` | PASS (9 checks) |
+| Wheel install, import, console scripts, `mayhem --version`, `python -m mayhem` | PASS |
+| GitHub Actions on `v0.9.0` | PASS — unit, integration, e2e, schema, ruff-fatal, package build, wheel smoke, artifact verification |
+| Repository-wide `ruff` / `mypy` / `lint-imports` | Pre-existing failures, advisory only (not release-gating) |
+| Live Kubernetes / remote-agent execution | Not claimed, and not enabled by default |
 
 ---
 
@@ -389,7 +411,7 @@ mayhem bundle verify bundle/
 
 The stable identifiers and numeric values are defined in
 [`src/mayhem/cli/exit_codes.py`](src/mayhem/cli/exit_codes.py) and documented in
-[`docs/reference/cli.md`](docs/reference/cli.md#exit-codes). The deterministic
+`src/mayhem/cli/exit_codes.py`. The deterministic
 documentation test rejects identifiers that are not declared in source.
 
 ---
@@ -423,9 +445,9 @@ is as small as possible:
 | [`docs/README.md`](docs/README.md) | Documentation authority, classifications, source-of-truth map, and Kubernetes status vocabulary. |
 | [`docs/drill-spec.md`](docs/drill-spec.md) | Drill DSL reference. |
 | [`docs/config.md`](docs/config.md) | Current layered configuration contract. |
-| [`docs/reference/cli.md`](docs/reference/cli.md) | Current commands, options, and stable exit codes. |
-| [`docs/reference/output-schema.md`](docs/reference/output-schema.md) | Versioned machine-output envelope and the v0.9.0 compatibility boundary. |
-| [`docs/reference/fault-catalog.md`](docs/reference/fault-catalog.md) | Checked Kubernetes fault catalog status snapshot and capability gates. |
+| `src/mayhem/cli/command_registry.py` | Current commands, options, and stable exit codes. |
+| `src/mayhem/schemas/output_v1.json`(docs/reference/output-schema.md) | Versioned machine-output envelope and the v0.9.0 compatibility boundary. |
+| [`docs/fault-catalog/`](docs/fault-catalog/README.md)(docs/reference/fault-catalog.md) | Checked Kubernetes fault catalog status snapshot and capability gates. |
 | [`docs/compensation.md`](docs/compensation.md) | Compensation lifecycle and verification contracts. |
 
 ---
@@ -451,8 +473,8 @@ is as small as possible:
 The [examples/k8s README](examples/k8s/README.md) and
 [documentation authority index](docs/README.md#kubernetes-status-vocabulary)
 explain the separate Kubernetes states. Historical discovery reports and the
-dated [grounding log](docs/grounding-log.md) are retained for traceability and
-must not be treated as live-cluster evidence.
+discovery reports are retained in git history for traceability and must not be
+treated as live-cluster evidence.
 
 ---
 

{mayhem_cli-0.9.0 → mayhem_cli-0.9.1}/README.md

@@ -245,7 +245,9 @@ The full configuration reference is in
 
 The active CLI is workflow-oriented: `discover`, `prepare`, `experiment`, `run`, `inspect`, `recover`, and `extend`. Guided `init` and `doctor` are active, and all legacy root commands and aliases have been removed. Exit codes, machine-readable fields, and database migrations remain stable.
 
-See [`docs/product/cli-product-direction.md`](docs/product/cli-product-direction.md), [`docs/product/command-architecture.md`](docs/product/command-architecture.md), and [`docs/new-plan/README.md`](docs/new-plan/README.md).
+The command inventory, global options, and stable exit codes are generated from
+[`src/mayhem/cli/command_registry.py`](src/mayhem/cli/command_registry.py) and
+[`src/mayhem/cli/exit_codes.py`](src/mayhem/cli/exit_codes.py).
 
 Root options precede the command. Unique prefixes work at the root and in the workflow groups.
 
@@ -260,14 +262,12 @@ Root options precede the command. Unique prefixes work at the root and in the wo
 | `mayhem extend` | Inspect and extend faults, capabilities, dependencies, and providers. |
 | `mayhem game-day` | Plan and run controlled game-day sessions with named approvals. |
 | `mayhem bundle` | Verify a portable evidence bundle offline. |
+| `mayhem completion` | Print a bash/zsh/fish completion script. |
 | `mayhem campaign`, `mayhem commands`, `mayhem init`, `mayhem doctor`, `mayhem verify` | Manage campaigns, inspect the command map, onboard, diagnose, and verify evidence. |
 
-Use each command's current `--help` output for accepted arguments. The full
-sub-command inventory, root options, and stable exit codes are in
-[`docs/reference/cli.md`](docs/reference/cli.md); that inventory is compared
-against `src/mayhem/cli/command_registry.py` by
-`tests/unit/test_release_contract.py`, so a command that is not documented
-here fails the suite.
+Use each command's current `--help` output for accepted arguments. `mayhem commands show`
+prints the live command map, and `tests/unit/test_cli_exhaustive_matrix.py` fails
+when a registered command is missing from the active surface.
 
 ---
 
@@ -290,7 +290,7 @@ stored spec paths, `pause` and `resume` stop and continue a running campaign,
 and `archive` or `abort` sets the corresponding terminal status. The current
 command surface does not expose campaign scheduling, priority ordering, or
 policy/window editing. See the
-[command inventory](docs/reference/cli.md#command-inventory).
+`mayhem commands show`.
 
 ---
 
@@ -302,7 +302,7 @@ plan-only until explicitly executed, and every claim is recorded in evidence.
 
 | Area | What it gives you | Where |
 |------|-------------------|-------|
-| Explicit intent | Every mutating command needs an approval; `--dry-run` previews and returns before any engine exists. | `mayhem run --execute`, [`docs/reference/cli.md`](docs/reference/cli.md) |
+| Explicit intent | Every mutating command needs an approval; `--dry-run` previews and returns before any engine exists. | `mayhem run --execute`, `src/mayhem/cli/command_registry.py` |
 | Runtime context | Engine, target, and namespace resolved once and propagated; a target-type mismatch is refused **before** any lease or subprocess. | `mayhem doctor`, evidence `k8s_context` |
 | Capability truth | What each fault can actually do per engine, with a reason and a source of truth for every blocked row. | `mayhem discover capabilities [--explain] [--blocked]` |
 | Replay capsules | A versioned, digest-checked capsule per run; export and validate offline. | `mayhem inspect replay export\|validate RUN_ID` |
@@ -313,8 +313,8 @@ plan-only until explicitly executed, and every claim is recorded in evidence.
 | Campaign resume | Durable checkpoints; a verified experiment is never repeated without `--retry-verified`. | `mayhem campaign resume-plan` |
 | Residual impact | Before/after comparison proving the system came back; an unavailable source reads `unavailable`, never `clean`. | `mayhem inspect residual` |
 | Game days | Sessions with a freeze window, named approvers, and dual control for critical faults. | `mayhem game-day` |
-| Provider sandbox | Default grant is read-only; signed fault packs; unsigned is development-only. | [`docs/provider-sdk.md`](docs/provider-sdk.md) |
-| Observability | Read-only Prometheus/Loki connectors and local OpenTelemetry spans. | [`docs/observability.md`](docs/observability.md) |
+| Provider sandbox | Default grant is read-only; signed fault packs; unsigned is development-only. | `src/mayhem/providers/`(docs/provider-sdk.md) |
+| Observability | Read-only Prometheus/Loki connectors (bounded timeout, response-size cap, redacted errors) plus local OpenTelemetry spans. | `src/mayhem/observability/` |
 | Evidence bundles | Hash-chained, offline-verifiable bundles of a run's evidence. | `mayhem bundle verify PATH` |
 
 Two honesty rules are worth stating plainly, because they change what output
@@ -327,6 +327,23 @@ means:
   dashboard reports `live=false` for every row in this repository; `live=true`
   can only come from a recorded live run.
 
+### Shell completion
+
+`mayhem completion SHELL` prints a completion script to stdout. Nothing is
+installed and nothing is executed — you choose where it goes. Completion is
+dynamic, so the candidates always match the commands your installed version
+actually has:
+
+```bash
+mayhem completion bash >> ~/.bashrc
+mayhem completion zsh  > "${fpath[1]}/_mayhem"
+mayhem completion fish > ~/.config/fish/completions/mayhem.fish
+```
+
+`bash` needs **bash >= 4.4**; macOS ships 3.2, where dynamic completion is not
+available — use `zsh` or `fish` there, or install a newer bash. The generated
+bash script says so in its header.
+
 ```bash
 mayhem --version                     # installed version, or 0.0.0+source in a checkout
 mayhem discover capabilities --explain k8s.pod_kill
@@ -334,15 +351,20 @@ mayhem inspect replay export RUN_ID --out bundle/
 mayhem bundle verify bundle/
 ```
 
-### v0.9.0 documentation
+### v0.9.0 status
 
-| Document | Contents |
-|----------|----------|
-| [`docs/v0.9.0/01-vision-and-positioning.md`](docs/v0.9.0/01-vision-and-positioning.md) | What v0.9.0 is for |
-| [`docs/v0.9.0/04-architecture-and-decisions.md`](docs/v0.9.0/04-architecture-and-decisions.md) | ADRs and the decisions behind them |
-| [`docs/v0.9.0/06-core-implementation-plan.md`](docs/v0.9.0/06-core-implementation-plan.md) | Core tasks 1-10 and the core checkpoint |
-| [`docs/v0.9.0/07-expansion-implementation-plan.md`](docs/v0.9.0/07-expansion-implementation-plan.md) | Expansion tasks 11-20 and the expansion checkpoint |
-| [`docs/v0.9.0/08-release-readiness.md`](docs/v0.9.0/08-release-readiness.md) | Gate results and what is still excluded |
+The v0.9.0 planning package was scaffolding and has been removed; the behavior
+it described is what is implemented and documented above. What remains verified:
+
+| Gate | Result |
+|------|--------|
+| `pytest tests/unit tests/integration tests/e2e` | PASS |
+| Coverage of the v0.9.0 modules | 100% on 14 of 15; `domain/scenarios.py` 99% (3 unreachable defensive lines) |
+| `uv build --sdist --wheel` + `scripts/verify_release_artifacts.py` | PASS (9 checks) |
+| Wheel install, import, console scripts, `mayhem --version`, `python -m mayhem` | PASS |
+| GitHub Actions on `v0.9.0` | PASS — unit, integration, e2e, schema, ruff-fatal, package build, wheel smoke, artifact verification |
+| Repository-wide `ruff` / `mypy` / `lint-imports` | Pre-existing failures, advisory only (not release-gating) |
+| Live Kubernetes / remote-agent execution | Not claimed, and not enabled by default |
 
 ---
 
@@ -374,7 +396,7 @@ mayhem bundle verify bundle/
 
 The stable identifiers and numeric values are defined in
 [`src/mayhem/cli/exit_codes.py`](src/mayhem/cli/exit_codes.py) and documented in
-[`docs/reference/cli.md`](docs/reference/cli.md#exit-codes). The deterministic
+`src/mayhem/cli/exit_codes.py`. The deterministic
 documentation test rejects identifiers that are not declared in source.
 
 ---
@@ -408,9 +430,9 @@ is as small as possible:
 | [`docs/README.md`](docs/README.md) | Documentation authority, classifications, source-of-truth map, and Kubernetes status vocabulary. |
 | [`docs/drill-spec.md`](docs/drill-spec.md) | Drill DSL reference. |
 | [`docs/config.md`](docs/config.md) | Current layered configuration contract. |
-| [`docs/reference/cli.md`](docs/reference/cli.md) | Current commands, options, and stable exit codes. |
-| [`docs/reference/output-schema.md`](docs/reference/output-schema.md) | Versioned machine-output envelope and the v0.9.0 compatibility boundary. |
-| [`docs/reference/fault-catalog.md`](docs/reference/fault-catalog.md) | Checked Kubernetes fault catalog status snapshot and capability gates. |
+| `src/mayhem/cli/command_registry.py` | Current commands, options, and stable exit codes. |
+| `src/mayhem/schemas/output_v1.json`(docs/reference/output-schema.md) | Versioned machine-output envelope and the v0.9.0 compatibility boundary. |
+| [`docs/fault-catalog/`](docs/fault-catalog/README.md)(docs/reference/fault-catalog.md) | Checked Kubernetes fault catalog status snapshot and capability gates. |
 | [`docs/compensation.md`](docs/compensation.md) | Compensation lifecycle and verification contracts. |
 
 ---
@@ -436,8 +458,8 @@ is as small as possible:
 The [examples/k8s README](examples/k8s/README.md) and
 [documentation authority index](docs/README.md#kubernetes-status-vocabulary)
 explain the separate Kubernetes states. Historical discovery reports and the
-dated [grounding log](docs/grounding-log.md) are retained for traceability and
-must not be treated as live-cluster evidence.
+discovery reports are retained in git history for traceability and must not be
+treated as live-cluster evidence.
 
 ---
 

mayhem_cli-0.9.1/docs/README.md

@@ -0,0 +1,59 @@
+# Documentation authority
+
+This page is the authority index for Mayhem documentation. It classifies every
+Markdown document tracked in the repository and records which source files
+control current behavior. When prose disagrees with one of those sources, the
+source is current and the prose needs correction.
+
+## Source authority
+
+| Contract | Executable authority |
+|----------|----------------------|
+| Layered configuration | [`src/mayhem/config.py`](../src/mayhem/config.py) |
+| CLI commands and global options | [`src/mayhem/cli/app.py`](../src/mayhem/cli/app.py) and [`src/mayhem/cli/`](../src/mayhem/cli/) |
+| Stable exit codes | [`src/mayhem/cli/exit_codes.py`](../src/mayhem/cli/exit_codes.py) |
+| Command inventory | [`src/mayhem/cli/command_registry.py`](../src/mayhem/cli/command_registry.py) |
+| Drill schema | [`src/mayhem/domain/experiments.py`](../src/mayhem/domain/experiments.py) and [`src/mayhem/spec.py`](../src/mayhem/spec.py) |
+| Execution intent and approval | [`src/mayhem/domain/execution_intent.py`](../src/mayhem/domain/execution_intent.py) |
+| Typed admission | [`src/mayhem/domain/admission.py`](../src/mayhem/domain/admission.py) |
+| Capability truth | [`src/mayhem/domain/capability_status.py`](../src/mayhem/domain/capability_status.py) and [`src/mayhem/infra/catalog_report.py`](../src/mayhem/infra/catalog_report.py) |
+| Replay capsules | [`src/mayhem/domain/replay.py`](../src/mayhem/domain/replay.py) |
+| Evidence and redaction | [`src/mayhem/domain/evidence.py`](../src/mayhem/domain/evidence.py) and [`src/mayhem/domain/redaction.py`](../src/mayhem/domain/redaction.py) |
+| Evidence bundles | [`src/mayhem/domain/evidence_bundle.py`](../src/mayhem/domain/evidence_bundle.py) |
+| Provider sandbox and packs | [`src/mayhem/providers/permissions.py`](../src/mayhem/providers/permissions.py) and [`src/mayhem/providers/pack.py`](../src/mayhem/providers/pack.py) |
+| Fault catalog and support declarations | [`src/mayhem/domain/catalog.py`](../src/mayhem/domain/catalog.py) and [`src/mayhem/controller/k8s_runtime.py`](../src/mayhem/controller/k8s_runtime.py) |
+| Kubernetes planning and execution seams | [`src/mayhem/controller/planner.py`](../src/mayhem/controller/planner.py), [`src/mayhem/agents/k8s_resolve.py`](../src/mayhem/agents/k8s_resolve.py), and [`src/mayhem/agents/executors.py`](../src/mayhem/agents/executors.py) |
+
+## Document inventory
+
+| Document | Classification | Current-use rule |
+|----------|----------------|------------------|
+| [`../README.md`](../README.md) | user guide | Start here: quickstart, CLI surface, safety model, status, and what v0.9.0 added. |
+| [`../CHANGELOG.md`](../CHANGELOG.md) | historical audit | Release history up to the last generated tag; it does not describe uncommitted behavior. |
+| [`drill-spec.md`](drill-spec.md) | current reference | Drill DSL reference, including the v0.9.0 `slo:` block and the scenario document format. |
+| [`config.md`](config.md) | current reference | Authoritative checked-in summary of `src/mayhem/config.py`. |
+| [`compensation.md`](compensation.md) | current reference | Compensation lifecycle reference; executor behavior remains authoritative in source and tests. |
+| [`fault-catalog/README.md`](fault-catalog/README.md) | current reference | Fault catalog and capability snapshot. |
+| [`fault-catalog/reliability-matrix.md`](fault-catalog/reliability-matrix.md) | current reference | Per-fault reliability and compensation matrix. |
+
+Planning packages, dated discovery reports, and per-release readiness notes were
+removed once their content was implemented and folded into the references above.
+They remain in git history if a historical record is ever needed.
+
+## Kubernetes status vocabulary
+
+These states are intentionally separate. Possessing one does not imply the
+next.
+
+| State | Current meaning | Source evidence |
+|-------|-----------------|-----------------|
+| Kubernetes manifest planning | A multi-document Kubernetes manifest can produce an offline blueprint graph. Workload pods are placeholders, not live pod selections. | [`k8s_manifest.py`](../src/mayhem/topology/providers/k8s_manifest.py) |
+| Planner support | `targets:` drills normalize Kubernetes scopes, preserve logical target identity, and compile frozen plans. Plan-time resolution is best-effort for manifest workloads. | [`planner.py`](../src/mayhem/controller/planner.py) |
+| Executor support | Kubernetes-routed fault families have dedicated dispatch registers, undo contracts, and executor classes. A registered executor does not prove that a cluster is reachable or a required capability is available. | [`executors.py`](../src/mayhem/agents/executors.py) and [`k8s_runtime.py`](../src/mayhem/controller/k8s_runtime.py) |
+| Live resolution | A resolver seam can select eligible live Running pods or nodes and record resolved-target evidence when a usable client exists. No checked-in document should claim that a particular external cluster passed validation. | [`k8s_resolve.py`](../src/mayhem/agents/k8s_resolve.py) |
+| Legacy adapter availability | `KubernetesAdapter` remains a registered compatibility seam with `is_available() == False`; do not use its advertised capabilities as proof that the separate resolver/executor path is available. | [`k8s_adapter.py`](../src/mayhem/domain/k8s_adapter.py) |
+| Catalog-only fault | A fault can be defined, typed, and planned without being in `k8s_available_faults()`. `k8s.image_pull_slow` is the current catalog-only Kubernetes example and refuses before mutation. | [`catalog.py`](../src/mayhem/domain/catalog.py) and [`k8s_runtime.py`](../src/mayhem/controller/k8s_runtime.py) |
+
+The Kubernetes unit suite exercises these seams with fake clients and
+in-memory data. Documentation does not promote those tests into a claim of live
+cluster acceptance.

{mayhem_cli-0.9.0 → mayhem_cli-0.9.1}/docs/config.md

@@ -123,7 +123,7 @@ Forbidden credential keys in a target profile: `password`, `secret`, `token`,
 `credentials`, `api_key`, `apikey`. A wider set is redacted when configuration
 is rendered — by `config show`, by `config explain`, and by evidence alike — so
 free-form blocks such as a profile's `observability:` are filtered by one
-policy; see [`policy-and-break-glass.md`](policy-and-break-glass.md).
+policy; see `src/mayhem/controller/safety.py`.
 
 A drill document's own top-level `targets:` block is *not* a target-profile
 block. It declares the spec's logical targets
@@ -311,4 +311,4 @@ Current root CLI controls relate to layering and execution as follows:
 | `--skip-gate` | Controls the impact gate; it is not a configuration field. |
 | `--podman` / `--kubernetes` | Select CLI engine state; they do not rewrite `runtime`. |
 
-Use [`reference/cli.md`](reference/cli.md) for the executable command surface.
+Use `src/mayhem/cli/command_registry.py` for the executable command surface.

{mayhem_cli-0.9.0 → mayhem_cli-0.9.1}/docs/drill-spec.md

@@ -27,7 +27,7 @@ mayhem maniac   examples/testCase/mayhem.yaml --compose examples/testCase/docker
 
 `run` and `maniac` inject faults, so both need the explicit `--execute`
 approval; without it they stop at a preview and no lease is ever created. See
-[CLI reference](reference/cli.md#execution-intent).
+[CLI reference](../README.md#whats-new-in-v090).
 
 The positional spec path may be omitted when the global ``--config`` flag
 names the drill spec itself — useful from a directory without a spec file:

{mayhem_cli-0.9.0 → mayhem_cli-0.9.1}/docs/fault-catalog/README.md

@@ -5,7 +5,7 @@ The active CLI exposes this catalog through `mayhem discover faults`,
 runtime-free reliability contract, coverage report, maturity policy, recommendations,
 and Plan 08 family status are documented in [`reliability-matrix.md`](reliability-matrix.md).
 
-The current Kubernetes catalog snapshot is maintained at [`../reference/fault-catalog.md`](../reference/fault-catalog.md). Definitions are sourced from `src/mayhem/domain/catalog.py`; runtime status is sourced from `src/mayhem/controller/k8s_runtime.py`.
+The current Kubernetes catalog snapshot is maintained at [`reliability-matrix.md`](reliability-matrix.md). Definitions are sourced from `src/mayhem/domain/catalog.py`; runtime status is sourced from `src/mayhem/controller/k8s_runtime.py`.
 
 ## Container and Kubernetes expansion
 

{mayhem_cli-0.9.0 → mayhem_cli-0.9.1}/src/mayhem/cli/command_registry.py

@@ -15,6 +15,7 @@ class CommandSpec:
 COMMAND_HELP: dict[str, str] = {
     "campaign": "Create, inspect, and run chaos campaigns.",
     "commands": "Show the command migration map.",
+    "completion": "Generate a shell completion script for this Mayhem build.",
     "discover": "Discover targets, engines, and capabilities.",
     "doctor": "Check configuration, database, engines, and permissions.",
     "experiment": "Inspect and validate authored experiment specs.",
@@ -35,6 +36,7 @@ COMMAND_HELP: dict[str, str] = {
 COMMAND_SPECS: tuple[CommandSpec, ...] = (
     CommandSpec("campaign", "run", help_group="experiments", mutating=True),
     CommandSpec("commands", "inspect", help_group="inspect"),
+    CommandSpec("completion", "inspect", help_group="inspect"),
     CommandSpec("discover", "discover", help_group="discovery"),
     CommandSpec("doctor", "inspect", help_group="inspect"),
     CommandSpec("experiment", "experiment", help_group="experiments"),
@@ -55,6 +57,7 @@ COMMAND_SPECS: tuple[CommandSpec, ...] = (
 def register_commands(app: Any) -> None:
     from mayhem.cli.campaign import campaign
     from mayhem.cli.commands import commands
+    from mayhem.cli.completion import completion
     from mayhem.cli.doctor import doctor_cmd
     from mayhem.cli.experiment import experiment
     from mayhem.cli.game_day import game_day
@@ -66,6 +69,7 @@ def register_commands(app: Any) -> None:
     command_map = {
         "campaign": campaign,
         "commands": commands,
+        "completion": completion,
         "discover": discover,
         "doctor": doctor_cmd,
         "experiment": experiment,

mayhem_cli-0.9.1/src/mayhem/cli/completion.py

@@ -0,0 +1,76 @@
+"""``mayhem completion SHELL`` — print a shell completion script.
+
+This prints Click's own completion script for the requested shell, verbatim from
+:meth:`click.shell_completion.ShellComplete.source`. That is deliberate:
+hand-rolled wrappers are how you end up binding a function name that does not
+exist (``compdef _mayhem`` instead of ``compdef _mayhem_completion``), which
+parses fine under ``zsh -n`` and then silently completes nothing.
+
+The scripts are self-contained, so you decide where they go:
+
+    mayhem completion bash >> ~/.bashrc
+    mayhem completion zsh  > "${fpath[1]}/_mayhem"
+    mayhem completion fish > ~/.config/fish/completions/mayhem.fish
+
+Completion is dynamic: the shell asks the installed ``mayhem`` for candidates,
+so the list always matches the commands that build actually has.
+"""
+
+from __future__ import annotations
+
+import click
+from click.shell_completion import BashComplete, FishComplete, ShellComplete, ZshComplete
+
+#: The executable users type. Keep in sync with ``[project.scripts]``.
+PROG_NAME = "mayhem"
+
+SUPPORTED_SHELLS: tuple[str, ...] = ("bash", "zsh", "fish")
+
+#: ``complete_var`` Click derives from the program name: ``_<PROG>_COMPLETE``.
+COMPLETE_VAR = f"_{PROG_NAME.upper()}_COMPLETE"
+
+_COMPLETERS = {
+    "bash": BashComplete,
+    "zsh": ZshComplete,
+    "fish": FishComplete,
+}
+
+
+def _app() -> click.Command:
+    # Imported lazily: app -> command_registry -> completion, so a module-level
+    # import here would be circular.
+    from mayhem.cli.app import app
+
+    return app
+
+
+def _source(completer: ShellComplete) -> str:
+    """Render the script, tolerating a host bash too old to run it.
+
+    ``BashComplete.source`` refuses to emit when the *local* bash is < 4.4
+    (macOS ships 3.2). The script itself is version-agnostic — it is the
+    running bash that must be new enough — so a warning plus the script is more
+    useful than a refusal.
+    """
+    try:
+        return completer.source()
+    except RuntimeError as exc:
+        click.echo(f"warning: {exc}", err=True)
+        return ShellComplete.source(completer)
+
+
+@click.command("completion")
+@click.argument(
+    "shell",
+    type=click.Choice(SUPPORTED_SHELLS, case_sensitive=False),
+    required=False,
+    default="bash",
+)
+def completion(shell: str) -> None:
+    """Print the completion script for SHELL (bash, zsh, or fish).
+
+    Writes to stdout only: nothing is installed, no file is touched, and
+    nothing is executed.
+    """
+    completer = _COMPLETERS[shell.lower()](_app(), {}, PROG_NAME, COMPLETE_VAR)
+    click.echo(_source(completer), nl=False)

{mayhem_cli-0.9.0 → mayhem_cli-0.9.1}/tests/unit/test_cli_active_surface.py

@@ -10,6 +10,7 @@ ACTIVE_COMMANDS = {
     "bundle",
     "campaign",
     "commands",
+    "completion",
     "discover",
     "doctor",
     "experiment",