@sebastienrousseau/dotfiles 0.2.508 → 0.2.510

package/docs/manual/index.md

@@ -8,7 +8,7 @@ render_with_liquid: false
 
 A trusted agent workstation baseline for macOS, Linux, and WSL. Chezmoi handles templating and platform differences; the `dot` CLI coordinates lifecycle operations on top.
 
-This manual is generated from the Markdown sources in [`docs/manual/`](https://github.com/sebastienrousseau/dotfiles/tree/master/docs/manual) and published in nine formats per release. The HTML edition you are reading is the canonical online version.
+This manual is generated from the Markdown sources in [`docs/manual/`](https://github.com/sebastienrousseau/dotfiles/tree/main/docs/manual) and published in nine formats per release. The HTML edition you are reading is the canonical online version.
 
 ## Read it your way
 

package/docs/operations/ARCHITECTURE_ROADMAP.md

@@ -0,0 +1,145 @@
+---
+title: "Architecture & Roadmap — cross-shell consistency, performance, decoupling"
+date: 2026-07-01
+status: living document
+---
+
+# Architecture & Roadmap
+
+This document captures a deep-dive across four fronts — cross-shell
+consistency, real startup performance, the 2026 competitive/research
+landscape, and a plan to decouple optional subsystems (`dot ai`, MCP, LSP)
+into companion repos around a stable core. It is the source of truth for
+the multi-phase program tracked below.
+
+> Honesty policy: every performance number here is **measured** with
+> `hyperfine` (warmed up), reproducible with the harness in
+> `tests/performance/bench.sh` (interactive sessions, all installed shells)
+> and `dot benchmark`. Estimates are labelled as such. The
+> built-in `dot doctor` perf readout historically **understated** real
+> startup because it timed a narrower slice — Phase 0 reconciles that.
+
+## 1. Measured performance baseline (2026-07-01, Apple Silicon)
+
+Method: `hyperfine -N --warmup 5` on the deployed config; `exit`-on-launch.
+
+| Shell   | Startup (mean) | rc cost over ~7ms spawn | vs <30ms target |
+|---------|----------------|-------------------------|-----------------|
+| nushell | 24.8 ms        | —                       | meets           |
+| bash    | 51.1 ms        | +43.6 ms                | 1.7× over       |
+| zsh     | 66.3 ms        | +59.6 ms                | 2.2× over       |
+| fish    | 128.8 ms       | bash-bridge tax         | 4.3× over       |
+
+Baselines (pure process spawn, no rc): `zsh -fc exit` 6.7 ms,
+`bash --norc` 7.5 ms.
+
+Cost attribution (uncached tool-init subprocess cost, what `_cached_eval`
+caches away): `mise activate` 17.7 ms, `atuin init` 7.1 ms,
+`starship init` 4.0 ms, `zoxide init` 2.4 ms. `_cached_eval` **is**
+working (cache files fresh; `zcompdump` is `zcompile`d), which is why zsh
+is 66 ms and not ~97 ms.
+
+**<30ms verdict (honest):** not reachable for the *full eager stack*
+(mise + starship + atuin + zoxide + fzf + zinit + ~97 alias files + ~53
+functions + compinit) on zsh/bash without tradeoffs. It **is** reachable
+as a tunable "fast profile" + first-prompt deferral. nushell already
+meets it; fish (bash-bridge) is the worst and the biggest opportunity.
+
+## 2. Cross-shell consistency
+
+- bash/zsh are native + single-source; **fish and nushell are bash
+  *bridges*** — they filter aliases and wrap functions via `bash -c`
+  subshells, adding a runtime bash dependency and silent parity loss.
+- Parity gap: bash/zsh ~53 functions; fish 27 native; nushell 0 native;
+  ~26 functions have no native impl; behaviour drifts (e.g. `goto` loses
+  directory grouping in fish/nu).
+- Duplication: eza-detection logic in bash + 7 fish files + nu wrappers;
+  `_cached_eval` reimplemented four times.
+- Direction: a **manifest-driven single source of truth** (one
+  alias/function spec → per-shell generators). This also removes the
+  class of parse-time collision that produced the zsh alias-shim bug.
+
+## 3. Decoupling architecture
+
+```
+                     dotfiles (CORE)
+   dot CLI · lib/dot/ui.sh · utils.sh · chezmoi base · plugin API
+        |               |                 |             |
+   dotfiles-ai     dotfiles-mcp      dotfiles-lsp    (future)
+   dot ai,          registry,         dot/alias/
+   cockpit,         policy,           chezmoi-template
+   gateway          mcp-doctor        completions
+```
+
+Readiness (from the coupling audit):
+
+| Subsystem | Coupling | Effort | Notes |
+|-----------|----------|--------|-------|
+| MCP | low (declarative JSON + one `cmd_mcp`) | low | isolated by design |
+| LSP | none (one nvim plugin file) | trivial | already a lazy.nvim plugin |
+| `dot ai` | high (ui.sh, utils.sh, dispatcher, chezmoi hooks) | high | needs the two contracts below |
+
+Two foundational contracts must exist before AI can move cleanly:
+
+1. **Extract `lib/dot/ui.sh` into a versioned shared lib** — AI *and* MCP
+   depend on it; without this, decoupling means duplication.
+2. **A `dot` plugin/extension API** — manifest-registered subcommands so
+   companion repos add `dot ai` / `dot mcp` without forking the
+   dispatcher.
+
+## 4. 2026 landscape — gaps worth adopting (highest value first)
+
+- **`dotfiles-mcp` with a secrets-redaction + allowlist policy layer** — a
+  genuine gap no existing dotfiles-MCP fills; reuses the gitleaks / Atuin
+  `history_filter` posture. Expose introspection via MCP **Resources**,
+  actions via **Tools**.
+- **`dotfiles-lsp`** = `dot` subcommand completions + alias awareness +
+  **chezmoi-template-data-aware** completions → a novel *combination*
+  (weekend-scale MVP using just-lsp / tcl-lsp patterns).
+- Password-manager templating (1Password/Bitwarden), SOPS for shared
+  secrets, **Bats** tests (reviewer lingua franca), devcontainer/Codespaces
+  fast install path.
+
+Context: chezmoi has won the dotfiles category; mise is baseline; Starship
+has overtaken Powerlevel10k (maintenance-only); MCP spec 2025-11-25 is
+under the Linux Foundation and safe to build on.
+
+## 5. Staged roadmap
+
+Each phase ships as its own reviewed PR with before/after benchmarks.
+
+| Phase | Work | Risk | Target payoff |
+|-------|------|------|---------------|
+| **0** | Honest benchmark harness in-repo; make `dot doctor` report real numbers | low | truth in metrics |
+| **1** | Perf quick-wins audit (deferral, compinit, zcompile, mise ordering) | low | verify + record baseline |
+| **2** | Extract `lib/dot/ui.sh` → versioned shared lib | med | unblocks decoupling |
+| **3** | `dot` plugin API + carve out `dotfiles-mcp` (lowest-risk repo) | med | proves the model |
+| **4** | Cross-shell manifest (single source → per-shell generators); de-bash-bridge fish | high | consistency + fish speed |
+| **5** | `dotfiles-ai` as a plugin repo | high | the decoupling goal |
+| **6** | `dotfiles-lsp` MVP | low | differentiation |
+| **7** | Docs + `examples/` + published honest benchmarks | med | completeness |
+
+### Status
+
+- **Phase 0 — done** (`feat/v0.2.509`): `tests/performance/bench.sh` now times
+  every shell *interactively* (fish was measured non-interactively, faking
+  ~12ms vs the real ~118ms) and includes nushell; `dot doctor` reports the
+  real medians.
+- **Phase 1 — done (audit)** (`feat/v0.2.509`): the documented quick-wins are
+  **already implemented** in the deployed config, verified:
+  - `compinit` deferred to first prompt, `-C` + daily-audit cache
+    (`~/.config/zsh/rc.d/30-options.zsh`).
+  - Eagerly-sourced hub files are `zcompile`d (`.zwc` present).
+  - Plugins turbo-deferred (`zinit ice wait lucid`), fzf backgrounded, and
+    mise/atuin/starship/zoxide inits deferred to post-prompt hydration and
+    cached via `_cached_eval`.
+  - `mise activate` ordering is a non-issue here: zsh uses `add-zsh-hook`
+    (appends, no overwrite) and bash manages `PROMPT_COMMAND` explicitly.
+  - Net: `zsh -ic exit` (which runs before the prompt, so it excludes the
+    deferred inits) is ~66ms of *eager* rc — dominated by sourcing the large
+    aggregated alias/function hubs. No safe further quick-win remains.
+  - **Consequence:** sub-30ms is not reachable by tuning; it needs Phase 4
+    (manifest → cut the eager alias/function volume) or a lean profile.
+    fish (~118ms) is the biggest single opportunity (bash-bridge), also
+    Phase 4.
+- Phases 2–7 — planned; sequencing subject to review.

package/docs/operations/CI_CADENCE.md

@@ -102,6 +102,6 @@ When adding a new workflow:
 
 ## References
 
-- [`nightly.yml`](../../.github/workflows/nightly.yml) — the workflow whose cadence flip triggered this page.
-- [`security-enhanced.yml`](../../.github/workflows/security-enhanced.yml) — earlier daily→weekly reduction.
+- [`nightly.yml`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/nightly.yml) — the workflow whose cadence flip triggered this page.
+- [`security-enhanced.yml`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/security-enhanced.yml) — earlier daily→weekly reduction.
 - Issue [#861](https://github.com/sebastienrousseau/dotfiles/issues/861).

package/docs/operations/COMPLETIONS.md

@@ -116,8 +116,8 @@ their lifecycle.
 
 ## References
 
-- [`dot_config/zsh/rc.d/30-options.zsh.tmpl`](../../defaults/dot_config/zsh/rc.d/30-options.zsh.tmpl) — the deferred-compinit logic.
-- [`run_onchange_after_zcompile-completions.sh.tmpl`](../../defaults/run_onchange_after_zcompile-completions.sh.tmpl) — the apply-time precompile hook.
+- [`dot_config/zsh/rc.d/30-options.zsh.tmpl`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/zsh/rc.d/30-options.zsh.tmpl) — the deferred-compinit logic.
+- [`run_onchange_after_zcompile-completions.sh.tmpl`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/run_onchange_after_zcompile-completions.sh.tmpl) — the apply-time precompile hook.
 - [`zsh` completion docs](https://zsh.sourceforge.io/Doc/Release/Completion-System.html).
 - ADR-002 (Shell Performance Optimization).
 - Issue [#864](https://github.com/sebastienrousseau/dotfiles/issues/864).

package/docs/operations/COVERAGE.md

@@ -43,7 +43,7 @@ matches and emits standard `lcov.info` that Codecov ingests natively.
 
 | Surface | What runs |
 |---|---|
-| **PR + push to master** | `.github/workflows/coverage.yml` → `Coverage / kcov` job → uploads lcov.info to Codecov and fails the build below `MIN_COVERAGE_PCT` (currently `0`, ratcheted up each slice). |
+| **PR + push to main** | `.github/workflows/coverage.yml` → `Coverage / kcov` job → uploads lcov.info to Codecov and fails the build below `MIN_COVERAGE_PCT` (currently `0`, ratcheted up each slice). |
 | **Local dev** | `bash tools/ci/run-coverage.sh` — works on Linux + macOS (xtrace is a bash primitive, no platform tools needed). |
 | **macOS dev** | Supported. xtrace-based instrumentation runs on macOS bash 3.2+ and Homebrew bash 5.x. |
 
@@ -117,7 +117,7 @@ heatmap.
 When the `Coverage / kcov` PR check fails:
 
 1. Pull the workflow's `coverage-lcov` artifact (30-day retention).
-2. Compare against the previous master run by downloading its
+2. Compare against the previous main run by downloading its
    `coverage-lcov` artifact too.
 3. Identify the file(s) where the line-coverage dropped.
 4. Either:
@@ -176,7 +176,7 @@ Adjust via the env vars at the top of `run-coverage.sh`.
 ## References
 
 - [Bash xtrace + PS4 + BASH_ENV docs](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html).
-- [`tools/ci/run-coverage.sh`](../../tools/ci/run-coverage.sh).
-- [`.github/workflows/coverage.yml`](../../.github/workflows/coverage.yml).
+- [`tools/ci/run-coverage.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/tools/ci/run-coverage.sh).
+- [`.github/workflows/coverage.yml`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/coverage.yml).
 - Issue [#856](https://github.com/sebastienrousseau/dotfiles/issues/856) (closed) /
   [#883](https://github.com/sebastienrousseau/dotfiles/issues/883) (coverage roadmap).

package/docs/operations/DRIFT.md

@@ -47,7 +47,7 @@ Exit code: `0` if every class is clean; `1` if any drift is found;
 ## How the nightly check works
 
 `.github/workflows/drift-detection.yml` runs `dot drift --json` against
-a fresh checkout of `master` every day at 04:00 UTC. If `total != 0`
+a fresh checkout of `main` every day at 04:00 UTC. If `total != 0`
 it opens (or updates) a tracking issue labelled
 `type:chore + priority:medium` with the JSON summary, full
 `chezmoi diff`, and `chezmoi status` attached as a workflow artifact.

package/docs/operations/MAINTENANCE.md

@@ -17,11 +17,11 @@ This runbook captures recovery and release maintenance operations for this repos
 
 **Procedure:**
 
-1. Create a backup ref for current `master`.
+1. Create a backup ref for current `main`.
 2. Build a rewritten signed baseline commit from the current tree.
 3. Push the rewritten branch to remote.
-4. Temporarily allow force-push on `master` protections/rulesets.
-5. Force-update `master` to the rewritten signed baseline.
+4. Temporarily allow force-push on `main` protections/rulesets.
+5. Force-update `main` to the rewritten signed baseline.
 6. Disable force-push again immediately.
 7. Re-run CI and verify required checks are green.
 8. Repoint the release tag/target as needed.
@@ -30,7 +30,7 @@ This runbook captures recovery and release maintenance operations for this repos
 
 ```bash
 git verify-commit HEAD
-gh run list --workflow ci.yml --branch master --limit 1
+gh run list --workflow ci.yml --branch main --limit 1
 gh release view v0.2.501 --json tagName,targetCommitish,url
 ```
 
@@ -38,10 +38,10 @@ gh release view v0.2.501 --json tagName,targetCommitish,url
 
 For every release update:
 
-1. `master` branch is clean and synced.
+1. `main` branch is clean and synced.
 2. CI is green on the release commit.
 3. Annotated release tag points to the intended commit.
-4. GitHub release target is correct (`master` or explicit commit).
+4. GitHub release target is correct (`main` or explicit commit).
 5. Branch protections/rulesets are restored to strict state.
 6. Local apply has completed:
 

package/docs/operations/PERFORMANCE.md

@@ -20,7 +20,7 @@ lifecycle, and the regression-alert pipeline. Managed under
 
 `dot perf` measures every installed shell and flags any whose mean
 exceeds its target. The numbers come from
-[`scripts/diagnostics/perf.sh`](../../scripts/diagnostics/perf.sh) —
+[`scripts/diagnostics/perf.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/scripts/diagnostics/perf.sh) —
 warm-up + 3 runs by default.
 
 ## The baseline
@@ -100,7 +100,7 @@ spiking from 5ms steady-state to 200ms once).
 
 ## CI workflow
 
-[`.github/workflows/perf-baseline.yml`](../../.github/workflows/perf-baseline.yml)
+[`.github/workflows/perf-baseline.yml`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/perf-baseline.yml)
 runs weekly on Sunday at 03:00 UTC on `ubuntu-latest`. It:
 
 1. Restores the previous week's baseline from a workflow artifact.
@@ -116,7 +116,7 @@ each developer's box and aren't synced.
 ## Adjusting the budget
 
 Per-shell targets live in
-[`scripts/diagnostics/perf.sh`](../../scripts/diagnostics/perf.sh)
+[`scripts/diagnostics/perf.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/scripts/diagnostics/perf.sh)
 under `shell_target_for()`. Bumping a target should always come with:
 
 - A commit-message rationale explaining why slower is acceptable
@@ -126,8 +126,8 @@ under `shell_target_for()`. Bumping a target should always come with:
 
 ## References
 
-- [`scripts/diagnostics/perf.sh`](../../scripts/diagnostics/perf.sh)
-- [`tests/unit/diagnostics/test_perf_percentiles.sh`](../../tests/unit/diagnostics/test_perf_percentiles.sh) — percentile math contract
-- [`.github/workflows/perf-baseline.yml`](../../.github/workflows/perf-baseline.yml)
+- [`scripts/diagnostics/perf.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/scripts/diagnostics/perf.sh)
+- [`tests/unit/diagnostics/test_perf_percentiles.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/tests/unit/diagnostics/test_perf_percentiles.sh) — percentile math contract
+- [`.github/workflows/perf-baseline.yml`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/perf-baseline.yml)
 - ADR-002 (Shell Performance Optimization)
 - Issue [#863](https://github.com/sebastienrousseau/dotfiles/issues/863)

package/docs/operations/RELIABILITY.md

@@ -71,7 +71,7 @@ name: Reliability Gate
 on:
   pull_request:
   push:
-    branches: [master]
+    branches: [main]
   workflow_dispatch:
 
 jobs:

package/docs/operations/ROADMAP_V0_2_503.md

@@ -78,7 +78,7 @@ Target the [public Scorecard report](https://scorecard.dev/viewer/?uri=github.co
 | Check | Today (baseline) | Path to 10 |
 |---|---|---|
 | **Binary-Artifacts** | 10 (no binaries committed) | Maintain — pre-commit guard rejecting any committed binary. |
-| **Branch-Protection** | needs token | Already configured on `master` (required reviews, signed commits, status-check gating, linear history). Verify in `gh api repos/.../branches/master/protection` and document in `docs/security/`. |
+| **Branch-Protection** | needs token | Already configured on `main` (required reviews, signed commits, status-check gating, linear history). Verify in `gh api repos/.../branches/main/protection` and document in `docs/security/`. |
 | **CI-Tests** | 10 (CI passes on every PR) | Maintain — current 75-check matrix is comprehensive. |
 | **CII-Best-Practices** / OpenSSF Best Practices badge | not present | Apply for the badge at [bestpractices.coreinfrastructure.org](https://www.bestpractices.dev/) and embed the badge in README. |
 | **Code-Review** | needs verification | Already enforced via branch protection; document in CONTRIBUTING.md. |

package/docs/operations/TRACEABILITY.md

@@ -39,3 +39,5 @@ It is enforced by `bash ./scripts/qa/traceability-coverage.sh`.
 | BT-27 | Workstation environment manifest emitter (`dot env emit`) | `scripts/dot/commands/env-emit.sh` | `tests/unit/dot-cli/test_cmd_env_emit.sh` | `docs/operations/MANIFEST.md`, `docs/schema/dot-env-v1.json` |
 | BT-28 | Cross-file version-string consistency contract | `scripts/qa/check-version-consistency.sh` | `tests/unit/qa/test_check_version_consistency.sh` | `docs/operations/RELIABILITY.md` |
 | BT-29 | OpenSSF Scorecard nightly snapshot artefact | `scripts/qa/scorecard-snapshot.sh` | `tests/unit/qa/test_scorecard_snapshot.sh` | `docs/security/SCORECARD.md` |
+| BT-30 | Shell completion generator (`dot completion <shell>`) | `scripts/dot/commands/completion.sh` | `tests/unit/dot-cli/test_dot_completion.sh` | `docs/reference/UTILS.md` |
+| BT-31 | Examples coverage contract (feature/command → example) | `scripts/qa/examples-coverage.sh` | `tests/unit/misc/test_qa_examples_coverage.sh` | `docs/reference/UTILS.md` |

package/docs/operations/TRUSTED_AGENT_WORKSTATION.md

@@ -20,12 +20,12 @@ It defines a signed, local-first workstation baseline for agentic development on
 
 The source of truth lives in tracked JSON artifacts:
 
-- [policy-bundles.json](../../defaults/dot_config/dotfiles/policy-bundles.json)
-- [agent-profiles.json](../../defaults/dot_config/dotfiles/agent-profiles.json)
-- [mcp-policy.json](../../defaults/dot_config/dotfiles/mcp-policy.json)
-- [mcp-registry.json](../../defaults/dot_config/dotfiles/mcp-registry.json)
-- [model-registry.json](../../defaults/dot_config/dotfiles/model-registry.json)
-- [prompt-registry.json](../../defaults/dot_config/dotfiles/prompt-registry.json)
+- [policy-bundles.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/policy-bundles.json)
+- [agent-profiles.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/agent-profiles.json)
+- [mcp-policy.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/mcp-policy.json)
+- [mcp-registry.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/mcp-registry.json)
+- [model-registry.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/model-registry.json)
+- [prompt-registry.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/prompt-registry.json)
 
 ## Enterprise path
 

package/docs/operations/VERSION_SYNC.md

@@ -35,7 +35,7 @@ This system provides automated version synchronization through:
 
 **Triggers**:
 
-- Push to `master` branch when `package.json` changes
+- Push to `main` branch when `package.json` changes
 - Pull requests affecting `package.json`
 - Manual dispatch with optional target version
 
@@ -146,8 +146,8 @@ Version changes in `package.json` automatically trigger synchronization:
 # Developer updates package.json version
 npm version patch
 
-# Push to master
-git push origin master
+# Push to main
+git push origin main
 
 # GitHub Actions automatically:
 # 1. Detects version change

package/docs/reference/UTILS.md

@@ -22,6 +22,7 @@ The `dot` command is the main interface for managing dotfiles. Run `dot version`
 | `dot diff` | Show local changes (excludes scripts) |
 | `dot status` | Show configuration drift |
 | `dot remove <path>` | Safely remove a managed file |
+| `dot uninstall` | Remove the managed dotfiles environment (prompts unless `--force`) |
 | `dot cd` | Print source directory path |
 | `dot edit` | Open source in your editor |
 | `dot clean-cache` | Clear generated shell initialization caches |
@@ -39,6 +40,7 @@ The `dot` command is the main interface for managing dotfiles. Run `dot version`
 | Command | Description |
 |---------|-------------|
 | `dot doctor` | Run system health checks (`--score/-s`,`--heal/-H`) |
+| `dot secret-audit` | Audit secret hygiene and leakage surface |
 | `dot health` | Run the health dashboard (`--verbose/-v`,`--json/-j`,`--fix/-f`,`--force/-F`) |
 | `dot heal` | Auto-repair missing tools, chezmoi drift, broken symlinks, and critical files (`--dry-run/-n`,`--force/-f`) |
 | `dot smoke-test` | Verify toolchains (Rust, Go, AI CLIs) |
@@ -69,6 +71,7 @@ The `dot` command is the main interface for managing dotfiles. Run `dot version`
 | Command | Description |
 |---------|-------------|
 | `dot env` | Show managed runtime and tool versions |
+| `dot env emit` | Emit a portable workstation environment manifest (SBOM) |
 | `dot profile` | Show or switch the active configuration profile |
 | `dot keys` | Show the keybindings and signing reference |
 | `dot tools` | Show tools documentation |
@@ -78,6 +81,7 @@ The `dot` command is the main interface for managing dotfiles. Run `dot version`
 | `dot learn` | Start the guided onboarding tour |
 | `dot docs` | Show the main repository documentation |
 | `dot log-rotate` | Rotate `~/.local/share/dotfiles.log` |
+| `dot completion <bash\|zsh\|fish\|nu>` | Generate shell completions from the command registry |
 | `dot lint` | Lint shell scripts (`--check/-c`,`--fix/-f`) |
 
 ## Universal Scripts
@@ -142,6 +146,7 @@ prints a one-line hint. See [AI.md](../AI.md) for the full surface.
 | Command | Description |
 |---------|-------------|
 | `dot backup` | Create a compressed backup |
+| `dot policy` | Check and enforce security policies across the environment |
 | `dot encrypt-check` | Check disk encryption status |
 | `dot firewall` | Apply firewall hardening |
 | `dot telemetry` | Disable telemetry |
@@ -157,3 +162,80 @@ prints a one-line hint. See [AI.md](../AI.md) for the full surface.
 | `dot fleet drift` | Check configuration drift across managed files |
 | `dot fleet namespace` | Show or set the active fleet namespace |
 | `dot fleet events` | Show recent local fleet events |
+| `dot teleport <user@host>` | Deploy the dotfiles environment to a remote host over SSH |
+
+## Subcommands
+
+Every `dot` command's individually-enforced subcommands (see `dot help`).
+
+| Command | Description |
+|---|---|
+| `dot fleet status` | Show this node's fleet status: id, namespace, version, OS, drift, last apply |
+| `dot fleet enforce` | Show or set RBAC enforcement mode (advisory/strict) for agent profiles |
+| `dot fleet apply` | SSH to every host in fleet.toml and run dot sync (or a custom --cmd) |
+| `dot ai chat` | Start an interactive AI session with a chosen tool |
+| `dot ai tools` | Show installed AI CLI tools and their versions |
+| `dot ai install` | Install AI CLI tools via mise/native installers |
+| `dot ai serve` | Run the local AI gateway/proxy that routes non-Claude providers |
+| `dot ai cost` | Report AI spend across every provider from the unified run log |
+| `dot ai login` | Interactive setup/authentication for installed AI CLI tools |
+| `dot ai doctor` | Diagnose AI tooling configuration and connectivity |
+| `dot ai ask` | Context-aware RAG query over your dotfiles |
+| `dot ai run` | Run a one-shot prompt with an AI tool |
+| `dot ai delegate` | Delegate a coding task to a cheaper AI model under agent policy |
+| `dot mode list` | List available agent operating profiles (ask/plan/apply/audit) |
+| `dot mode current` | Show the active agent profile and its policy |
+| `dot mode show` | Show details of a specific agent profile |
+| `dot mode set` | Switch the active agent profile |
+| `dot mode run` | Run a command under a given agent profile with a checkpoint |
+| `dot mode doctor` | Validate the agent-profiles.json config and default profile |
+| `dot agent card` | Show the local agent card metadata |
+| `dot agent log` | Tail the agent session audit log |
+| `dot agent checkpoint` | Manage agent run checkpoints (save/list/show/replay) |
+| `dot agent delegate` | Delegate execution to an allowed sub-agent |
+| `dot agent a2a-card` | Show or validate the A2A v0.3 agent card |
+| `dot agent conformance` | Run the A2A conformance test suite |
+| `dot mcp doctor` | Run the MCP policy/supply-chain/config audit |
+| `dot mcp registry` | Show the configured MCP server registry |
+| `dot secrets edit` | Edit the encrypted secrets file (age) |
+| `dot secrets set` | Store a secret value under a key |
+| `dot secrets get` | Retrieve a secret value (--raw for plaintext) |
+| `dot secrets list` | List indexed secret keys |
+| `dot secrets load` | Emit export lines for a secrets bucket (use with eval) |
+| `dot secrets provider` | Show the active secrets provider |
+| `dot env list` | List managed tool versions via mise |
+| `dot env prune` | Show or remove orphan tool installs (--yes to commit) |
+| `dot env install` | Install requested tool versions via mise |
+| `dot env use` | Pin a tool version globally/locally via mise |
+| `dot registry list` | List modules in the configured module registry |
+| `dot registry search` | Filter registry modules by keyword |
+| `dot registry info` | Print full metadata for a registry module |
+| `dot registry install` | Install a registry module (scaffold) |
+| `dot registry url` | Show the active registry URL |
+| `dot registry set-url` | Override the registry URL (https only; persists) |
+| `dot theme list` | Show all available terminal/wallpaper themes |
+| `dot theme set` | Set a theme by name (interactive picker if omitted) |
+| `dot theme toggle` | Toggle light/dark within the current theme family |
+| `dot theme sync` | Sync the dotfiles theme with system dark/light mode |
+| `dot theme family` | Cycle between theme families |
+| `dot theme current` | Show the current theme info |
+| `dot theme rebuild` | Regenerate themes from system and custom wallpapers |
+| `dot wallpaper sync` | Sync wallpaper from your library |
+| `dot wallpaper rotate` | Rotate to the next wallpaper in your library |
+| `dot tools install` | Enter the Nix development shell with all managed tools |
+| `dot tools docs` | Show the full tools markdown documentation |
+| `dot profile show` | Show the active configuration profile and feature flags |
+| `dot profile set` | Set the active configuration profile (run dot sync to apply) |
+| `dot agents list` | Show recognised AI agent harnesses and their config paths |
+| `dot agents check` | Verify AGENTS.md tracks CLAUDE.md (exit 1 if drifted) |
+| `dot agents render` | Regenerate AGENTS.md and per-harness config from CLAUDE.md |
+| `dot aliases list` | List all shell aliases shipped by the dotfiles |
+| `dot aliases search` | Search aliases by term |
+| `dot aliases why` | Show details and deprecation status for a single alias |
+| `dot aliases stats` | Show alias usage counts from shell history |
+| `dot aliases cheatsheet` | Generate the alias cheatsheet markdown |
+| `dot aliases tiers` | Show which alias tiers/ecosystems are enabled |
+| `dot patterns list` | List AI steering patterns |
+| `dot patterns view` | View an AI steering pattern |
+| `dot patterns edit` | Edit an AI steering pattern in $EDITOR |
+| `dot keys sign-check` | Verify git commit-signing configuration and key availability |

package/docs/security/AUDIT_BYPASS.md

@@ -5,7 +5,7 @@ render_with_liquid: false
 # Pre-Push Audit Bypass
 
 This page documents when the pre-push reliability audit can be bypassed,
-how to do it, and why the answer is "almost never on `master`."
+how to do it, and why the answer is "almost never on `main`."
 
 ## Background
 
@@ -57,7 +57,7 @@ bypassed?" without git archaeology.
 
 Short list — anything outside this is suspicious:
 
-- **Hotfix push to a non-master branch** when CI infrastructure itself
+- **Hotfix push to a non-main branch** when CI infrastructure itself
   is the audit blocker (e.g., the audit pre-flight depends on a remote
   service that's down). The fix should land *before* the
   infrastructure recovers; bypass is the bridge.
@@ -66,7 +66,7 @@ Short list — anything outside this is suspicious:
 
 When bypass is **not** legitimate:
 
-- Routine `master` pushes. The whole point of the audit is to guard
+- Routine `main` pushes. The whole point of the audit is to guard
   the protected branch.
 - Pushes whose audit failure is "annoying" — the right move is to fix
   the failure, not skip the check.

package/docs/security/AUTOMATION_SECRETS.md

@@ -21,6 +21,6 @@ render_with_liquid: false
 ## Provisioning notes
 
 1. Store the SSH signing private key in GitHub Actions as `ACTIONS_BOT_SIGNING_KEY`.
-2. Store the matching public key in [allowed_signers](../../defaults/dot_config/git/allowed_signers.tmpl).
+2. Store the matching public key in [allowed_signers](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/git/allowed_signers.tmpl).
 3. Rotate the key on personnel or workstation change.
 4. Fail closed when secrets are absent.

package/docs/security/CI_PINNING.md

@@ -17,7 +17,7 @@ Every external dependency the CI pipeline consumes must be pinned by
 When `ci.yml` calls a reusable via `./.github/workflows/reusable-X.yml`,
 GitHub resolves the reusable from the **same ref as the calling
 workflow at run time**. For an in-repo PR that's the PR's branch —
-fine. The risk is the inverse: a malicious push to `master` (or any
+fine. The risk is the inverse: a malicious push to `main` (or any
 ref the calling workflow might resolve from) can swap reusable
 content under a CI run, with no audit trail in the PR diff.
 
@@ -29,11 +29,11 @@ site — visible in the PR diff, reviewable, revertible.
 
 ```yaml
 # Acceptable — full SHA pin.
-uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@b0615f8fb5c0f3826f58904a5567eff11b6c500e # master
+uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@b0615f8fb5c0f3826f58904a5567eff11b6c500e # main
 ```
 
 The trailing comment is a human-readable hint at what the SHA
-represented when it was pinned (typically `master`, sometimes a tag
+represented when it was pinned (typically `main`, sometimes a tag
 like `v0.2.501`). The hint is documentation only — the SHA is what
 GitHub uses.
 
@@ -44,7 +44,7 @@ GitHub uses.
 uses: ./.github/workflows/reusable-shell-lint.yml
 
 # Rejected — branch ref is mutable.
-uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@master
+uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@main
 
 # Rejected — tag ref is mutable (tags can be moved).
 uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@v0.2.501
@@ -57,20 +57,20 @@ rejected forms above.
 ## Refreshing pinned SHAs
 
 `bump-reusable-pins.yml` handles this automatically. On every push to
-`master` that touches `.github/workflows/reusable-*.yml`, the bot scans
+`main` that touches `.github/workflows/reusable-*.yml`, the bot scans
 caller workflows for stale pins and opens a PR bumping them to the new
 SHA. Signed with `ACTIONS_BOT_SIGNING_KEY` so the resulting commit
 passes `Verify Commit Signatures`.
 
 The manual recipe below stays here as a fallback — for example, if you
-need to bump pins before a merge to master, or if the bot's run failed
+need to bump pins before a merge to main, or if the bot's run failed
 and you want to short-circuit waiting for the next push trigger.
 
 ```sh
-# 1. Land the change to the reusable on master via a PR.
-# 2. After merge, capture the new master SHA:
-git fetch origin master
-PIN=$(git rev-parse origin/master)
+# 1. Land the change to the reusable on main via a PR.
+# 2. After merge, capture the new main SHA:
+git fetch origin main
+PIN=$(git rev-parse origin/main)
 echo "$PIN"
 
 # 3. Bump every call site:

package/docs/security/COMMIT_SIGNING.md

@@ -1,6 +1,6 @@
 # Commit Signing — Policy & Setup
 
-Every commit that reaches `master` in this repository must carry a
+Every commit that reaches `main` in this repository must carry a
 cryptographic signature that GitHub can verify. The policy is enforced
 in three independent layers, so a single bypass does not break the
 chain. This document explains the policy, walks through SSH and GPG
@@ -24,16 +24,16 @@ is missing. The chain below removes every escape hatch.
    `git verify-commit` against every commit in the push range. A
    single unverified commit aborts the push. `--no-verify` skips
    this layer; the next two catch it.
-3. **GitHub Rulesets** — `.github/rulesets/master.json` declares
-   `required_signatures` on `refs/heads/master`. The rule is part
+3. **GitHub Rulesets** — `.github/rulesets/main.json` declares
+   `required_signatures` on `refs/heads/main`. The rule is part
    of the repo so it's reproducible across forks. Apply with
-   `gh ruleset import .github/rulesets/master.json`.
+   `gh ruleset import .github/rulesets/main.json`.
 4. **`compliance-guard.yml` workflow** — runs on every PR targeting
-   `master`. Walks the commit range with `git verify-commit` and
+   `main`. Walks the commit range with `git verify-commit` and
    marks unsigned commits in the PR summary; fails the workflow
    when `unsigned_count > 0`.
 
-A merge to `master` therefore requires (Ruleset accepts the push) AND
+A merge to `main` therefore requires (Ruleset accepts the push) AND
 (the workflow's signed-commit check passes) AND (the maintainer's
 push key is allowed). The protection holds even if a contributor's
 local hooks are missing or skipped.
@@ -100,7 +100,7 @@ git log "$(git merge-base @{u} HEAD)..HEAD" \
 for c in $(git rev-list "$(git merge-base @{u} HEAD)..HEAD"); do
   git verify-commit "$c" >/dev/null 2>&1 \
     && echo "✓ $c" \
-    || echo "✗ $c — unsigned, will be rejected by master ruleset"
+    || echo "✗ $c — unsigned, will be rejected by main ruleset"
 done
 ```
 
@@ -112,7 +112,7 @@ done
 | `error: Load key "/.../id_ed25519": Permission denied` | SSH key permissions too open | `chmod 600 ~/.ssh/id_ed25519` |
 | GitHub shows "Unverified" on a commit signed locally | Signing key not uploaded to GitHub | `gh ssh-key add … --type signing` (SSH) or `gh gpg-key add` (GPG) |
 | Pre-push hook rejects a merge commit you didn't author | Upstream commit lacks a signature | Either pull the rebased branch, or fast-forward instead of merging |
-| Ruleset import via `gh` complains "invalid JSON" | Rulesets API expects the `target` + `rules` envelope, not just the rules array | Use the file as-is — `gh ruleset import .github/rulesets/master.json` |
+| Ruleset import via `gh` complains "invalid JSON" | Rulesets API expects the `target` + `rules` envelope, not just the rules array | Use the file as-is — `gh ruleset import .github/rulesets/main.json` |
 
 ## Re-applying the ruleset after a manual edit
 
@@ -121,14 +121,14 @@ file-of-truth wins. Re-apply:
 
 ```sh
 gh api -X POST repos/{owner}/{repo}/rulesets \
-  --input .github/rulesets/master.json
+  --input .github/rulesets/main.json
 ```
 
 (or `-X PUT` against the existing ruleset's ID if it already exists).
 
 ## References
 
-- `.github/rulesets/master.json` — the enforced policy.
+- `.github/rulesets/main.json` — the enforced policy.
 - `.github/workflows/compliance-guard.yml` — the workflow that
   fails PRs containing unsigned commits.
 - `scripts/git-hooks/pre-push` — the local pre-push gate.