@sebastienrousseau/dotfiles 0.2.502 → 0.2.503

package/README.md

@@ -10,10 +10,12 @@
 
 <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.502-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>
 
 ---
@@ -50,7 +52,7 @@
 
 ```bash
 curl -fsSL -o /tmp/dotfiles-install.sh \
-  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.502/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
@@ -185,7 +187,7 @@ Over 80 commands grouped by intent. Run `dot help` for the full reference.
 | `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](dot_claude/skills/dotfiles-bootstrap/SKILL.md) is also shipped — `/skills` discovers `dotfiles-bootstrap` and runs `dot init` with profile-aware safety defaults.
+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
 

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.502) - <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).