@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/operations/REGISTRY.md

@@ -1,90 +0,0 @@
----
-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 # verify and preview changes
-dot registry install rust-dev-setup --yes # verify, persist, and apply
-dot registry installed              # list locally installed modules
-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",
-      "archive_url": "https://example.com/rust-dev-setup-1.2.0.tar.gz",
-      "sha256": "f9a2c1b0a8d27c41b99c8c93641a0d476a0e54b23161847c47c780025ac7c4a1",
-      "license": "MIT"
-    }
-  ]
-}
-```
-
-Required keys: `name` (kebab-case, no more than 32 characters), `description` (no more than 200 characters), `version` (semver), `archive_url` (immutable HTTPS archive), and `sha256` (64 lowercase hexadecimal characters).
-
-Optional keys: `repo` (HTTPS project URL), `tags` (lower-case array), `maintainer`, and `license` (SPDX identifier). The machine-readable contract is [`docs/schema/dot-registry-v1.json`](../schema/dot-registry-v1.json).
-
-## Contributing a module
-
-1. Build a gzip-compressed tar archive containing a chezmoi-source-compatible directory. Publish it at an immutable HTTPS URL, such as a versioned GitHub release asset.
-2. Open a PR against `sebastienrousseau/dotfiles` adding one entry to `docs/registry.json` (alphabetical by `name`).
-3. The PR runs CI checks for:
-   - Runtime contract validity and unique, sorted module names.
-   - Valid JSON for both the index and its published JSON Schema.
-   - A pinned SHA-256 digest for every archive.
-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
-
-`dot registry install <name>` is preview-first and does not mutate the workstation. Pass `--yes` only after reviewing the chezmoi dry-run. The installer:
-
-1. Resolve the module entry from the registry index.
-2. Download the versioned archive using HTTPS and TLS 1.2 or newer.
-3. Verify the archive against the registry's SHA-256 digest.
-4. Reject absolute paths, parent traversal, symbolic links, and hard links before extraction.
-5. Run `chezmoi apply --dry-run` against the isolated module source.
-6. With `--yes`, persist it at `${XDG_DATA_HOME:-~/.local/share}/dotfiles/modules/<name>/<version>` and apply that exact verified source.
-
-## Security model
-
-- Modules execute with the consumer's user privileges via chezmoi scripts. Review the default dry-run and publisher before passing `--yes`.
-- The SHA-256 pin binds installation to the reviewed archive bytes, even if the hosting release later changes.
-- 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

@@ -1,128 +0,0 @@
----
-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.
-
-Release workflows are triggered by either `release.created` or
-`release.published`. Packaging starts at creation; distribution and the
-single security chain start at publication and run in parallel where
-dependencies allow.
-
-```
-            git push --tags                       (you)
-                  │
-                  ▼
-       ┌────────────────────────────┐
-       │  GitHub creates Release    │ (auto, from tag)
-       └─┬──────────────────────────┘
-         ├── on: release.created
-         │       └── release-package-dot.yml
-         │           → dot-VERSION.tar.gz + .zip
-         │
-         └── on: release.published
-                 │
-                 ├──────────────────────────────────┐
-                 ▼                                  ▼
-   ┌─────────────────────────────┐   ┌─────────────────────────────┐
-   │  release-distribute-*.yml   │   │  security-release.yml       │
-   │  ┌─────────────────────┐    │   │  → SBOM + provenance        │
-   │  │ homebrew → tap PR   │    │   │  → ALL_SHA256SUMS           │
-   │  │ scoop    → bucket PR│    │   │  → cosign sig + cert        │
-   │  │ aur      → AUR push │    │   │  → verify full bundle       │
-   │  └─────────────────────┘    │   └─────────────────────────────┘
-   └─────────────────────────────┘
-                 │
-                 ▼
-        ┌─────────────────────────────┐
-        │  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.published`, 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) | needs provenance + complete asset set | Build `ALL_SHA256SUMS` over every release asset, Cosign-sign it, and verify its signature and digests. | `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/dot-cli-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. |
-
-## Event ownership and readiness
-
-GitHub fires `release.created` the moment a Release record exists.
-That starts the packaging step, which depends only on source bytes at
-the tag and does not 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). Distribution and the security chain start from
-this event. Publication does not mean independently triggered asset
-publishers have finished, so the manifest job waits for all 13 required
-package, documentation, SBOM, signature, and provenance assets before
-it downloads or signs the bundle. The final integrity job then verifies
-the manifest's Cosign identity and every recorded digest.
-
-Both release and dispatch paths 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/dot-cli-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=dot-cli-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/RELIABILITY.md

@@ -1,122 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# Reliability
-
-## Reliability scorecard
-
-- Unit coverage: 100% module mapping target, enforced by `tests/framework/module_coverage.sh`
-- Integration depth: 11 integration test files in `tests/integration/`
-- Regression automation: 436 discovered test files and 2149 named tests in the current baseline
-
-## Coverage gap map
-
-| Module | Missing path | Risk level | Proposed test case |
-| :--- | :--- | :--- | :--- |
-| `scripts/qa/reliability-audit.sh` | Quick mode and integration mode branch handling | Closed | Covered by `tests/unit/misc/test_qa_reliability_behaviour.sh` |
-| `scripts/git-hooks/pre-push` | Audit command failure path | Closed | Covered by `tests/unit/misc/test_git_hooks_pre_push_behaviour.sh` |
-| `tests/framework/module_coverage.sh` | False-positive module matches | Closed | Covered by `tests/unit/misc/test_module_coverage_behaviour.sh` |
-| `examples/*.sh` | Drift between examples and real commands | Closed | Examples execute in CI through `Examples Contract` and `validate-examples.sh` |
-
-## Integration boundaries
-
-```mermaid
-flowchart LR
-  Dev[Developer] --> Hook[pre-push hook]
-  Hook --> Audit[reliability-audit.sh]
-  Audit --> Syntax[Shell syntax gate]
-  Audit --> Unit[Unit suite]
-  Audit --> Coverage[Module coverage]
-  Audit --> Examples[Example validation]
-  Audit --> WSL[WSL contract]
-  Audit --> Integration[Integration suite]
-  Integration --> Repo[Dotfiles workflows]
-  WSL --> Repo
-```
-
-```mermaid
-sequenceDiagram
-  participant Dev as Developer
-  participant Git as Git client
-  participant Hook as pre-push
-  participant Audit as reliability-audit.sh
-  participant Suite as tests/framework/test_runner.sh
-  participant Cov as module_coverage.sh
-  participant Ex as validate-examples.sh
-  participant WSL as wsl-contract.sh
-
-  Dev->>Git: git push
-  Git->>Hook: invoke pre-push
-  Hook->>Hook: verify signed commits
-  Hook->>Audit: run quick gate
-  Audit->>Suite: run unit suite
-  Audit->>Cov: enforce 100% module mapping
-  Audit->>Ex: execute examples
-  Audit->>WSL: verify WSL parity contract
-  Ex-->>Audit: pass
-  Cov-->>Audit: pass
-  WSL-->>Audit: pass
-  Suite-->>Audit: pass
-  Audit-->>Hook: pass
-  Hook-->>Git: allow push
-```
-
-## CI gate
-
-```yaml
-name: Reliability Gate
-
-on:
-  pull_request:
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-jobs:
-  reliability:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v6
-      - name: Reliability audit
-        run: bash ./scripts/qa/reliability-audit.sh --with-integration
-
-  examples-contract:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - name: Validate executable examples
-        run: bash ./scripts/qa/validate-examples.sh
-
-  wsl-contract:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - name: Validate WSL parity contract
-        run: bash ./scripts/qa/wsl-contract.sh
-
-  reliability-summary:
-    needs: [reliability, examples-contract, wsl-contract]
-    runs-on: ubuntu-latest
-```
-
-## Functional examples
-
-- `examples/example-test-suite.sh`: Runs a focused unit slice.
-- `examples/example-coverage-gate.sh`: Runs the module coverage contract.
-- `examples/example-git-hooks.sh`: Shows the local hook entrypoints.
-- `examples/example-platform-contract.sh`: Shows the platform and host contract across macOS, Linux, and WSL.
-
-## Local guardrail
-
-`make test` is the canonical reliability command. It runs syntax checks, unit tests, module coverage, executable examples, and integration tests.
-
-For a lightweight repository-wide snapshot, run `bash ./scripts/qa/coverage-baseline.sh --with-module-coverage`.
-
-Core internal behaviors are traced through `bash ./scripts/qa/traceability-coverage.sh`.
-{% endraw %}

package/docs/operations/RFC_v0_2_503_reorganization.md

@@ -1,280 +0,0 @@
----
-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.md

@@ -1,10 +0,0 @@
----
-render_with_liquid: false
----
-
-# Roadmap
-
-The canonical roadmap is [`../../ROADMAP.md`](../../ROADMAP.md).
-
-This file is retained only so existing documentation links continue to resolve.
-Do not add active planning content here.

package/docs/operations/ROADMAP_2026.md

@@ -1,7 +0,0 @@
-# 2026 Roadmap
-
-Historical content from this file has been consolidated into the canonical
-[`../../ROADMAP.md`](../../ROADMAP.md).
-
-This path is retained only for compatibility with older links. New roadmap work
-belongs in the root roadmap or in GitHub issues and milestones.

package/docs/operations/ROADMAP_V0_2_503.md

@@ -1,10 +0,0 @@
----
-title: "v0.2.503 Roadmap - Historical"
----
-
-# v0.2.503 Roadmap
-
-This v0.2.503 planning document is historical. Active roadmap content has been
-consolidated into [`../../ROADMAP.md`](../../ROADMAP.md).
-
-Release history remains in [`../../CHANGELOG.md`](../../CHANGELOG.md).