@sebastienrousseau/dotfiles 0.2.501 → 0.2.503

package/docs/operations/MAINTENANCE.md

@@ -46,7 +46,7 @@ For every release update:
 6. Local apply has completed:
 
 ```bash
-CHEZMOI_SOURCE_DIR="$HOME/.dotfiles" ./dot_local/bin/executable_dot apply
+CHEZMOI_SOURCE_DIR="$HOME/.dotfiles" ./bin/dot apply
 ```
 
 ## Security Scan Guardrails
@@ -54,10 +54,10 @@ CHEZMOI_SOURCE_DIR="$HOME/.dotfiles" ./dot_local/bin/executable_dot apply
 We prevent gitleaks historical-scan regressions with:
 
 - Shallow checkout (`fetch-depth: 1`, `fetch-tags: false`) in gitleaks jobs.
-- A workflow-dispatch guard script: `scripts/ci/guard-gitleaks-checkout.sh`.
+- A workflow-dispatch guard script: `tools/ci/guard-gitleaks-checkout.sh`.
 
 **Manual verification:**
 
 ```bash
-bash scripts/ci/guard-gitleaks-checkout.sh
+bash tools/ci/guard-gitleaks-checkout.sh
 ```

package/docs/operations/MANIFEST.md

@@ -0,0 +1,127 @@
+---
+title: "Workstation Environment Manifest"
+date: 2026-05-17
+---
+
+# Workstation Environment Manifest
+
+`dot env emit` produces a portable, schema-validated record of
+"what is installed on this machine" — the canonical input that
+downstream tooling consumes.
+
+## Schema
+
+[`docs/schema/dot-env-v1.json`](../schema/dot-env-v1.json) is a
+JSON Schema 2020-12 file. Validate any manifest against it with:
+
+```sh
+dot env emit | jsonschema -i /dev/stdin docs/schema/dot-env-v1.json
+# or
+dot env emit | check-jsonschema --schemafile docs/schema/dot-env-v1.json /dev/stdin
+```
+
+(`jsonschema` from the `jsonschema` PyPI package; `check-jsonschema`
+from `python-jsonschema/check-jsonschema`. Either works.)
+
+## Quick reference
+
+```sh
+dot env emit                              # canonical JSON to stdout
+dot env emit --format ndjson              # one tool per line, greppable
+dot env emit --output /tmp/env.json       # atomic file write
+dot env emit --compact                    # one-line JSON
+dot env emit --help                       # flags + examples
+```
+
+Example output (truncated):
+
+```json
+{
+  "schema_version": "https://sebastienrousseau.github.io/dotfiles/schema/dot-env-v1.json",
+  "manifest_version": "1.0.0",
+  "emitted_at": "2026-05-17T10:22:46Z",
+  "emitter": {
+    "name": "dot env emit",
+    "version": "0.2.503",
+    "repo": "github.com/sebastienrousseau/dotfiles"
+  },
+  "host": {
+    "hostname": "rousseau-mbp-m1",
+    "os": "Darwin",
+    "arch": "arm64"
+  },
+  "tools": [
+    {
+      "name": "node",
+      "version": "24.14.0",
+      "source": "/Users/seb/.dotfiles/mise.toml",
+      "source_type": "mise.toml",
+      "requested_version": "24.14.0",
+      "install_path": "/Users/seb/.local/share/mise/installs/node/24.14.0",
+      "active": true
+    },
+    ...
+  ]
+}
+```
+
+## Why this exists
+
+R3 §7.4 strategic-reversal call: **ship `dot env emit` BEFORE
+`dot fleet apply --attest`**. Three independent forces converge on
+a 2026-09-17 / 2026-09-11 window:
+
+1. **AgentSpec / AAIF** public deadline at AGNTCon Amsterdam
+   2026-09-17. First-mover with the canonical "one signed
+   manifest → AGENTS.md, agent.yaml, devcontainer-feature.json,
+   mise.toml, Brewfile, flake.nix, in-toto subject list"
+   generator owns the reference implementation.
+2. **EU CRA SBOM reporting** binding 2026-09-11. A v1 manifest
+   per workstation feeds the "demonstrate vulnerability response"
+   story for any EU procurement team.
+3. **dotbot v3.5.0's `workflow.yaml`** is 80% of the way to
+   AgentEnv parity. The window before they generate the same
+   manifest is measured in weeks.
+
+## Downstream consumers (planned)
+
+The v1 manifest is the source-of-truth that subsequent emitters
+will re-render. Each emitter is a single jq filter from the v1
+shape:
+
+| Target format | Use case | Status |
+|---|---|---|
+| `AGENTS.md` | Cross-harness AI agent context | shipped (`dot agents render`); will be re-pointed at the v1 manifest in v0.2.504 |
+| `devcontainer-feature.json` | Reproducible cloud-IDE setup | planned (v0.2.504) |
+| `mise.toml` | Round-trip: re-create the same install set on a fresh host | planned |
+| `Brewfile` | Hand off to a Homebrew-managed Mac | planned |
+| `flake.nix` | Nix reproducibility | planned (input to nix-shell) |
+| `in-toto subject list` | SLSA attestation subject array | planned (`dot fleet apply --attest`) |
+| `CycloneDX SBOM` | Compliance reporting (EU CRA) | planned (v0.2.504; per-artifact attestation closes R3-N7) |
+
+The schema is intentionally minimal — `dot env emit` records *what
+is installed*, not *what is desired* or *what is approved*. Downstream
+emitters add policy / approval / risk-score columns as they need
+them.
+
+## CI usage
+
+```yaml
+- name: Snapshot environment manifest
+  run: |
+    dot env emit --output env.json
+    # Attest the manifest as part of the next release
+    cosign sign-blob --yes --output-signature env.json.sig \
+      --output-certificate env.json.pem env.json
+```
+
+The signed manifest goes into the release alongside the SBOM —
+together they let any consumer answer "what software was on the
+runner that produced this release" and verify it cryptographically.
+
+## See also
+
+- `docs/schema/dot-env-v1.json` — the JSON Schema authoritative spec.
+- `docs/security/VERIFY_RELEASE.md` — three-attestation verification flow this manifest plugs into.
+- `docs/operations/HARD_AUDIT_2026.md` §7.4 — strategic-reversal record.
+- `docs/operations/ROADMAP_V0_2_503.md` — `dot env emit` was originally deferred to v0.2.504; pulled forward in this PR per user request.

package/docs/operations/REGISTRY.md

@@ -0,0 +1,89 @@
+---
+render_with_liquid: false
+title: "Dot Module Registry"
+description: "How to publish and consume reusable dotfile modules."
+---
+
+# Dot Module Registry
+
+The `dot registry` command discovers reusable dotfile modules from a JSON index published over HTTPS. The default registry is hosted by this repo at:
+
+```
+https://sebastienrousseau.github.io/dotfiles/registry.json
+```
+
+This page documents the JSON contract and the contribution flow. It is the §3 / Months 12-18 deliverable from [HARD_AUDIT_2026.md](./HARD_AUDIT_2026.md) — the registry is the network-effect feature that turns the framework into a category, not just one person's setup.
+
+## Quick start (consumer side)
+
+```sh
+dot registry list                   # list every published module
+dot registry search rust            # filter by keyword
+dot registry info rust-dev-setup    # full metadata for one module
+dot registry install rust-dev-setup # apply to this workstation (scaffold)
+dot registry url                    # show active registry URL
+dot registry set-url <url>          # point at a different registry
+```
+
+The registry index is cached locally at `${XDG_CACHE_HOME:-~/.cache}/dotfiles/registry/index.json` with a 6 hour TTL. Override the URL one-off via `DOTFILES_REGISTRY_URL=<url> dot registry list`.
+
+## JSON contract
+
+A registry index is a single JSON document:
+
+```json
+{
+  "version": 1,
+  "updated": "2026-05-15T16:30:00Z",
+  "registry": "sebastienrousseau/dotfiles",
+  "modules": [
+    {
+      "name": "rust-dev-setup",
+      "description": "Rust toolchain + cargo plugins + Helix/Neovim editor config",
+      "repo": "https://github.com/example/rust-dev-setup",
+      "version": "1.2.0",
+      "tags": ["rust", "language", "dev"],
+      "maintainer": "alice@example.com",
+      "sha256": "f9a2c1b…",
+      "license": "MIT"
+    }
+  ]
+}
+```
+
+Required keys: `name` (kebab-case, ≤ 32 chars), `description` (≤ 200 chars), `repo` (HTTPS clone URL), `version` (semver).
+
+Recommended keys: `tags` (lower-case array), `maintainer`, `sha256` (pinned at publish time so installers can verify), `license` (SPDX identifier).
+
+## Contributing a module
+
+1. Build your module as a chezmoi-source-compatible directory at `https://github.com/<you>/<module>.git`. The contents are overlaid onto the consumer's chezmoi source dir during install.
+2. Open a PR against `sebastienrousseau/dotfiles` adding one entry to `docs/registry.json` (alphabetical by `name`).
+3. The PR runs CI checks for:
+   - Schema validity (`jq` against the JSON contract).
+   - `repo` URL resolves and is a public git repo.
+   - `sha256` matches the latest tag at `repo`.
+4. Once merged, the GitHub Pages workflow re-deploys the registry; `dot registry list` picks it up within 6 hours (or immediately if the consumer purges the cache).
+
+## Install pipeline (scaffold today, full in Phase 2)
+
+`dot registry install <name>` currently prints what *would* happen. The full pipeline lands as follows:
+
+1. Resolve the module entry from the registry index.
+2. Clone the module to `$XDG_DATA_HOME/dotfiles/modules/<name>/<version>`.
+3. Verify the clone's HEAD matches `sha256` from the registry.
+4. Source the module's `module.toml` (if present) for declared profiles + feature flags.
+5. Merge the module's chezmoi source into the consumer's chezmoi source dir under a namespaced subtree (`/registry/<name>/...`).
+6. Run `chezmoi apply --include /registry/<name>/**` so only the module's files are written.
+
+The sandboxed apply (point 6) requires changes to `dot sync` to accept an include filter — that is its own roadmap issue and tracked separately.
+
+## Security model
+
+- Modules execute with the consumer's user privileges via chezmoi `run_onchange_*` scripts. The trust contract is identical to consuming any third-party dotfiles repo.
+- Pinning `sha256` lets a consumer verify the registry entry hasn't been tampered with between publish and install.
+- The registry index itself is fetched over HTTPS; the GitHub Pages cert chain provides transport integrity.
+
+## Why this lives in this repo (for now)
+
+A vendor-neutral registry would be ideal but adds operations cost. Hosting `registry.json` under this repo's `docs/` directory and serving it via GitHub Pages keeps the maintenance burden near zero while the registry is small. If/when the registry outgrows GitHub Pages, the JSON contract is stable and the index can move to a dedicated subdomain.

package/docs/operations/RELEASE_PIPELINE.md

@@ -0,0 +1,130 @@
+---
+title: "Release Pipeline"
+date: 2026-05-24
+---
+
+# Release Pipeline
+
+End-to-end flow from `git tag v0.2.503 && git push --tags` to a fully
+signed, distributed release on GitHub + Homebrew + Scoop + AUR.
+
+Five workflows are involved, each scoped to one job and triggered off
+either `release.created` or `release.published`. They run in parallel
+where dependencies allow.
+
+```
+            git push --tags                       (you)
+                  │
+                  ▼
+       ┌────────────────────────────┐
+       │  GitHub creates Release    │ (auto, from tag)
+       └─┬──────────────────────────┘
+         │ on: release.created
+         ▼
+   ┌─────────────────────────────┐   ┌─────────────────────────────┐
+   │  release-package-dot.yml    │   │  security-release.yml (sbom)│
+   │  → dot-VERSION.tar.gz       │   │  → SBOM + cosign sig + cert │
+   │  → dot-VERSION.zip          │   │  → SLSA L3 provenance       │
+   └─────────────┬───────────────┘   └──────────────┬──────────────┘
+                 │ uploaded to release              │
+                 │                                  │
+                 │ on: release.published            │ on: release.published
+                 │ (after human "publish" click,    │ (same trigger)
+                 │  or auto if Release was created  │
+                 │  with assets+published in one)   │
+                 ▼                                  ▼
+   ┌─────────────────────────────┐   ┌─────────────────────────────┐
+   │  release-distribute-*.yml   │   │  security-release.yml       │
+   │  ┌─────────────────────┐    │   │  (manifest job)             │
+   │  │ homebrew → tap PR   │    │   │  → ALL_SHA256SUMS           │
+   │  │ scoop    → bucket PR│    │   │  → cosign sig + cert        │
+   │  │ aur      → AUR push │    │   │                             │
+   │  └─────────────────────┘    │   └─────────────────────────────┘
+   └─────────────────────────────┘
+                 │
+                 ▼
+        ┌─────────────────────────────┐
+        │  release-attestation-check  │ (Mondays + on demand)
+        │  → opens issue if missing   │
+        └─────────────────────────────┘
+```
+
+## Workflows
+
+| Workflow | Trigger | Owns | Outputs |
+|---|---|---|---|
+| `release-package-dot.yml` | `release.created`, dispatch | Build deterministic `dot-VERSION.{tar.gz,zip}` from `bin/`, `lib/`, `share/`, completions. | Two release assets. |
+| `security-release.yml` (sbom job) | `release.created`, dispatch | Generate SPDX SBOM via anchore/sbom-action. Cosign keyless sign the SBOM. | `dotfiles-sbom.spdx.json` + `.sig` + `.pem`. |
+| `security-release.yml` (provenance job) | needs sbom | SLSA L3 provenance via slsa-framework/slsa-github-generator. | `dotfiles-sbom.spdx.json.intoto.jsonl`. |
+| `security-release.yml` (manifest job) | `release.published`, dispatch | Build `ALL_SHA256SUMS` over every release asset, Cosign-sign it. | `ALL_SHA256SUMS` + `.sig` + `.pem`. |
+| `release-distribute-homebrew.yml` | `release.published`, dispatch | Hash `dot-VERSION.tar.gz`, regenerate `install/homebrew/dot.rb`, push branch + PR to `sebastienrousseau/homebrew-tap`. | One PR on the tap repo. |
+| `release-distribute-scoop.yml` | `release.published`, dispatch | Hash `dot-VERSION.zip`, rewrite `install/scoop/dot.json` via jq (both 64bit + arm64 point at same zip), PR to `sebastienrousseau/scoop-bucket`. | One PR on the bucket repo. |
+| `release-distribute-aur.yml` | `release.published`, dispatch | Hash `dot-VERSION.tar.gz`, rewrite `pkgver` + `sha256sums` in `install/aur/PKGBUILD`, regenerate `.SRCINFO` via dockerised `makepkg`, push to `ssh://aur@aur.archlinux.org/dotfiles-git.git`. | One commit on AUR. |
+| `release-attestation-check.yml` | weekly cron + dispatch | Verify the latest release carries the full attestation bundle (SBOM + sig + cert + intoto + manifest + sig + cert). | Opens or comments on a tracking issue. |
+
+## Why `created` vs `published`
+
+GitHub fires `release.created` the moment a Release record exists.
+That covers SBOM + SLSA + the packaging step: those depend only on
+source bytes at the tag and don't need other assets to be present.
+
+`release.published` fires later, when a human flips the Release from
+draft to public (or when a Release is created already-public, the
+events fire together). The manifest job and the three distribution
+jobs wait for that because they enumerate *all* assets on the release;
+running them earlier would miss the manual / docs artefacts uploaded
+by `manual-publish.yml` and the packaging step's tarball + zip.
+
+Both arms of `security-release.yml` are idempotent: re-running the
+manifest job after late asset uploads picks up the new state and the
+`--clobber` flag overwrites the previous manifest sig + cert.
+
+## Secrets used
+
+| Secret | Used by | Setup |
+|---|---|---|
+| `GITHUB_TOKEN` | every workflow (auto) | n/a |
+| `ACTIONS_BOT_SIGNING_KEY` | distribute-* (signed commits on tap repos), `bump-reusable-pins.yml`, `update-deps.yml` | See `docs/security/AUTOMATION_SECRETS.md`. |
+| `AUR_SSH_KEY` | `release-distribute-aur.yml` only | SSH ED25519 keypair; public key on the `srousseau` AUR profile, private key in this secret. See `memory/reference_aur_account.md` for the AUR Edit-Account form quirk that bit us during setup. |
+
+## Distribution targets
+
+| Target | Repo | First-run prereq |
+|---|---|---|
+| Homebrew | `sebastienrousseau/homebrew-tap` | Tap repo exists (currently bare README + LICENSE). Workflow creates the `Formula/dot.rb` path on first publish. |
+| Scoop | `sebastienrousseau/scoop-bucket` | Bucket repo exists (currently bare). Workflow creates `bucket/dot.json` on first publish. |
+| AUR | `ssh://aur@aur.archlinux.org/dotfiles-git.git` | **Manual one-time step**: the maintainer must create the package entry via the AUR web UI before the workflow's `git clone` can succeed. The workflow exits with a clear error message on the first run if the repo doesn't exist. |
+
+## Verifying a release
+
+See `docs/security/VERIFY_RELEASE.md` for the consumer-facing
+verification recipe. The pipeline produces four orthogonal
+attestations (SBOM, Cosign signature on SBOM, SLSA provenance,
+unified Cosign-signed manifest) and a verifier can check any of them
+independently.
+
+## Known caveats
+
+- **AUR `pkgname=dotfiles-git`**: AUR's `-git` convention means
+  "tracks git HEAD", but the workflow publishes tagged stable
+  releases. Either rename to plain `dotfiles` in
+  `install/aur/PKGBUILD` and register that package, or accept the
+  misnomer. Documented in the v0.2.503 PR (#895).
+- **Signed-Releases retroactive**: the unified manifest landed in
+  v0.2.503. Releases v0.2.500-502 carry the SBOM bundle only.
+  We do not re-tag older releases (would break consumer pins). The
+  OSSF Scorecard score climbs naturally as new releases land.
+- **First-tag rehearsal**: tag a `v0.2.503-rc1` once before the real
+  v0.2.503 to live-test the full pipeline without burning the final
+  release tag. The workflows are idempotent so a real v0.2.503 still
+  works after the rc.
+
+## See also
+
+- `docs/security/VERIFY_RELEASE.md` — consumer-facing verification.
+- `docs/security/CI_PINNING.md` — reusable workflow pin policy + the
+  `bump-reusable-pins.yml` auto-bump bot.
+- `docs/security/AUTOMATION_SECRETS.md` — how each automation secret
+  is generated, scoped, and rotated.
+- `docs/operations/ROADMAP_V0_2_503.md` — the 7-workstream plan this
+  pipeline executed.

package/docs/operations/RFC_v0_2_503_reorganization.md

@@ -0,0 +1,280 @@
+---
+title: "RFC: v0.2.503 Repository Reorganisation"
+status: Accepted — shipping incrementally in this PR
+authors: ['@sebastienrousseau']
+opened: 2026-05-17
+accepted: 2026-05-17
+target: v0.2.503
+---
+
+# RFC: v0.2.503 Repository Reorganisation
+
+> **Status: Accepted.** This RFC was opened in this PR and
+> immediately accepted by the maintainer with explicit decision to
+> ship the reorganisation incrementally within v0.2.503 rather
+> than the originally-proposed two-version deprecation window.
+> Phases land as separate commits on `feat/v0.2.503`; each is
+> independently atomic and verified by `dot lint` + the existing
+> test matrix.
+
+## Summary
+
+Split the current chezmoi-managed monorepo into a **framework layer**
+(distributable CLI + library) and a **defaults layer** (user-facing
+configuration), with the framework layer publishable as a
+standalone tarball to Homebrew, Scoop, and AUR. Maintain
+backwards-compatible behaviour for existing users via a one-shot
+migration script that runs on first apply after upgrade.
+
+## Motivation
+
+R4 hard-audit identified the framework/user-config intermingling
+as the **highest-leverage structural gap** blocking de-facto-
+framework status (`HARD_AUDIT_2026.md` §8.5 Top-5 adoption gaps).
+Concrete symptoms:
+
+1. **Distribution stuck at "curl-pipe-bash".** The Homebrew /
+   Scoop / AUR manifests scaffolded in v0.2.503
+   (`install/{homebrew,scoop,aur}/`) cannot publish until there's
+   a single `bin/dot` tarball — chezmoi's `dot_*` / `executable_*`
+   / `private_*` prefixes force the current layout. Until that's
+   fixed, downstream distros have nothing to package.
+
+2. **New contributor onboarding cost.** Even with the v0.2.503
+   `STRUCTURE.md`, ~20 chezmoi-prefixed root paths require a
+   concept (the chezmoi naming contract) to navigate. A
+   `bin/` + `lib/` + `defaults/` layout is self-documenting.
+
+3. **Framework forks are blocked.** Anyone wanting to fork the
+   *CLI* without the maintainer's personal configs has to
+   manually delete 80+ tool-specific directories under
+   `dot_config/`. A clean separation makes "fork the framework,
+   apply my own defaults" a one-command flow.
+
+4. **Test surface bleed.** CI runs `chezmoi apply --dry-run` on
+   every PR, exercising both framework templates AND the
+   maintainer's personal defaults. A real consumer running the
+   framework will not exercise the maintainer's `dot_config/aider/`
+   etc. — and yet a regression there blocks CI.
+
+The reorganisation is **breaking** for existing user installs:
+chezmoi tracks deployed files by source path, so moving
+`bin/dot` to `bin/dot` means the old
+`~/.local/bin/dot` would be removed before the new path is
+installed. Mitigation: ship a `migrate-v0.2-to-v0.3.sh` script
+that runs before the first post-upgrade `chezmoi apply`.
+
+## Detailed design
+
+### Target layout
+
+Following the [Debian/aws-cli](https://github.com/Debian/aws-cli)
+discipline (every top-level path has a clear purpose; contributor
+orients in <30 seconds):
+
+```
+.
+├── bin/                          # CLI entrypoints
+│   ├── dot                       # was bin/dot
+│   ├── dot-load-benchmark-pty    # was bin/dot-load-benchmark-pty
+│   ├── dot-theme-sync            # was bin/dot-theme-sync
+│   ├── dot-bootstrap             # was bin/dot-bootstrap
+│   └── dot-update                # was dot_local/bin/executable_update (renamed)
+├── lib/                          # Framework library (no chezmoi)
+│   ├── commands/                 # was scripts/dot/commands/
+│   ├── ui.sh                     # was scripts/dot/lib/ui.sh
+│   ├── utils.sh                  # was scripts/dot/lib/utils.sh
+│   ├── platform.sh               # was scripts/dot/lib/platform.sh
+│   ├── log.sh                    # was scripts/dot/lib/log.sh
+│   ├── bento.sh                  # was scripts/dot/lib/bento.sh
+│   └── secrets_provider.sh       # was scripts/lib/secrets_provider.sh
+├── share/                        # OS-conventional resources
+│   ├── man/man1/dot.1            # was dot_local/share/man/man1/dot.1
+│   ├── completions/              # was dot_local/share/zsh/completions/
+│   └── docs/                     # was docs/
+├── defaults/                     # User-facing default config (was dot_config/, etc.)
+│   ├── home/                     # dotfiles deployed to $HOME (dot_X → .X)
+│   ├── config/                   # dotfiles deployed to $XDG_CONFIG_HOME
+│   └── tools/                    # per-tool configs (mise/, npmrc/, ...)
+├── install/                      # Distribution + bootstrap
+│   ├── install.sh                # was install.sh (moved one level down)
+│   ├── homebrew/dot.rb           # already at install/homebrew/ in v0.2.503
+│   ├── scoop/dot.json            # already at install/scoop/    in v0.2.503
+│   ├── aur/PKGBUILD              # already at install/aur/      in v0.2.503
+│   ├── provision/                # was install/provision/ (chezmoi run_onchange_ hooks)
+│   └── migrate/                  # NEW: migrate-v0_2-to-v0_3.sh + rollback
+├── tests/                        # unchanged
+├── examples/                     # unchanged
+├── tools/                        # NEW: ops scripts not shipped to users
+│   ├── ci/                       # was tools/ci/
+│   ├── release/                  # was tools/release/
+│   ├── maintenance/              # was tools/maintenance/
+│   ├── docs/                     # was tools/docs/
+│   └── version-sync.sh           # was scripts/version-sync.sh
+├── .chezmoiroot                  # NEW: points at defaults/
+├── README.md
+├── LICENSE
+├── CHANGELOG.md
+├── CLAUDE.md  /  AGENTS.md  /  per-harness renders
+└── (no more dot_X at root)
+```
+
+### chezmoi adaptation
+
+`.chezmoiroot` lets chezmoi treat a subdirectory as the source
+root. With `.chezmoiroot = "defaults"`, chezmoi will look for
+`defaults/home/dot_zshrc`, `defaults/config/dot_starship.toml`,
+etc. — and deploy to the normal `~/.zshrc` / `~/.config/starship.toml`
+paths.
+
+This means:
+
+- Repo top-level is no longer required to follow chezmoi naming.
+- `bin/dot` is a plain shell script, not `dot_local/bin/executable_dot`.
+- `share/man/man1/dot.1` is a plain file, not chezmoi-deployed.
+- A Homebrew formula can `bin.install 'bin/dot'` directly.
+
+### Migration tool
+
+`install/migrate/migrate-v0.2-to-v0.3.sh`:
+
+1. Detect existing chezmoi state at `~/.local/share/chezmoi` /
+   `~/.config/chezmoi/chezmoi.toml`.
+2. Read the user's pinned source repo from chezmoi.toml; if it's
+   `sebastienrousseau/dotfiles@<v0.2.x>`, warn and confirm.
+3. Run `chezmoi diff` and persist the per-file output to
+   `~/.local/state/dotfiles/v0_2_to_v0_3_pre_diff.log` so the
+   user has a record of pre-migration state.
+4. Run `chezmoi forget` for paths that are moving (no destructive
+   delete — chezmoi forget only un-tracks).
+5. Update `~/.config/chezmoi/chezmoi.toml` to point at the new
+   sourceDir with `.chezmoiroot` honoured.
+6. Run `chezmoi apply` — picks up the new layout and re-creates
+   the user's files at their canonical paths.
+7. Run `dot doctor` and `dot lint` to verify.
+
+The migration is **idempotent** and **safe to abort**: at step 4
+the chezmoi state is removed but no user data is deleted. At step
+6 chezmoi notices "these files already exist on disk with content
+matching the source" and is a no-op.
+
+### Library bash-source paths
+
+Today `scripts/dot/commands/<cmd>.sh` does:
+
+```bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/utils.sh"
+```
+
+After reorganisation:
+
+```bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../utils.sh"   # commands/<cmd>.sh → lib/utils.sh
+```
+
+Or, more robustly, drive lookup from a single env var set by `bin/dot`:
+
+```bash
+: "${DOT_LIB:=$(dirname "$(realpath "$0")")/../lib}"
+source "$DOT_LIB/utils.sh"
+```
+
+The Homebrew formula sets `$DOT_LIB` to `${libexec}/lib` so
+`bin/dot` finds its library wherever the package manager installed
+it.
+
+### Distribution surface
+
+Once `bin/dot` is standalone:
+
+| Channel | Artefact | Verify command |
+|---------|----------|----------------|
+| Homebrew tap | `dot-${VERSION}-${OS}-${ARCH}.tar.gz` | `brew install sebastienrousseau/tap/dot && dot version` |
+| Scoop bucket | `dot.json` → `dot-${VERSION}-windows-${ARCH}.zip` | `scoop install dot && dot version` |
+| AUR | `dotfiles-git` PKGBUILD building from source | `paru -S dotfiles-git && dot version` |
+| `install.sh` | Same SHA256-verified path as today | `bash install.sh` |
+| Direct tarball | Cosign-signed + SLSA-attested release asset | per `docs/security/VERIFY_RELEASE.md` |
+
+The chezmoi-managed `defaults/` subtree is **only** consumed when
+a user wants the maintainer's opinionated config layer. It's a
+strict superset: install `dot` standalone for the CLI; layer
+`defaults/` on top if you want the wallpaper-theming +
+multi-shell setup.
+
+## Backwards compatibility
+
+| Surface | v0.2.x behaviour | v0.2.503 behaviour | Breaking? |
+|---------|------------------|------------------|-----------|
+| `~/.local/bin/dot` | Deployed by chezmoi | Replaced by Homebrew/Scoop install, OR symlinked by chezmoi from the new source | Yes — path may move; migration script handles it |
+| `~/.zshrc` etc | Source-pinned at `dot_zshrc` | Source-pinned at `defaults/home/dot_zshrc`, chezmoi reads via `.chezmoiroot` | No — destination path unchanged |
+| `dot <cmd>` API | All subcommands work as documented | Same | No |
+| `scripts/dot/commands/*.sh` consumers | Direct source paths used in user customisations | Path moves to `lib/commands/*.sh` | Yes — affects any user who source'd these directly |
+| `.chezmoidata.toml` | Repo root | Repo root (unchanged for compatibility with old user `chezmoi init` flows) | No |
+
+### Two-version deprecation window
+
+v0.2.503 ships with the migration script and a deprecation warning
+in `dot doctor`. v0.4.0 removes any v0.2.x shim code. Users who
+skip v0.2.503 entirely (v0.2.x → v0.4.0) hit a hard error and must
+run the migration tool from a v0.3.x release manually.
+
+## Alternatives considered
+
+### A) Keep the chezmoi monorepo as-is
+
+**Pros**: zero migration cost; works today.
+**Rejected**: blocks Homebrew/Scoop/AUR publication permanently. The
+Top-5 adoption gap remains. R4 audit's "9.0/10 internal · 7.5/10
+adoption" plateau persists.
+
+### B) Two-repo split (framework + defaults)
+
+Publish `dot` framework at `sebastienrousseau/dot` and the
+maintainer's personal defaults at `sebastienrousseau/dotfiles`.
+
+**Pros**: cleanest possible separation. Framework forks trivial.
+**Rejected (for v0.3)**: requires a second repo, doubles the CI
+matrix, and forces users to install from two sources. Defer to
+v0.4 if v0.3 single-repo with `.chezmoiroot` proves insufficient.
+
+### C) Rename current root files only (cosmetic)
+
+Just rename `bin/dot` → `bin/executable_dot`
+without `.chezmoiroot`.
+
+**Rejected**: chezmoi only resolves the `executable_` /
+`dot_` prefixes for files inside its source root, so moving the
+prefixed file outside breaks chezmoi-driven install entirely
+without giving us a standalone tarball.
+
+## Unresolved questions
+
+1. **How does the `defaults/` subtree behave when a user wants to override one default?** Today they edit `dot_config/X.tmpl` directly. Post-reorg, do they: (a) edit `defaults/config/X.tmpl` and live with merge conflicts on framework updates, or (b) use a chezmoi `data` override + template conditional, or (c) maintain a second repo layered atop `defaults/`?
+2. **Should `install/migrate/` ship in the regular framework install, or only via a one-shot `https://...migrate.sh` URL?** Bundling it forever increases install size; URL-only requires the user to find and trust the right URL during a stressful upgrade moment.
+3. **Does `.chezmoiroot` survive existing user customisations in `~/.config/chezmoi/chezmoi.toml`?** Needs verification on a real upgrade test.
+4. **Windows-native `bin/dot`**: standalone PowerShell rewrite, or wrapper that shells to bash via WSL/git-bash? `POWERSHELL_PARITY.md` documents the current stub state.
+
+## Implementation plan
+
+| Phase | Scope | Effort |
+|-------|-------|--------|
+| 1 | Draft + ratify this RFC. Get user OK. | Done (this PR's draft) |
+| 2 | Create `defaults/`, `bin/`, `lib/`, `share/`, `tools/` and copy files. Update bash source paths. Add `.chezmoiroot`. | 1 week |
+| 3 | Write `install/migrate/migrate-v0_2-to-v0_3.sh`. Test against a synthetic v0.2.503-installed environment. | 3 days |
+| 4 | Update CI: every workflow that references `scripts/`, `dot_local/`, `dot_config/` needs path updates. | 3 days |
+| 5 | Update every doc that references the old paths. Most are in `docs/manual/`. | 1 day |
+| 6 | Cut v0.2.999 RC as a deprecation-warning-only release; let real users dry-run the migration. | 1 day + 2-week soak |
+| 7 | Cut v0.2.503 with the actual reorg + migration tool. | 1 day |
+| 8 | Publish to Homebrew/Scoop/AUR using `install/{homebrew,scoop,aur}/` scaffolds. | 1 week |
+| **Total** | | **~5 weeks calendar time** |
+
+## See also
+
+- `HARD_AUDIT_2026.md` §8.3 — cross-platform gap analysis.
+- `HARD_AUDIT_2026.md` §8.5 — Top-5 de-facto adoption gaps.
+- `STRUCTURE.md` — today's layout (honest about the chezmoi-prefix forcing function).
+- `GOVERNANCE.md` — RFC process this document follows.
+- `install/README.md` — distribution-channel publication checklist.
+- Reference: [Debian/aws-cli](https://github.com/Debian/aws-cli) — clean top-level discipline.