@sebastienrousseau/dotfiles 0.2.502 → 0.2.503

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/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.

package/docs/operations/ROADMAP_2026.md

@@ -60,8 +60,8 @@ The combination of Codex Windows GA (2026-03-04, 500k waitlist → 2M WAU in 4 w
 1. New job `windows` in `.github/workflows/ci.yml`:
    - runs-on: `windows-latest`
    - install pwsh 7.6 via `actions/setup-pwsh`
-   - run `pwsh -File scripts/ci/windows-smoke-test.ps1`
-2. New `scripts/ci/windows-smoke-test.ps1` that:
+   - run `pwsh -File tools/ci/windows-smoke-test.ps1`
+2. New `tools/ci/windows-smoke-test.ps1` that:
    - asserts `dot.ps1` (or the bash dispatcher under WSL) starts cleanly
    - exercises `dot version`, `dot help`, `dot agents check`
    - verifies chezmoi can be invoked from PowerShell
@@ -70,7 +70,7 @@ The combination of Codex Windows GA (2026-03-04, 500k waitlist → 2M WAU in 4 w
 
 **Acceptance.** Three new green checks on every PR: `CI / Windows / pwsh-smoke-test`, `Test / Windows / pwsh`, `Lint / Windows / PSScriptAnalyzer`.
 
-**Files.** `.github/workflows/ci.yml` (job add), `scripts/ci/windows-smoke-test.ps1` (new), `README.md` (header), `scripts/dot/lib/platform.sh` (pwsh.exe over powershell.exe).
+**Files.** `.github/workflows/ci.yml` (job add), `tools/ci/windows-smoke-test.ps1` (new), `README.md` (header), `scripts/dot/lib/platform.sh` (pwsh.exe over powershell.exe).
 
 ### B2 — Publish a Claude Code skill — **0.5 P-d**
 
@@ -197,7 +197,7 @@ $ dot agent run "fix the flaky integration test"
 
 **Files to modify.**
 
-- `dot_local/bin/executable_dot` — route `agent run` to the new entry-point
+- `bin/dot` — route `agent run` to the new entry-point
 - `scripts/dot/commands/agent.sh:cmd_mode` — record sandboxed runs in the session log
 - `dot_config/dotfiles/agent-profiles.json` (template) — add `allowedMcpServers` / `deniedMcpServers` per profile
 
@@ -267,7 +267,7 @@ harnesses = ["claude", "agents-md", "cursor", "codex", "windsurf", "zed", "roo",
 
 **Files to modify.**
 
-- `dot_local/bin/executable_dot` — route `env emit | diff | validate`
+- `bin/dot` — route `env emit | diff | validate`
 - `scripts/dot/commands/agents.sh` — consume the same source-of-truth (or accept `--from <toml>`)
 
 **Test plan.**
@@ -321,7 +321,7 @@ Each adds 8–15 lines to `cmd_agents`. The body content reuses `_agents_body` (
 
 **Files to modify.** `dot_config/zsh/dot_zshrc.tmpl`, `dot_config/zsh/conf.d/*.zsh`, `.github/workflows/dot-cli-bench.yml` (budget tighten).
 
-**Test plan.** `scripts/ci/dot-cli-startup-bench.sh --budget-ms 100` becomes the new CI gate. Plus an integration test that asserts `nvm`, `mise`, etc. still work after lazy-load (run `node --version` once and confirm activation fires).
+**Test plan.** `tools/ci/dot-cli-startup-bench.sh --budget-ms 100` becomes the new CI gate. Plus an integration test that asserts `nvm`, `mise`, etc. still work after lazy-load (run `node --version` once and confirm activation fires).
 
 **Acceptance.** Median cold-start `dot version` < 100ms on macOS local + < 150ms on ubuntu-latest CI runner.