@sebastienrousseau/dotfiles 0.2.508 → 0.2.511

package/docs/manual/command-index.md

@@ -12,11 +12,36 @@ job `lint/command-index` fails when this file is stale.
 |---------|---------|
 | `dot add` | Add a file to chezmoi source |
 | `dot agent` | Profile-aware execution, agent card, a2a-card, session log, checkpoints, and conformance |
+| `dot agent` | a2a-card Show or validate the A2A v0.3 agent card |
+| `dot agent` | card Show the local agent card metadata |
+| `dot agent` | checkpoint Manage agent run checkpoints (save/list/show/replay) |
+| `dot agent` | conformance Run the A2A conformance test suite |
+| `dot agent` | delegate Delegate execution to an allowed sub-agent |
+| `dot agent` | log Tail the agent session audit log |
+| `dot agents` | check Verify AGENTS.md tracks CLAUDE.md (exit 1 if drifted) |
+| `dot agents` | list Show recognised AI agent harnesses and their config paths |
+| `dot agents` | render Regenerate AGENTS.md and per-harness config from CLAUDE.md |
 | `dot agy` | Antigravity CLI with context patterns |
 | `dot ai` | AI fleet cockpit, gateway, and cost |
+| `dot ai` | ask Context-aware RAG query over your dotfiles |
+| `dot ai` | chat Start an interactive AI session with a chosen tool |
+| `dot ai` | cost Report AI spend across every provider from the unified run log |
+| `dot ai` | delegate Delegate a coding task to a cheaper AI model under agent policy |
+| `dot ai` | doctor Diagnose AI tooling configuration and connectivity |
+| `dot ai` | install Install AI CLI tools via mise/native installers |
+| `dot ai` | login Interactive setup/authentication for installed AI CLI tools |
+| `dot ai` | run Run a one-shot prompt with an AI tool |
+| `dot ai` | serve Run the local AI gateway/proxy that routes non-Claude providers |
+| `dot ai` | tools Show installed AI CLI tools and their versions |
 | `dot ai-query` | Context-aware RAG query over your dotfiles |
 | `dot ai-setup` | Interactive setup for all AI CLI tools |
 | `dot aider` | Aider with context patterns |
+| `dot aliases` | cheatsheet Generate the alias cheatsheet markdown |
+| `dot aliases` | list List all shell aliases shipped by the dotfiles |
+| `dot aliases` | search Search aliases by term |
+| `dot aliases` | stats Show alias usage counts from shell history |
+| `dot aliases` | tiers Show which alias tiers/ecosystems are enabled |
+| `dot aliases` | why Show details and deprecation status for a single alias |
 | `dot attest` | Export workstation attestation evidence (--json |
 | `dot backup` | Create a compressed backup of your home |
 | `dot bundle` | Create offline archive of dotfiles environment |
@@ -25,6 +50,7 @@ job `lint/command-index` fails when this file is stale.
 | `dot chaos` | Simulate config corruption to test self-healing |
 | `dot cl` | Claude CLI with context patterns |
 | `dot commit` | AI-powered conventional commit |
+| `dot completion` | Generate shell completions (bash/zsh/fish/nu) from the command registry |
 | `dot copilot` | GitHub Copilot CLI with context patterns |
 | `dot diff` | Show chezmoi diff with exclusions |
 | `dot dns-doh` | Enable DNS-over-HTTPS [macOS,Linux] |
@@ -33,34 +59,70 @@ job `lint/command-index` fails when this file is stale.
 | `dot edit` | Open chezmoi source in $EDITOR |
 | `dot encrypt-check` | Check disk encryption status |
 | `dot env` | Tool versions (mise) |
+| `dot env` | emit Emit a portable workstation environment manifest (SBOM; --format json) |
+| `dot env` | install Install requested tool versions via mise |
+| `dot env` | list List managed tool versions via mise |
+| `dot env` | prune Show or remove orphan tool installs (--yes to commit) |
+| `dot env` | use Pin a tool version globally/locally via mise |
 | `dot firewall` | Apply firewall hardening [macOS,Linux] |
 | `dot fleet` | Show fleet node status, drift, and namespace (--json for machine output) |
+| `dot fleet` | apply SSH to every host in fleet.toml and run dot sync (or a custom --cmd) |
 | `dot fleet` | drift Check for configuration drift across managed files |
+| `dot fleet` | enforce Show or set RBAC enforcement mode (advisory/strict) for agent profiles |
 | `dot fleet` | events Show recent fleet events from local event log |
 | `dot fleet` | namespace Show or set the active namespace for multi-tenant isolation |
-| `dot fonts` | Install Nerd Fonts (JetBrainsMono by default) |
+| `dot fleet` | status Show this node's fleet status: id, namespace, version, OS, drift, last apply |
+| `dot fonts` | Install (default) or patch Nerd Fonts (JetBrainsMono by default) |
 | `dot help` | Show this help message |
 | `dot history` | Shell history analysis |
 | `dot keys` | Keybindings (sign-check: verify git signing) |
+| `dot keys` | sign-check Verify git commit-signing configuration and key availability |
 | `dot kiro` | Kiro CLI with context patterns |
 | `dot learn` | Start the interactive tour of your new tools |
 | `dot lint` | Lint shell scripts (--fix |
 | `dot load-bench` | Measure time to heavy-layer readiness |
 | `dot lock-screen` | Enforce lock screen idle settings [Linux] |
 | `dot mcp` | Inspect MCP policy, supply chain, and registry |
+| `dot mcp` | doctor Run the MCP policy/supply-chain/config audit |
+| `dot mcp` | registry Show the configured MCP server registry |
 | `dot metrics` | Show recent observability metrics (JSONL) |
 | `dot mode` | Set or inspect agent operating profiles (ask/plan/apply/audit) |
+| `dot mode` | current Show the active agent profile and its policy |
+| `dot mode` | doctor Validate the agent-profiles.json config and default profile |
+| `dot mode` | list List available agent operating profiles (ask/plan/apply/audit) |
+| `dot mode` | run Run a command under a given agent profile with a checkpoint |
+| `dot mode` | set Switch the active agent profile |
+| `dot mode` | show Show details of a specific agent profile |
 | `dot new` | Create a new project from a template |
 | `dot ollama` | Ollama with context patterns |
 | `dot opencode` | OpenCode with context patterns |
 | `dot packages` | List installed packages and package managers |
+| `dot patterns` | edit Edit an AI steering pattern in $EDITOR |
+| `dot patterns` | list List AI steering patterns |
+| `dot patterns` | view View an AI steering pattern |
 | `dot perf` | Show performance mode and quick timing |
+| `dot policy` | Check and enforce security policies across the environment |
 | `dot profile` | Show/switch configuration profile |
+| `dot profile` | set Set the active configuration profile (run dot sync to apply) |
+| `dot profile` | show Show the active configuration profile and feature flags |
+| `dot registry` | info Print full metadata for a registry module |
+| `dot registry` | install Install a registry module (scaffold) |
+| `dot registry` | list List modules in the configured module registry |
+| `dot registry` | search Filter registry modules by keyword |
+| `dot registry` | set-url Override the registry URL (https only; persists) |
+| `dot registry` | url Show the active registry URL |
 | `dot rollback` | Rollback dotfiles to a previous state |
 | `dot sandbox` | Launch a safe sandbox preview (Docker/Podman) |
 | `dot score` | System health and security scorecard |
 | `dot search` | Find commands by keyword |
+| `dot secret-audit` | Audit secret hygiene and leakage surface |
 | `dot secrets` | Edit encrypted secrets (age) |
+| `dot secrets` | edit Edit the encrypted secrets file (age) |
+| `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 secrets` | set Store a secret value under a key |
 | `dot secrets-create` | Create an encrypted secrets file |
 | `dot secrets-init` | Initialize age key for secrets |
 | `dot sgpt` | Shell-GPT with context patterns |
@@ -70,10 +132,23 @@ job `lint/command-index` fails when this file is stale.
 | `dot status` | Show configuration drift (chezmoi status) |
 | `dot sync` | Apply dotfiles (alias for apply; --pull to fetch, --check to preview) |
 | `dot telemetry` | Disable OS telemetry [macOS,Linux] |
+| `dot teleport` | Deploy the dotfiles environment to a remote host over SSH |
 | `dot theme` | Switch terminal theme (dark/light) |
+| `dot theme` | current Show the current theme info |
+| `dot theme` | family Cycle between theme families |
+| `dot theme` | list Show all available terminal/wallpaper themes |
+| `dot theme` | rebuild Regenerate themes from system and custom wallpapers |
+| `dot theme` | set Set a theme by name (interactive picker if omitted) |
+| `dot theme` | sync Sync the dotfiles theme with system dark/light mode |
+| `dot theme` | toggle Toggle light/dark within the current theme family |
 | `dot tools` | Show or install nix packages |
+| `dot tools` | docs Show the full tools markdown documentation |
+| `dot tools` | install Enter the Nix development shell with all managed tools |
 | `dot tune` | Apply OS tuning (opt-in) [macOS,Linux] |
+| `dot uninstall` | Remove the managed dotfiles environment (prompts unless --force) |
 | `dot upgrade` | Update system toolchains, plugins, and dotfiles |
 | `dot usb-safety` | Disable automount for removable media [Linux] |
 | `dot version` | Show version information. |
 | `dot wallpaper` | Apply a wallpaper from your library [macOS,Linux] |
+| `dot wallpaper` | rotate Rotate to the next wallpaper in your library |
+| `dot wallpaper` | sync Sync wallpaper from your library |

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 |