@sebastienrousseau/dotfiles 0.2.501 → 0.2.503

package/README.md

@@ -5,28 +5,54 @@
 <h1 align="center">.dotfiles</h1>
 
 <p align="center">
-  <strong>Declarative dotfiles for macOS, Linux, and WSL. Multi-shell by default. Sub-second startup. Wallpaper-driven themes. Signed releases.</strong>
+  <strong>Declarative dotfiles for macOS, Linux, WSL, and Windows-native PowerShell 7.4 LTS / 7.5+. Multi-shell by default. Sub-100ms CLI cold-start. Wallpaper-driven themes. Signed + attested releases. Fleet apply over SSH.</strong>
 </p>
 
 <p align="center">
   <a href="https://github.com/sebastienrousseau/dotfiles/actions"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/dotfiles/ci.yml?style=for-the-badge&logo=github" alt="Build" /></a>
-  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.501-blue?style=for-the-badge" alt="Version" /></a>
+  <a href="https://github.com/sebastienrousseau/dotfiles/releases/latest"><img src="https://img.shields.io/badge/Version-v0.2.503-blue?style=for-the-badge" alt="Version" /></a>
   <a href="https://github.com/sebastienrousseau/dotfiles/releases"><img src="https://img.shields.io/github/downloads/sebastienrousseau/dotfiles/total?style=for-the-badge" alt="Downloads" /></a>
   <a href="https://codespaces.new/sebastienrousseau/dotfiles"><img src="https://img.shields.io/badge/Open%20in-Codespaces-blue?style=for-the-badge&logo=github" alt="Open in GitHub Codespaces" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/dotfiles?style=for-the-badge&label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard" /></a>
+  <a href="https://www.bestpractices.dev/projects/new"><img src="https://img.shields.io/badge/OpenSSF%20Best%20Practices-in%20progress-yellow?style=for-the-badge" alt="OpenSSF Best Practices" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT" /></a>
 </p>
 
 ---
 
 > **Why this is different.** You won't find these three things in `mathiasbynens/`, `holman/`, or `paulirish/`. First, wallpaper-driven terminal themes. We use K-Means clustering in CIELAB and enforce WCAG AAA contrast. Second, first-class agent governance. That covers MCP policy, A2A discovery, signed attestation logs, and bounded profiles (`ask` / `plan` / `apply` / `audit`). Third, verified multi-shell parity across zsh, fish, bash, nushell, and PowerShell. The suite is tested on macOS, Linux, WSL2, and Apple Silicon CI runners. Signed commits are enforced. The installer is idempotent. The CLI heals itself.
 
+<!-- ASCIINEMA DEMO — closes #874 once recorded.
+     30-second clip covering: install.sh → dot doctor → dot theme rebuild.
+     Recording recipe (maintainer):
+
+       asciinema rec ~/dotfiles-demo.cast \
+         --idle-time-limit 1 --rows 30 --cols 100 \
+         --title "Dotfiles: install → doctor → theme"
+       # in the recording shell:
+       #   curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/master/install.sh | bash
+       #   dot doctor
+       #   dot theme rebuild --force
+       # then Ctrl-D to stop
+
+     Upload with `asciinema upload ~/dotfiles-demo.cast`, grab the
+     resulting `https://asciinema.org/a/<id>` URL, and replace this
+     comment with:
+
+       <p align="center">
+         <a href="https://asciinema.org/a/<id>">
+           <img src="https://asciinema.org/a/<id>.svg" alt="install → doctor → theme demo" />
+         </a>
+       </p>
+-->
+
 ## Install
 
 **Verified install (recommended).** Pin to a release tag. Download the installer. Check its SHA256 against the value published with the release. Then run it. See [docs/security/INSTALL_VERIFICATION.md](docs/security/INSTALL_VERIFICATION.md) for the per-release hash and how it's generated.
 
 ```bash
 curl -fsSL -o /tmp/dotfiles-install.sh \
-  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.501/install.sh
+  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.503/install.sh
 echo "4c0303a2d88d5aed98428ab0da37618c9795af4dae0e6549646c2fce5235c280  /tmp/dotfiles-install.sh" \
   | shasum -a 256 -c
 bash /tmp/dotfiles-install.sh
@@ -80,10 +106,10 @@ Most dotfiles repos are personal collections. This one ships as workstation infr
 |:---|:---|:---|
 | **Wallpaper-driven themes** | K-Means clustering in CIELAB extracts terminal palettes from any wallpaper. WCAG AAA enforced. Dynamic HEIC dark/light. | `dot theme rebuild` |
 | **AI and MCP native** | Agent profiles, MCP policy enforcement, attestation logs, AI commit messages. | `dot ai`, `dot mcp`, `dot agent`, `dot mode` |
-| **Cryptographic attestation** | Signed commits, machine-readable evidence, policy bundle releases. | `dot attest`, `dot verify` |
+| **Cryptographic attestation** | Signed commits, machine-readable evidence, policy bundle releases. | `dot attest`, `dot secrets verify` |
 | **Fleet management** | Multi-node drift dashboard, per-host profiles. | `dot fleet` |
 | **Self-healing** | Auto-repair tools, chezmoi drift, broken symlinks, missing files. | `dot heal`, `dot chaos`, `dot rollback`, `dot bundle` |
-| **Sub-second startup** | Lazy loading, `_cached_eval` pattern, mtime-based cache invalidation, realpath sidecar pins. | `dot benchmark`, `dot perf` |
+| **Sub-second startup** | Lazy loading, `_cached_eval` pattern, mtime-based cache invalidation, realpath sidecar pins. | `dot perf`, `dot health` |
 | **Multi-shell parity** | Tier-1 (full): zsh, bash. Tier-2 (bridged): fish. Tier-3 (compatible): nushell. PowerShell is supported as a contract-tested parity target. See [ADR-007](docs/adr/ADR-007-multi-shell-parity.md) and [ADR-011](docs/adr/ADR-011-nushell-tier3-keep.md). | `dot env`, `dot profile` |
 | **Build artifacts → /tmp** | Cargo, Go, pip, uv, and Zig caches redirect to `/tmp/builds/`. Project dirs stay clean. | `~/.config/mise/config.toml`, `~/.cargo/config.toml` |
 | **Encrypted secrets** | Age and SOPS keep per-machine secrets out of plaintext history. | `dot secrets` |
@@ -153,9 +179,15 @@ Over 80 commands grouped by intent. Run `dot help` for the full reference.
 
 | | |
 |:---|:---|
+| `dot init <user>` | Bootstrap any GitHub user's dotfiles repo through this harness |
 | `dot sync` | Apply dotfiles to this machine |
 | `dot doctor` | Check the environment and surface issues |
 | `dot learn` | Open the guided tour |
+| `dot agents render` | Sync `CLAUDE.md` → `AGENTS.md` + Cursor + Codex stubs |
+| `dot fleet apply` | SSH out to every host in `~/.config/dotfiles/fleet.toml` |
+| `dot registry list` | Browse reusable dotfile modules from the registry |
+
+A [Claude Code skill](defaults/dot_claude/skills/dotfiles-bootstrap/SKILL.md) is also shipped — `/skills` discovers `dotfiles-bootstrap` and runs `dot init` with profile-aware safety defaults.
 
 ### Daily Use
 
@@ -201,9 +233,9 @@ Over 80 commands grouped by intent. Run `dot help` for the full reference.
 | | |
 |:---|:---|
 | `dot fleet` | Multi-node status, drift, and namespace |
-| `dot benchmark` / `dot perf` | Measure shell startup |
+| `dot perf` | Measure shell startup |
 | `dot score` / `dot security-score` | Health and security scorecards |
-| `dot prewarm` | Warm caches for the first interactive shell |
+| `dot health` | Live dashboard for caches and tool state |
 
 Full reference: [docs/reference/UTILS.md](docs/reference/UTILS.md) · Complete manual: [docs/manual/](docs/manual/) or `dot manual`
 
@@ -227,7 +259,7 @@ The `.dotfiles` Manual is published in nine formats: HTML (single and multi-page
 2. **Explore** — `dot learn` walks through shells, secrets, themes, and performance
 3. **Customize** — edit `~/.config/chezmoi/chezmoi.toml` for per-machine settings ([Profiles](docs/reference/PROFILES.md))
 4. **Toggle features** — flip features in `.chezmoidata.toml` ([Feature Flags](docs/reference/FEATURES.md))
-5. **Apply** — `dot sync` applies the config and `dot prewarm` caches shell startup
+5. **Apply** — `dot sync` applies the config and the next interactive shell hydrates caches via `_cached_eval`
 
 See the [Migration Guide](docs/operations/MIGRATION.md) for version upgrades.
 

package/docs/CONFIG_STRATEGY.md

@@ -0,0 +1,124 @@
+# Configuration Management Strategy
+
+## Overview
+
+This document defines the configuration management approach for this development environment, consolidating multiple systems into a clear hierarchy.
+
+## Configuration Systems
+
+### Primary: Chezmoi
+
+**Role:** Source of truth for all managed dotfiles
+**Location:** `~/.dotfiles/` (chezmoi source directory)
+**Managed Files:** 209 files/directories
+
+Chezmoi handles:
+
+- Shell configurations (.bashrc, .zshrc, .profile, .zshenv, .zprofile)
+- Editor configs (.vimrc, nvim, VS Code settings)
+- Tool configs (.gitconfig, .npmrc, .noderc, etc.)
+- Application configs (~/.config/*)
+- SSH configuration (~/.ssh/config, config.d/)
+
+
+### Tertiary: Runtime/Application Data
+
+**Role:** Auto-generated, not version controlled
+**Examples:**
+
+- `~/.cache/` - Application caches
+- `~/.local/share/` - Application data
+- `~/.cargo/`, `~/.rustup/` - Language toolchains
+- `~/.npm/`, `~/.node_modules/` - Node.js packages
+
+## Decision Matrix
+
+| Configuration Type | Manager | Reason |
+|-------------------|---------|--------|
+| Shell dotfiles | Chezmoi | Templated, machine-specific |
+| Editor configs | Chezmoi | Consistent across machines |
+| Git config | Chezmoi | Templated (email, signing key) |
+| SSH config | Chezmoi | Structured with config.d/ |
+| Euxis framework | Git (separate) | Independent lifecycle |
+| Language runtimes | mise | Version management |
+| System packages | apt/snap | OS-level |
+| Application data | None | Auto-generated |
+
+## Chezmoi Configuration
+
+### Data Variables (.chezmoidata.toml)
+
+```toml
+profile = "laptop"           # Machine profile
+theme = "tokyonight-night"   # Color scheme
+terminal_font_family = "JetBrains Mono"
+terminal_font_size = 12
+
+[features]
+zsh = true      # Enable zsh configs
+nvim = true     # Enable neovim configs
+tmux = true     # Enable tmux configs
+gui = true      # Enable GUI app configs
+secrets = true  # Enable secret management
+```
+
+### Template Patterns
+
+Files ending in `.tmpl` are processed with Go templates:
+
+- `dot_gitconfig.tmpl` - Injects name, email, signing key
+- `dot_npmrc.tmpl` - Injects registry tokens
+- `dot_noderc.tmpl` - Injects Node.js settings
+
+### Ignored Patterns (.chezmoiignore.tmpl)
+
+Machine-specific exclusions based on profile and features.
+
+## Workflow
+
+### Adding New Configuration
+
+1. **Check if managed:** `chezmoi managed | grep <file>`
+2. **If not managed:** `chezmoi add <file>`
+3. **If templating needed:** Rename to `.tmpl`, add template logic
+4. **Apply changes:** `chezmoi apply`
+
+### Updating Configuration
+
+1. **Edit source:** `chezmoi edit <file>` or edit in `~/.dotfiles/`
+2. **Preview changes:** `chezmoi diff`
+3. **Apply:** `chezmoi apply`
+4. **Commit:** `cd ~/.dotfiles && git add -A && git commit`
+
+### Syncing Across Machines
+
+```bash
+# On new machine
+chezmoi init https://github.com/<user>/dotfiles.git
+chezmoi apply
+
+# On existing machine
+chezmoi update
+```
+
+## Anti-Patterns to Avoid
+
+1. **Manual edits to managed files** - Always edit via chezmoi or re-add after manual changes
+2. **Duplicate configs** - Don't maintain parallel configs outside chezmoi
+3. **Hardcoded machine-specific values** - Use templates and data variables
+4. **Version controlling runtime data** - Keep ~/.cache, ~/.local/share out of version control
+
+## File Ownership
+
+| Path | Owner | Notes |
+|------|-------|-------|
+| `~/.dotfiles/` | chezmoi | Source of truth |
+| `~/.*` (dotfiles) | chezmoi-applied | Don't edit directly |
+| `~/.config/*` | Mixed | Check `chezmoi managed` |
+| `~/.local/` | chezmoi (bin) + runtime | Partial management |
+
+## Maintenance Schedule
+
+- **Weekly:** `chezmoi update` to sync remote changes
+- **Monthly:** Review `chezmoi unmanaged` for new configs to add
+- **Quarterly:** Audit `.chezmoiignore` patterns

package/docs/COPYRIGHT

@@ -1,5 +1,5 @@
 /*
-* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.501) - <https://github.com/sebastienrousseau/dotfiles>
+* 🅳🅾🆃🅵🅸🅻🅴🆂 (v0.2.503) - <https://github.com/sebastienrousseau/dotfiles>
 * Made With ❤️ in London, United Kingdom
 * Designed by
 * Copyright (c) 2015-2026. All rights reserved.

package/docs/GOVERNANCE.md

@@ -0,0 +1,98 @@
+# Governance
+
+## Model
+
+**Single-maintainer steward.** The project is owned and decided
+by one maintainer (see [`MAINTAINERS.md`](MAINTAINERS.md)). This document exists so
+contributors and downstream consumers understand exactly how
+decisions are made, how to influence them, and what guarantees
+exist.
+
+## Decision-making
+
+| Decision class | Process | Veto |
+|---|---|---|
+| Bug fix | Open PR, maintainer reviews + merges. Tests required. | Maintainer |
+| Feature addition | Open issue first to scope. Then PR. Larger changes need an RFC in `docs/operations/`. | Maintainer |
+| Breaking change | RFC in `docs/operations/RFC_<topic>.md` + 2-week comment window + migration script + at least one minor-version deprecation. | Maintainer (with public reasoning) |
+| Security policy | `.github/SECURITY.md` is the canonical reference. Disclosure-key rotation follows `docs/security/KEY_ROTATION.md`. | Maintainer + 30-day public notice |
+| Dependency change | Pre-commit + CI must stay green. New runtime deps require RFC. | Maintainer |
+| Release | Maintainer cuts tags. Convention: signed annotated tag, Cosign-signed SBOM, SLSA L3 provenance. | Maintainer |
+
+## Contribution flow
+
+1. **Issue** for non-trivial work. Confirm scope before coding.
+2. **Branch** off `master`: `feat/<scope>`, `fix/<scope>`,
+   `docs/<scope>`, etc.
+3. **PR** with description following the template:
+   - Summary (1–3 bullets)
+   - Test plan (checklist)
+   - Trailing Euxis signature block (required by
+     `pr-signature.yml`)
+4. **CI** must pass before merge. Pre-commit hooks must not be
+   bypassed (`--no-verify` is rejected by the pre-push hook).
+5. **Review** by the maintainer. Squash-merge is the project
+   default; merge-commit only for release PRs that need history
+   preserved (e.g., `feat/v0.X.YYY` aggregate PRs).
+6. **Commit signing** is mandatory: SSH or GPG. Unsigned commits
+   are rejected at push.
+
+See `CONTRIBUTING.md` for full code-style + commit-message
+requirements.
+
+## RFC process
+
+For breaking changes or substantial new features:
+
+1. Create `docs/operations/RFC_<short-name>.md` with sections:
+   - **Summary** (one paragraph)
+   - **Motivation** (why now, what's broken without it)
+   - **Detailed design** (concrete file paths, API shapes)
+   - **Backwards compatibility** (what breaks, migration path)
+   - **Alternatives considered** (with reasons rejected)
+   - **Unresolved questions**
+2. Open a PR labelled `rfc` against `master`.
+3. Comment window: 14 days minimum.
+4. Maintainer renders a decision (accept / accept-with-changes /
+   reject) with public reasoning in the PR.
+5. Accepted RFCs are merged as-is to `docs/operations/` and become
+   the implementation reference.
+
+Active and historical RFCs are linked from
+`docs/operations/README.md`.
+
+## Code of conduct
+
+Standard expectations: be kind, assume good faith, focus on the
+work. Discriminatory or harassing behaviour is grounds for
+permanent block. Report incidents to the maintainer via the
+security disclosure channel (`security@sebastienrousseau.com`,
+encrypted to the WKD-published GPG key).
+
+## Forking
+
+The project is MIT-licensed; fork freely. If your fork diverges
+substantially and gains its own community, please rename it to
+avoid downstream confusion ("dotfiles-X" or similar).
+
+## Sustainability
+
+The single-maintainer model has known weaknesses (bus factor,
+review bandwidth, perspective). The project mitigates these by:
+
+- **Comprehensive automation**: 75+ CI checks, pre-commit hooks,
+  shellcheck/shfmt/typos enforcement.
+- **Documented architecture**: [`STRUCTURE.md`](STRUCTURE.md), `scripts/README.md`,
+  `architecture/`, `operations/HARD_AUDIT_2026.md`.
+- **Cryptographic supply chain**: Cosign-signed SBOMs, SLSA L3
+  provenance, signed commits, WKD-published disclosure key.
+- **Permissive license**: MIT — anyone can fork and continue.
+- **Active issue triage**: targeted weekly cadence.
+
+When the project gains regular contributors, this document will be
+updated to reflect the shared-maintainer model.
+
+## Reference
+
+- [OpenSSF Best Practices criteria](https://www.bestpractices.dev/en/criteria/0) — this governance model is designed to satisfy the "passing" tier.
+- [CNCF Project Governance template](https://contribute.cncf.io/maintainers/governance/) — adapted for solo maintainership.

package/docs/MAINTAINERS.md

@@ -0,0 +1,41 @@
+# Maintainers
+
+This project is maintained by a single primary maintainer with an
+explicit, documented governance model (see [`GOVERNANCE.md`](GOVERNANCE.md)).
+
+## Primary maintainer
+
+- **Sebastien Rousseau** — <sebastian.rousseau@gmail.com>
+  - GitHub: [@sebastienrousseau](https://github.com/sebastienrousseau)
+  - Role: project owner, release manager, security disclosure contact
+  - Commit signing: SSH ED25519 (`SHA256:kIOPAavp1TCEauTr1tTIN3cv+tSs6F9m/4lZjuM9tqk`)
+  - GPG disclosure key fingerprint: `55AFAD364FD9DB3819E61F0C8D688FAFA9144693` (ed25519 + cv25519, expires 2029-05-15, published via WKD at `security@sebastienrousseau.com`)
+
+## Active contributors
+
+This is a solo-maintained project. Contributions are welcomed via
+pull request (see `CONTRIBUTING.md`); the maintainer reviews and
+merges. When the project gains additional regular committers their
+names will land here with role and contact.
+
+## Security contact
+
+For coordinated vulnerability disclosure, follow `.github/SECURITY.md`.
+TL;DR: encrypt your report to the WKD-published GPG key above and
+email `security@sebastienrousseau.com`. Acknowledgement SLA: 72 hours.
+
+## Backup / continuity
+
+In the event the primary maintainer becomes unable to maintain the
+project, the repository is published under the MIT license and may
+be forked. The `chezmoi`-based architecture means existing user
+installs continue to work indefinitely without upstream activity.
+
+## Releases
+
+| Release author | Cadence | Signing |
+|---|---|---|
+| Primary maintainer | ~weekly | Signed annotated git tag + Cosign-signed SBOM + SLSA L3 provenance |
+
+See `docs/operations/HARD_AUDIT_2026.md` Part 7 for the
+disclosure-key generation + WKD publication record.

package/docs/OPENCODE.md

@@ -0,0 +1,127 @@
+<!--
+  Role:     Repo-scoped instructions for the OpenCode CLI when operating
+            inside this repository. Mirrors CLAUDE.md but targets OpenCode's
+            conventions/discovery.
+  Audience: OpenCode, this repo only.
+
+  Distinct from:
+    - CLAUDE.md           — same intent, but for Claude Code.
+    - dot_claude/CLAUDE.md — PERSONAL cross-project Claude Code preferences,
+                             deployed to ~/.claude/CLAUDE.md by chezmoi.
+
+  Keep CLAUDE.md and OPENCODE.md in sync on repo-level conventions (layout,
+  naming, CI, testing). If they drift, CLAUDE.md is the source of truth.
+-->
+
+# OPENCODE.md — AI Assistant Guidelines for Dotfiles Repository
+
+## Chezmoi Source Directory Conventions
+
+This is a **chezmoi-managed** dotfiles repository. Files here are *source templates*,
+not the deployed config files. Understanding the naming conventions is critical.
+
+### File Naming Rules
+
+| Prefix/Suffix    | Meaning                                              |
+|------------------|------------------------------------------------------|
+| `dot_`           | Deployed with a leading `.` (e.g., `dot_zshrc` -> `.zshrc`) |
+| `executable_`    | Deployed with `+x` permission                        |
+| `private_`       | Deployed with `0600` permissions                      |
+| `.tmpl`          | **Go template** — processed by chezmoi before deployment |
+| `run_onchange_`  | Script that runs when the target file changes         |
+| `encrypted_`     | Age-encrypted file, decrypted at deploy time          |
+
+### Critical: Template vs Non-Template Files
+
+Many shell config files exist **only** as `.tmpl` variants. When reading files:
+
+- `dot_config/shell/00-core-paths.sh` does **NOT** exist
+- `dot_config/shell/00-core-paths.sh.tmpl` **DOES** exist (this is the source)
+
+**Rule**: If a `.sh` or `.zsh` file is not found, always try appending `.tmpl`.
+
+Files that are templates (use Go template syntax like `{{ .variable }}`):
+
+- `dot_config/shell/*.sh.tmpl` — all shell layer files
+- `dot_config/zsh/dot_zshrc.tmpl` — main zsh config
+- `dot_config/zsh/rc.d/*.tmpl` — zsh startup modules
+- `dot_gitconfig.tmpl` — git configuration
+- `private_dot_ssh/config.tmpl` — SSH configuration
+- `dot_npmrc.tmpl` — npm configuration
+- `private_dot_netrc.tmpl` — netrc credentials
+
+Files that are **NOT** templates (plain files, no `.tmpl` suffix):
+
+- `dot_config/shell/00-container-detect.sh` — plain shell script
+- `dot_config/shell/90-theme-switch.sh` — plain shell script
+- `dot_config/zsh/rc.d/00-alias-shims.zsh` — plain zsh
+- `dot_config/zsh/rc.d/05-ssh-agent.zsh` — plain zsh
+- Most files under `dot_config/nvim/`, `dot_config/starship.toml.tmpl`, etc.
+
+### Reading Template Files
+
+Template files contain Go template directives like:
+
+```
+{{ if eq .chezmoi.os "darwin" }}
+  # macOS-specific config
+{{ end }}
+```
+
+Data variables come from `.chezmoidata.toml` (profiles, features, theme, tools).
+User-specific values (git identity, age keys) come from `~/.config/chezmoi/chezmoi.toml`.
+
+### Repository Layout
+
+```
+.chezmoidata.toml           # Feature flags, profiles, version
+.chezmoitemplates/          # Reusable template partials (aliases, functions, paths)
+dot_config/                 # XDG configs (~/.config/*) — largest directory
+  zsh/                      # Zsh configuration
+    dot_zshrc.tmpl          # Main zsh orchestrator
+    rc.d/                   # Startup modules (sourced in order)
+  shell/                    # POSIX shell layers (paths, safety, aliases, functions)
+  nvim/                     # Neovim configuration (Lua)
+  mise/                     # mise version manager config
+  starship.toml.tmpl        # Starship prompt config
+  atuin/                    # Atuin shell history
+  bat/                      # bat (cat replacement) config
+  ghostty/                  # Ghostty terminal config
+  kitty/                    # Kitty terminal config
+  alacritty/                # Alacritty terminal config
+dot_local/bin/              # User scripts (~/.local/bin)
+scripts/                    # Repo-only scripts (tests, ops, security, diagnostics)
+docs/                       # Documentation (30+ files)
+install.sh                  # Bootstrap installer
+```
+
+### Shell Startup Chain
+
+```
+~/.zshenv (dot_zshenv)           → XDG vars, PATH, ZDOTDIR
+~/.config/zsh/.zshrc (dot_zshrc.tmpl) → Main orchestrator
+  → rc.d/00-alias-shims.zsh     → Single-letter fallback commands
+  → rc.d/05-ssh-agent.zsh       → SSH agent + YubiKey
+  → rc.d/10-env.zsh.tmpl        → Environment variables
+  → rc.d/20-zinit.zsh.tmpl      → Plugin manager (deferred)
+  → rc.d/30-options.zsh.tmpl    → History, keybindings, completions
+  → rc.d/40-bell.zsh.tmpl       → Bell settings
+  → rc.d/50-login-fortune.zsh.tmpl → Login greeting
+  → shell/00-core-paths.sh.tmpl → Full PATH construction
+  → shell/05-core-safety.sh.tmpl → Safety defaults
+  → shell/90-ux-aliases.sh.tmpl → Core aliases (eager)
+  → [deferred] mise, atuin, starship, zoxide, fzf
+  → [lazy] shell/91-ux-aliases-lazy.sh.tmpl → Tool aliases
+```
+
+### Key Data Files
+
+- `.chezmoidata.toml` — All configuration: profiles, feature flags, tool settings
+- `dot_config/mise/config.toml` — mise tool versions (node, python, go, rust, etc.)
+- `dot_config/starship.toml.tmpl` — Prompt configuration
+
+### Testing
+
+- Test framework: `tests/framework/`
+- Unit tests: `tests/unit/`
+- Tests execute bash source files directly — they do NOT use Go template syntax

package/docs/README.md

@@ -54,6 +54,8 @@ Quick jumps into the Manual:
 - [Naming conventions](NAMING_CONVENTIONS.md)
 - [Architecture](architecture/ARCHITECTURE.md)
 - [Repository layout](architecture/REPO_LAYOUT.md)
+- [AI cost optimization](architecture/AI_COST_OPTIMIZATION.md)
+- [Release pipeline](operations/RELEASE_PIPELINE.md)
 - [Architecture decisions](adr/README.md)
 
 ## Repository map

package/docs/STRUCTURE.md

@@ -0,0 +1,102 @@
+# Repository Structure
+
+This document maps every top-level path in the repository to its
+purpose. Skim it once and you should be able to answer:
+
+- **Where is the `dot` CLI?** → `bin/dot` (the source-of-truth file). At runtime it lives at `~/.local/bin/dot`.
+- **Why are there 20+ `dot_*` files at root?** → chezmoi convention: a `dot_X` source file deploys to `~/.X` on apply. Same for `executable_*` (gains `+x`), `private_*` (`0600`), `run_onchange_*` (re-runs when source changes).
+- **What's the framework vs. the maintainer's personal config?** → Everything under `scripts/`, `install/`, `tools/`, `lib/`, and `defaults/.chezmoitemplates/` is framework code. Everything under `defaults/dot_config/`, `defaults/dot_warp/`, `defaults/private_dot_ssh/` is user-facing default configuration (chezmoi auto-rebases via `.chezmoiroot`).
+
+The Debian/aws-cli-style root layout shipped in **v0.2.503**:
+`bin/` (dispatcher), `lib/` (shared bash libs), `defaults/`
+(all chezmoi-tracked source files, rebased via
+`.chezmoiroot`). Repo root now hosts only project/CI/docs paths.
+See `docs/operations/ROADMAP_V0_2_503.md` for the full history.
+
+---
+
+## Top-level paths
+
+| Path | Kind | Purpose |
+|------|------|---------|
+| **CLI + framework** | | |
+| `dot_local/bin/` | framework | `executable_dot` (CLI entrypoint) and helper scripts. Deploys to `~/.local/bin/`. |
+| `dot_local/share/` | framework | Man pages, zsh completions. Deploys to `~/.local/share/`. |
+| `scripts/` | framework | Runtime-invoked scripts (`dot` CLI dispatch + specialised subtrees). See `scripts/README.md`. |
+| `tools/` | repo-ops | Repo-only ops: CI helpers, release, maintenance, docs-generation. Not distributable. See `tools/README.md`. |
+| `lib/dot/` | framework | Shared bash library sourced by every `dot` subcommand and the dispatcher. Reorganised here from `scripts/dot/lib/` per RFC Phase 1. See `lib/dot/README.md`. |
+| `lib/` | framework | Library tree (`lib/dot/` + third-party `lib/wasm-tools/`). |
+| `install/` | framework | Bootstrap logic + distribution-channel manifests (`homebrew/`, `scoop/`, `aur/`). See `install/README.md`. `install/provision/` runs on `chezmoi apply` via `run_onchange_*` triggers. |
+| `install.sh` | framework | Top-level installer. SHA256-verified chezmoi fetch + initial apply. |
+| `.chezmoitemplates/` | framework | Reusable Go-template partials (aliases, functions, paths). Sourced by `dot_*.tmpl` files. |
+| **User-facing defaults** | | |
+| `dot_bashrc`, `dot_zshrc`, `dot_zshenv`, `dot_zprofile`, `dot_profile`, `dot_vimrc`, etc. | defaults | Shell + editor rc files. Deploy to `~/.X`. |
+| `dot_config/` | defaults | XDG config (`~/.config/*`). Largest tree — 80+ tool configs. |
+| `dot_local/` (non-bin/share) | defaults | Per-user state files for tools (`dot_local/state/`, etc.). |
+| `dot_cargo/`, `dot_etc/`, `dot_warp/` | defaults | Tool-specific roots (cargo, system etc, Warp terminal). |
+| `private_dot_ssh/` | defaults | SSH config — chezmoi `private_` prefix forces 0600. Does NOT contain private keys. |
+| `dot_claude/` | defaults | Claude Code per-user skills and config. |
+| **Templates + data** | | |
+| `templates/` | framework | Non-chezmoi templates (e.g. for `dot agents render`). |
+| `.chezmoidata/` | data | Hardware presets (`macbook-t2`, `surface-pro`) read by templates. |
+| `.chezmoidata.toml` | data | Feature flags + version. Single source-of-truth for `dotfiles_version`. |
+| `.chezmoi.toml.tmpl` | framework | Per-host chezmoi config generated on first apply. |
+| `.chezmoiignore` / `.chezmoiignore.tmpl` | framework | Tells chezmoi which paths NOT to deploy. |
+| **Docs + tests** | | |
+| `docs/` | docs | All documentation: `manual/` (user guide), `operations/` (audits, roadmaps), `reference/` (lookup tables), `security/`. |
+| `tests/` | tests | Test suite: `framework/` (runner + assertions + mocks), `unit/`, `integration/`, `regression/`, `fuzz/`, `snapshots/`. |
+| `examples/` | docs | Standalone examples (mise plugin, AI patterns, ops scripts). |
+| **CI + release** | | |
+| `.github/` | ci | GitHub Actions workflows + issue/PR templates + repo-level SECURITY/CODEOWNERS. |
+| `.devcontainer/` | ci | Dev Container spec for reproducible contributor onboarding. |
+| `Dockerfile.test` | ci | Container baseline for the CI test job. |
+| `.pre-commit-config.yaml` → `config/pre-commit-config.yaml` | ci | Pre-commit hooks (shellcheck, shfmt, luacheck, gitleaks, typos, conventional-commits). |
+| `flake.nix` / `flake.lock` | ci | Nix flake for reproducible dev shell. |
+| `mise.toml` / `mise-versions.lock.json` | ci | Pinned tool versions (mise as the package manager). |
+| **Misc + agents** | | |
+| `AGENTS.md` | docs | Cross-harness AI agent context (the standard read by Codex/Cursor/etc.). |
+| `.cursor/`, `.codex/`, `.windsurf/`, `.zed/`, `.roo/`, `.clinerules`, `.aider.conf.yml`, `.continuerc.json`, `.jules/`, `.gemini/` | agents | Per-harness AGENTS.md renderings. Generated by `dot agents render`. Each one points back at `CLAUDE.md` as canonical. |
+| `CLAUDE.md` | docs | Project guidelines (the canonical source — `dot agents render` propagates it). |
+| `CONTRIBUTING.md` | docs | Contributor guide (must stay at root for GitHub auto-discovery). |
+| `docs/CONFIG_STRATEGY.md`, `docs/OPENCODE.md` | docs | Strategy + OpenCode-CLI guidance. Moved out of root for cleanliness in v0.2.503. |
+| `README.md` / `CHANGELOG.md` / `LICENSE` | docs | Standard project files. |
+| `Justfile.tmpl` / `Makefile` | dev | Task runners. |
+| `dist/` | build | Build artefacts directory. |
+| `coverage/`, `nightly-reports/` | build | CI output directories (gitignored). |
+| `nix/` | build | Nix flake source. |
+| `.well-known/` | misc | RFC-compliant `.well-known/` content (currently used for WKD GPG key publication). |
+| `.version-sync-backup/` | misc | Backup directory used by `scripts/version-sync.sh` during release prep. |
+
+## Chezmoi naming contract
+
+| Prefix / suffix | Effect on deployment |
+|---|---|
+| `dot_foo` | Deploys as `.foo` (the `dot_` is consumed). |
+| `executable_foo` | Adds `+x` permission. |
+| `private_foo` | Sets `0600` permission. |
+| `run_onchange_foo.sh` | Script re-executes when its hash changes. |
+| `*.tmpl` | Processed as a Go template with chezmoi data before deployment. |
+
+**Critical gotcha:** `executable_dot_foo` deploys as `.foo` (not
+`dot_foo`). The `dot_` prefix is consumed by chezmoi after the
+`executable_` prefix. Renaming a deployed file silently can leave
+stale state in `~/.config/chezmoi/`.
+
+## Where to make changes
+
+| Goal | File(s) to edit |
+|------|----------------|
+| Add a new `dot <subcommand>` | `scripts/dot/commands/<subcommand>.sh` + dispatch in `bin/dot` + entry in `docs/manual/03-reference/01-dot-cli.md` + entry in `docs/manual/command-index.md`. |
+| Change an alias | `.chezmoitemplates/aliases/<file>.aliases.sh` (sourced by `dot_zshrc.tmpl`, etc.). |
+| Add a feature flag | `[features]` block in `.chezmoidata.toml` + doc entry in `docs/manual/03-reference/05-feature-flags.md`. |
+| Add a new file deployed to `~/.X` | Create `dot_X` at root (or under a chezmoi-managed subtree). |
+| Add a new chezmoi template | `dot_X.tmpl` at root, then use `{{ }}` for chezmoi data. |
+| Add a CI workflow | `.github/workflows/<name>.yml`. |
+| Add a test | `tests/unit/<domain>/test_<name>.sh` or `tests/integration/test_<name>.sh`. |
+
+## See also
+
+- `scripts/README.md` — map of the `scripts/` subtree.
+- `CONTRIBUTING.md` — code-style + commit-message + signing requirements.
+- `CLAUDE.md` — AI-assistant guidelines (the canonical source for `dot agents render`).
+- `docs/operations/ROADMAP_V0_2_503.md` — current release scope, including the v0.2.503 reorganisation plan.

package/docs/adr/ADR-011-nushell-tier3-keep.md

@@ -137,8 +137,8 @@ plugin system, bash bridge for aliases) await an actual user request.
 
 ## References
 
-- [`dot_config/nushell/cached_eval.nu`](../../dot_config/nushell/cached_eval.nu) — the new module.
-- [`dot_config/nushell/env.nu.tmpl`](../../dot_config/nushell/env.nu.tmpl) — adopter.
+- [`dot_config/nushell/cached_eval.nu`](../../defaults/dot_config/nushell/cached_eval.nu) — the new module.
+- [`dot_config/nushell/env.nu.tmpl`](../../defaults/dot_config/nushell/env.nu.tmpl) — adopter.
 - ADR-007 (Multi-Shell Parity Strategy) — establishes the tier definitions.
 - ADR-002 (Shell Performance Optimization Strategy) — establishes `_cached_eval` semantics this module ports.
 - Issue [#880](https://github.com/sebastienrousseau/dotfiles/issues/880).