@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/docs/manual/04-cookbook/03-faq.md

@@ -0,0 +1,167 @@
+# Cookbook: Frequently Asked Questions
+
+## General
+
+### Why use this over stow, yadm, or a plain Git repo?
+
+Because it's not just a dotfiles manager. It's a workstation baseline with:
+
+- Cryptographic attestation
+- AI/MCP policy enforcement
+- Wallpaper-driven theme engine (WCAG AAA)
+- Self-healing + chaos testing
+- Fleet management
+- Per-platform rendering via chezmoi templates
+
+If you only need to symlink `.bashrc`, use stow. If you're operating a fleet of signed, attested, AI-aware workstations, use this.
+
+### Does it work on Windows?
+
+Only via WSL2. Native Windows PowerShell support exists for baseline parity (aliases, prompt), but the full feature set (chezmoi, Mise, theme engine) requires WSL2.
+
+### Is it production-ready?
+
+Yes — it's the author's daily driver across multiple hosts and receives regular releases (see `CHANGELOG.md`). CI enforces 100% test coverage, zero-warning linting, WCAG AAA for themes, SBOM + CVE scanning, and signed commits on every merge.
+
+### Can I fork it and use it without attribution?
+
+Yes — MIT License. Attribution is appreciated but not required.
+
+## Themes
+
+### Why K-Means in CIELAB instead of RGB?
+
+CIELAB distances approximate human perception. A Δ in RGB might look identical to your eye in one part of the color space and very different in another. Clustering in Lab produces palettes where "close" colors actually look close. See [Theme Engine](../01-concepts/03-theme-engine.md).
+
+### Why not pre-built themes like Catppuccin or Rosé Pine?
+
+Two reasons:
+1. **Maintenance** — 100+ themes × 20+ applications = thousands of template variables to keep in sync. Generation from wallpapers eliminates that.
+2. **User agency** — users bring their own wallpapers. The theme adapts to them, not the other way around.
+
+The engine can still produce Catppuccin-like output: give it a Catppuccin wallpaper and you get Catppuccin-aligned terminal colors.
+
+### Does it ship wallpapers?
+
+No. Apple/Microsoft/distro-vendor wallpapers are copyrighted. The repo discovers wallpapers that are already on the user's system (at `~/Pictures/Wallpapers/` or the OS's system wallpaper directory). Users bring their own images.
+
+### How do I control the accent color?
+
+You don't directly — the accent hue is extracted from the wallpaper. But `_compute_accent()` picks the most chromatic cluster, then darkens it until white text meets 7:1 contrast. If you want a specific accent, choose a wallpaper with that hue dominant.
+
+### Can I use my own theme without a wallpaper?
+
+Not directly — the engine expects a source image. You could:
+1. Pick a wallpaper whose palette you want
+2. Let the engine generate the theme
+3. Lock the generated `.toml` entry by copying to a non-regenerated path
+
+But this defeats the point. If you have a specific palette in mind, generate a solid-color or gradient image with those colors and use that.
+
+## Secrets
+
+### Why Age instead of GPG?
+
+GPG is notoriously complex. Age is simpler, uses modern crypto (X25519 + ChaCha20-Poly1305), and has no legacy baggage. It's the tool [SOPS recommends](https://github.com/getsops/sops#encrypting-using-age).
+
+### Why commit encrypted secrets at all?
+
+- **Traceable** — Git history shows when secrets changed
+- **Auditable** — ciphertext is testable without decryption
+- **Portable** — clone the repo anywhere, decrypt with your key
+- **No external dependency** — no Vault/AWS Secrets Manager/etc.
+
+The alternative (storing secrets outside the repo) creates sync headaches across fleet hosts. Encrypted-at-rest-in-repo is simpler and just as secure if keys are managed correctly.
+
+### What if I lose my Age private key?
+
+You lose access to all secrets encrypted only for that key. Recovery requires another recipient (another host with a valid key) to decrypt and re-encrypt. Fleet setups use multiple recipients for this reason — see [Deploy to Fleet](../02-tutorials/05-deploy-fleet.md).
+
+## AI & Agents
+
+### Does this require an API key?
+
+No. The AI tools (Claude Code, Codex, Copilot) are installed but require their own authentication. `dot ai` shows what's present without invoking any remote service.
+
+### What is MCP?
+
+The [Model Context Protocol](https://modelcontextprotocol.io/) is a standard for connecting AI models to tools and data sources. `.dotfiles` includes policy enforcement for MCP-aware agents: allowlists, attestation, and signed registries. See [Trust Model](../01-concepts/02-trust-model.md).
+
+### Can I add my own agent profile?
+
+Yes. Drop a Markdown file in `dot_config/ai/patterns/`. Each file describes a profile (architect, hardener, etc.). `dot mode <name>` switches between them.
+
+## Fleet
+
+### How many hosts can I manage?
+
+No hard limit. The `dot fleet` commands SSH sequentially by default, so large fleets (>20 hosts) benefit from parallel invocation. For industrial scale, pair with Ansible/Nix/Puppet; `.dotfiles` handles the user-level config, not system administration.
+
+### Do I need a central server?
+
+No. Everything is Git-based. No central orchestration service, no daemon. Each host pulls independently.
+
+### Can two hosts have different themes?
+
+Yes. Each host's `~/.config/chezmoi/chezmoi.toml` can set its own `theme`. This is per-host override — not shared in the repo.
+
+## Performance
+
+### Why is my shell startup 800ms when the budget is 500ms?
+
+Check what's loaded:
+
+```sh
+DOTFILES_DEBUG=1 zsh -i -c exit 2>&1 | grep -E '\[debug [0-9]+ms\]'
+```
+
+Common culprits:
+- nvm loading Node on every shell (use lazy loading)
+- `mise activate` with aggressive hook-env (set `activate_aggressive = false`)
+- Plugin manager scanning for updates
+
+Run `dot benchmark --detailed` to attribute cost.
+
+### Can I disable prewarming?
+
+Yes — but your cold shell startup will be slow. Remove the prewarm invocation from your shell profile or skip `dot prewarm` after apply.
+
+## Troubleshooting Community
+
+### Where do I report bugs?
+
+GitHub issues: <https://github.com/sebastienrousseau/dotfiles/issues>. Include output of `dot doctor --json` and your platform.
+
+### Where do I ask usage questions?
+
+GitHub discussions, or mention in the issue you open. The maintainer responds best to issues with clear repro steps.
+
+### Is there a Discord / Slack?
+
+Not currently.
+
+## Philosophy
+
+### Why so much emphasis on attestation?
+
+Because AI agents operating on your workstation can do anything you can. Attestation is the audit trail — who ran what, when, with which policy. Without it, agent operations are black boxes.
+
+### Why MIT License?
+
+To maximize adoption and contribution. MIT is compatible with commercial use; copyleft alternatives would restrict who can use the code.
+
+### Why no GUI configurator?
+
+Text + Git is the optimal interface for a workstation baseline:
+- Versioned (Git history)
+- Reproducible (same input → same output)
+- Auditable (diff-able)
+- Scriptable (any `dot` command can be invoked programmatically)
+
+A GUI adds complexity without benefit over editing `.chezmoidata.toml` directly.
+
+## See Also
+
+- [Troubleshooting](02-troubleshooting.md)
+- [Recipes](01-recipes.md)
+- [GitHub Discussions](https://github.com/sebastienrousseau/dotfiles/discussions)

package/docs/manual/05-appendices/A-platform-matrix.md

@@ -0,0 +1,97 @@
+# Appendix A: Platform Support Matrix
+
+## Supported Platforms
+
+| OS | Version | Support | Notes |
+|:---|:---|:---:|:---|
+| macOS | 14 (Sonoma) | ✓ full | Primary development platform |
+| macOS | 15 (Sequoia) | ✓ full | |
+| macOS | 26 (Tahoe) | ✓ full | |
+| Ubuntu | 22.04 LTS | ✓ full | |
+| Ubuntu | 24.04 LTS | ✓ full | CI reference platform |
+| Debian | 12 (Bookworm) | ✓ full | |
+| Debian | 13 (Trixie) | ✓ full | |
+| Arch Linux | rolling | ✓ full | |
+| CachyOS | rolling | ✓ full | Arch-based |
+| Fedora | 39 | ✓ | Less tested |
+| Fedora | 40, 41 | ✓ | Less tested |
+| openSUSE | Tumbleweed | ✓ | Less tested |
+| Alpine | 3.20 | ⚠ partial | POSIX shells only; no Fish |
+| WSL2 | Ubuntu 22.04+ | ✓ full | Windows 11 host |
+| WSL2 | Debian | ✓ full | |
+| Windows PowerShell | 7.5+ | ⚠ baseline | Aliases + prompt; no chezmoi |
+| FreeBSD | 14 | ✗ untested | |
+| Termux (Android) | latest | ✗ untested | |
+
+## Supported Shells
+
+| Shell | Version | Support |
+|:---|:---|:---:|
+| Fish | 3.6+ | ✓ primary |
+| Zsh | 5.9+ | ✓ full |
+| Bash | 5.0+ | ✓ full |
+| Nushell | 0.90+ | ✓ full |
+| PowerShell | 7.5+ | ⚠ baseline |
+
+## Supported Architectures
+
+| Arch | Status |
+|:---:|:---:|
+| amd64 / x86_64 | ✓ |
+| arm64 / aarch64 | ✓ |
+| armv7 | ⚠ best-effort |
+| riscv64 | ✗ untested |
+
+## Required Binaries
+
+| Binary | Purpose | Install |
+|:---|:---|:---|
+| `git` | Version control | System package manager |
+| `curl` | Installer | System package manager |
+| `chezmoi` | Template engine | Installer downloads verified binary |
+
+## Optional Binaries (installed by Mise on first apply)
+
+| Binary | Purpose |
+|:---|:---|
+| `mise` | Runtime version manager |
+| `age` | Secret encryption |
+| `sops` | YAML secret encryption |
+| `pandoc` | Manual generation |
+| `shellcheck` | Shell linting |
+| `shfmt` | Shell formatting |
+| `starship` | Prompt |
+| `fzf` | Fuzzy finder |
+| `zoxide` | Smart `cd` |
+| `atuin` | Shell history sync |
+| `delta` | Git diff pager |
+| `lazygit` | TUI Git client |
+| `neovim` | Editor |
+
+## Tested CI Environments
+
+| Environment | Workflow |
+|:---|:---|
+| macOS 14 (GHA) | `ci.yml`, `ci-enforced.yml` |
+| Ubuntu 24.04 (GHA) | `ci.yml`, `ci-enforced.yml` |
+| GitHub Codespaces | `devcontainer-prebuild.yml` |
+| Docker Ubuntu 24.04 | `ci.yml` test-docker job |
+
+## Feature Matrix
+
+| Feature | macOS | Linux | WSL2 |
+|:---|:---:|:---:|:---:|
+| Shell configs (zsh/fish/bash/nu) | ✓ | ✓ | ✓ |
+| Terminal emulator configs | ✓ | ✓ | ✗ (host handles) |
+| Theme engine (K-Means) | ✓ | ✓ | ✓ |
+| Dynamic HEIC dark/light | ✓ native | ⚠ HEIC→PNG converted | ✗ |
+| Neovim + LSP | ✓ | ✓ | ✓ |
+| AI tools (Claude, Codex, etc.) | ✓ | ✓ | ✓ |
+| MCP policy enforcement | ✓ | ✓ | ✓ |
+| Attestation | ✓ | ✓ | ✓ |
+| Fleet (SSH-based) | ✓ | ✓ | ⚠ |
+| AeroSpace (WM) | ✓ | ✗ | ✗ |
+| Niri (WM) | ✗ | ✓ | ✗ |
+| GNOME gsettings | ✗ | ✓ | ⚠ |
+| Build artifact redirect | ✓ | ✓ | ✓ |
+| Self-healing (`dot heal`) | ✓ | ✓ | ✓ |

package/docs/manual/05-appendices/B-security-checklist.md

@@ -0,0 +1,78 @@
+# Appendix B: Security Checklist
+
+Run this checklist after a fresh install and quarterly afterwards.
+
+## Pre-Install
+
+- [ ] Download `install.sh` over HTTPS only
+- [ ] Inspect `install.sh` before running (optional, recommended for untrusted environments)
+- [ ] Ensure SSH signing key exists and is backed up (`~/.ssh/id_ed25519`)
+- [ ] Ensure Age key is backed up if reinstalling (`~/.config/age/keys.txt`)
+
+## Post-Install
+
+- [ ] Run `dot doctor` — expect score ≥90
+- [ ] Run `dot verify --security` — all checks pass
+- [ ] Verify commit signing: `cd ~/.dotfiles && git verify-commit HEAD`
+- [ ] Confirm `~/.ssh/allowed_signers` contains your public key
+- [ ] Check that `~/.config/age/keys.txt` permissions are `0600`
+- [ ] Run `dot mcp --strict` — policy matches registry
+
+## Ongoing (monthly)
+
+- [ ] `dot upgrade` — pick up security patches
+- [ ] `dot verify --security` — confirm no new leaks
+- [ ] Review `~/.local/state/dotfiles/mcp-violations.log` — any unexpected entries?
+- [ ] Review recent attestations — `ls ~/.local/state/dotfiles/attestation/ | tail -10`
+- [ ] Rotate Age key if compromised or as part of scheduled rotation
+
+## Ongoing (quarterly)
+
+- [ ] Rotate SSH signing key
+- [ ] Audit `~/.ssh/allowed_signers` — remove former team members
+- [ ] Review SOPS recipient list in `.sops.yaml`
+- [ ] Run `dot chaos` in a test container — verify heal works
+- [ ] Update pinned tool versions in `mise.toml`
+- [ ] Run fleet attestation — confirm all hosts aligned
+
+## Incident Response
+
+If a secret leak is detected:
+
+1. **Contain** — remove from history, force-push
+   ```sh
+   git filter-repo --path <file> --invert-paths
+   git push --force
+   ```
+2. **Rotate** — change the leaked secret upstream (Stripe key, SSH key, etc.)
+3. **Audit** — check who/what had access
+4. **Notify** — inform affected parties if required
+
+If a host is compromised:
+
+1. **Revoke** — remove the host's public key from `~/.ssh/allowed_signers` on all other fleet hosts
+2. **Re-encrypt** — `sops updatekeys` with the host excluded from recipients
+3. **Attest** — run `dot fleet attest` to verify revocation propagated
+4. **Wipe** — if the host is recoverable, `rm -rf ~/.config/age ~/.dotfiles` and reinstall
+
+## Gates Enforced by CI
+
+Every PR to master must pass:
+
+- [x] SSH-signed commits
+- [x] Shellcheck zero warnings (severity=error)
+- [x] Gitleaks scan
+- [x] Detect-secrets baseline diff
+- [x] TruffleHog verified scan
+- [x] Copyright headers present
+- [x] 100% unit test coverage
+- [x] Reliability tests (macOS + Ubuntu)
+- [x] Checkov infra scan
+- [x] Version sync (bumped across all files)
+
+## See Also
+
+- [Trust Model](../01-concepts/02-trust-model.md)
+- [Encrypt a Secret tutorial](../02-tutorials/04-encrypt-secret.md)
+- [Security Policy](../../security/SECURITY.md)
+- [Incident Response Playbook](../../security/INCIDENT_RESPONSE.md)

package/docs/manual/05-appendices/C-glossary.md

@@ -0,0 +1,36 @@
+# Appendix C: Glossary
+
+| Term | Definition |
+|:---|:---|
+| **Age** | Modern file-encryption tool using X25519 + ChaCha20-Poly1305. Stores secrets in the repository encrypted at rest. |
+| **Agent Profile** | A named behaviour template for AI agents (e.g. architect, hardener). Stored in `dot_config/ai/patterns/`. |
+| **ANSI Colors** | The 16 foreground/background color slots (c0 through c15) used by terminal emulators. |
+| **Apple Desktop APR** | XMP metadata in dynamic HEIC wallpapers mapping image indices to light/dark appearance modes. |
+| **Attestation** | Signed JSON document asserting machine identity, policy, tool versions, and Git state at a point in time. |
+| **Baseline (security)** | Reference state used by `detect-secrets` to distinguish new leaks from known acceptable patterns. |
+| **Chaos** | Intentional corruption (`dot chaos`) used to verify `dot heal` recovers to a healthy state. |
+| **Chezmoi** | The templating engine handling per-platform rendering and applying configuration to `$HOME`. |
+| **CIELAB** | Color space designed for perceptual uniformity. Used by the theme engine for K-Means clustering. |
+| **CycloneDX** | SBOM format used by the repository for machine-readable dependency inventories. |
+| **Dank Material Shell (DMS)** | A shell for the Niri Wayland compositor that provides polished theming hooks. |
+| **Drift** | Local changes to managed files that diverge from the source tree. Detected by `dot status`. |
+| **Dynamic HEIC** | Apple's single-file wallpaper format that contains both light and dark variants with appearance metadata. |
+| **Fleet** | Two or more workstations sharing a single `.dotfiles` source repository. |
+| **Gitleaks** | Secret-pattern scanner that blocks commits containing obvious secret patterns. |
+| **Golden Ratio** | 1.618... Used as the target brightness ratio between dark and light theme variants. |
+| **Heal** | The `dot heal` command's action of auto-fixing drift, missing tools, and broken symlinks. |
+| **Idempotent** | Property where running an operation twice has the same result as running it once. |
+| **K-Means** | Clustering algorithm partitioning data into k groups by proximity to centroids. Used for dominant color extraction. |
+| **K-Means++** | Variant of K-Means with smart initialization that reduces sensitivity to random seeding. |
+| **MCP** | Model Context Protocol — standard for connecting AI models to external tools and data. |
+| **Mise** | User-space language and tool version manager. Replaces asdf, nvm, rbenv, pyenv. |
+| **Nix Flakes** | Nix's reproducible-build system. Used for strict repeatability when Mise's approximations aren't enough. |
+| **Niri** | Wayland compositor with scrollable tiling layout. |
+| **Policy Hash** | SHA-256 of the active MCP policy JSON. Included in attestations for drift detection. |
+| **Prewarm** | `dot prewarm` regenerates shell init caches, eliminating slow first-shell startup. |
+| **Profile** | Named collection of settings in `.chezmoidata.toml` selectable via `dot profile`. |
+| **SOPS** | "Secrets OPerationS" — YAML-aware envelope encryption tool that wraps Age (or PGP/AWS KMS). |
+| **SBOM** | Software Bill of Materials — machine-readable dependency list, generated by Syft, scanned by Grype. |
+| **Trust Anchor** | The root public key from which all other trust derives. For `.dotfiles`, the user's SSH ED25519 signing key. |
+| **WCAG AAA** | Web Content Accessibility Guidelines Level AAA — 7:1 text contrast ratio, the highest accessibility tier. |
+| **XDG Base Directory** | Spec defining `~/.config`, `~/.cache`, `~/.local/share`, `~/.local/state` for app data locations. |

package/docs/manual/05-appendices/D-bibliography.md

@@ -0,0 +1,54 @@
+# Appendix D: Bibliography
+
+Cited works and recommended reading.
+
+## Algorithms
+
+- **MacQueen, J. (1967).** *Some methods for classification and analysis of multivariate observations.* Proceedings of the Fifth Berkeley Symposium on Mathematical Statistics and Probability. — The original K-Means paper.
+- **Arthur, D. & Vassilvitskii, S. (2007).** *K-Means++: The advantages of careful seeding.* ACM-SIAM Symposium on Discrete Algorithms. <https://theory.stanford.edu/~sergei/papers/kMeansPP-soda.pdf>
+- **Heckbert, P. (1982).** *Color image quantization for frame buffer display.* Computer Graphics 16(3). — Median cut algorithm, the alternative to K-Means.
+
+## Color Science
+
+- **CIE (1976).** *Recommendations on uniform color spaces, color-difference equations, psychometric color terms.* Supplement No. 2 to CIE Publication No. 15. — Defines CIELAB.
+- **Lindbloom, B. J.** *RGB/XYZ matrices.* <http://www.brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html> — sRGB → XYZ conversion reference.
+- **Fairchild, M. D. (2013).** *Color Appearance Models, 3rd Edition.* Wiley. — Comprehensive treatment of perceptual color spaces.
+
+## Accessibility
+
+- **W3C (2023).** *Web Content Accessibility Guidelines (WCAG) 2.2.* <https://www.w3.org/TR/WCAG22/> — Accessibility standards including contrast ratios.
+- **W3C.** *Techniques for WCAG 2.2: G17 Using a contrast ratio of at least 7:1.* <https://www.w3.org/WAI/WCAG22/Techniques/general/G17>
+
+## Cryptography
+
+- **Valsorda, F. (2020).** *age: A simple, modern and secure encryption tool.* <https://age-encryption.org/>
+- **Mozilla.** *SOPS: Secrets OPerationS.* <https://github.com/getsops/sops>
+- **Barnes, R., et al. (2023).** *RFC 9420: The Messaging Layer Security (MLS) Protocol.* — Modern group-key agreement, relevant to multi-recipient encryption.
+
+## Protocols
+
+- **Anthropic.** *Model Context Protocol specification.* <https://modelcontextprotocol.io/>
+- **OpenID Foundation.** *Model Context Protocol A2A (Agent-to-Agent).* — Referenced in `dot_config/dotfiles/agent-card.json`.
+
+## Tools & Systems
+
+- **Twpayne, T.** *chezmoi: Manage your dotfiles across multiple machines.* <https://chezmoi.io>
+- **jdxcode.** *mise: Dev tools, env vars, task runner.* <https://mise.jdx.dev/>
+- **NixOS.** *Nix Flakes.* <https://nixos.wiki/wiki/Flakes>
+- **Microsoft / CycloneDX.** *CycloneDX SBOM specification.* <https://cyclonedx.org/>
+- **Anchore.** *Syft + Grype.* <https://github.com/anchore/syft>, <https://github.com/anchore/grype>
+
+## Shell Performance
+
+- **Yoo, D.** *How to benchmark shell startup time.* <https://web.archive.org/web/2023/https://hermann.blog/benchmark-shell-startup-time>
+- **Zsh manual.** *Startup files: zshenv, zprofile, zshrc.* <https://zsh.sourceforge.io/Doc/Release/Files.html>
+
+## Documentation Systems
+
+- **GNU Stow documentation.** <https://www.gnu.org/software/stow/manual/> — Inspiration for this manual's multi-format publishing model.
+- **Pandoc.** *Universal document converter.* <https://pandoc.org/>
+- **GNU Texinfo.** <https://www.gnu.org/software/texinfo/> — The original GNU documentation system.
+
+## Author
+
+- **Rousseau, S.** *Dotfiles v0.2.500.* <https://github.com/sebastienrousseau/dotfiles>

package/docs/manual/05-appendices/E-license.md

@@ -0,0 +1,34 @@
+# Appendix E: License
+
+## MIT License
+
+Copyright (c) 2015-2026 Sebastien Rousseau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Third-Party Licenses
+
+This repository references, configures, or wraps many third-party tools. Each tool retains its own license:
+
+| Tool | License |
+|:---|:---|
+| Chezmoi | MIT |
+| Mise | MIT |
+| Nix | LGPL-2.1 |
+| Age | BSD-3-Clause |
+| SOPS | MPL-2.0 |
+| Fish shell | GPL-2.0 |
+| Zsh | Zsh License (MIT-like) |
+| Neovim | Apache-2.0 |
+| ImageMagick | ImageMagick License (Apache-2.0-like) |
+| Pandoc | GPL-2.0+ |
+
+Wallpapers referenced from `/System/Library/Desktop Pictures/` or `/usr/share/backgrounds/` retain their original vendors' licenses (Apple, Microsoft, distribution vendors). They are not redistributed by this repository — they are discovered and processed in place.
+
+## Contributions
+
+Contributions are accepted under the MIT License. By submitting a pull request, you assert that your contribution is your own work (or properly attributed) and that it may be relicensed under MIT.

package/docs/manual/_toc.yml

@@ -0,0 +1,58 @@
+# Master ordering for build-manual.sh
+# Determines concatenation order for single-page HTML/PDF/EPUB
+title: "The .dotfiles Manual"
+subtitle: "A Trusted Agent Workstation for macOS, Linux, and WSL"
+version: "0.2.500"
+
+sections:
+  - file: 00-introduction.md
+    title: "Introduction"
+
+  - group: "Concepts"
+    prefix: "01-concepts"
+    files:
+      - 01-architecture.md
+      - 02-trust-model.md
+      - 03-theme-engine.md
+      - 04-fleet.md
+      - 05-self-healing.md
+
+  - group: "Tutorials"
+    prefix: "02-tutorials"
+    files:
+      - 01-first-install.md
+      - 02-add-wallpaper.md
+      - 03-create-profile.md
+      - 04-encrypt-secret.md
+      - 05-deploy-fleet.md
+
+  - group: "Reference"
+    prefix: "03-reference"
+    files:
+      - 01-dot-cli.md
+      - 02-config-files.md
+      - 03-environment.md
+      - 04-templates.md
+      - 05-feature-flags.md
+
+  - group: "Cookbook"
+    prefix: "04-cookbook"
+    files:
+      - 01-recipes.md
+      - 02-troubleshooting.md
+      - 03-faq.md
+
+  - group: "Appendices"
+    prefix: "05-appendices"
+    files:
+      - A-platform-matrix.md
+      - B-security-checklist.md
+      - C-glossary.md
+      - D-bibliography.md
+      - E-license.md
+
+  - file: concept-index.md
+    title: "Concept Index"
+
+  - file: command-index.md
+    title: "Command Index"

package/docs/manual/command-index.md

@@ -0,0 +1,58 @@
+# Command Index
+
+Alphabetical list of `dot` subcommands referenced in the manual.
+
+- `dot agent`
+- `dot ai`
+- `dot apply --dry-run`
+- `dot apply`
+- `dot attest`
+- `dot benchmark --detailed`
+- `dot benchmark`
+- `dot bundle`
+- `dot cache-refresh`
+- `dot cd`
+- `dot chaos`
+- `dot clean-cache`
+- `dot commit`
+- `dot diff`
+- `dot doctor --json`
+- `dot doctor`
+- `dot drift`
+- `dot edit`
+- `dot env`
+- `dot fleet attest`
+- `dot fleet diff`
+- `dot fleet sync`
+- `dot fleet`
+- `dot heal`
+- `dot help`
+- `dot learn`
+- `dot lint`
+- `dot load-bench`
+- `dot manual text`
+- `dot manual`
+- `dot mcp --strict`
+- `dot mcp`
+- `dot metrics`
+- `dot mode`
+- `dot packages`
+- `dot perf`
+- `dot prewarm`
+- `dot profile`
+- `dot rollback`
+- `dot score`
+- `dot secrets rotate`
+- `dot secrets`
+- `dot status`
+- `dot sync`
+- `dot theme list`
+- `dot theme rebuild`
+- `dot theme toggle`
+- `dot theme`
+- `dot tune`
+- `dot update`
+- `dot upgrade`
+- `dot verify --security`
+- `dot verify`
+- `dot version`