arashi 1.33.0 → 1.35.0

package/README.md

@@ -4,424 +4,130 @@
 [![CI](https://github.com/corwinm/arashi/actions/workflows/ci.yml/badge.svg)](https://github.com/corwinm/arashi/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/corwinm/arashi.svg)](https://github.com/corwinm/arashi/blob/main/LICENSE)
 
-Arashi is a Git worktree manager for meta-repositories.
+Arashi is a Git worktree manager for meta-repositories. It coordinates related repositories in one feature workspace while each repository keeps its own history, CI, and pull requests.
 
-It keeps related repositories aligned while you work on a feature branch across a shared workspace.
-
-Arashi makes a polyrepo work like a monorepo during development, while every repository keeps its own history, CI, and pull requests.
-
-[Documentation](https://arashi.haphazard.dev)
+[Documentation](https://arashi.haphazard.dev) · [Command reference](https://arashi.haphazard.dev/commands/) · [Workflow guides](https://arashi.haphazard.dev/workflows/)
 
 ## Installation
 
-### Option 1: Install with curl (official direct install)
-
-Prerequisites:
-
-- `curl`
-- `bash`
-- A SHA-256 tool (`shasum`, `sha256sum`, or `openssl`)
+macOS and Linux:
 
 ```bash
 curl -fsSL https://arashi.haphazard.dev/install | bash
 ```
 
-Install a specific release:
-
-```bash
-curl -fsSL https://arashi.haphazard.dev/install | ARASHI_VERSION=1.4.0 bash
-```
-
-Verify install:
-
-```bash
-aw --version
-```
-
-By default, the installer places `arashi` in `~/.arashi/bin`, adds that path to your shell config, and in interactive installs offers to enable shell integration for `aw switch --cd`.
-Use `aw` for documented workflows. The `arashi` executable remains supported for existing scripts and workflows, and both names run the same implementation. Product names, configuration, environment variables, packages, and native binaries retain their established Arashi names.
-
-The installer transaction verifies that both executable entrypoints report the same non-empty version before declaring success.
-
-If curl installation fails, or if the smoke test reports a bad release artifact, use npm installation below or the manual release instructions in [`docs/INSTALLATION.md`](./docs/INSTALLATION.md).
-
-### Option 2: Install on Windows with PowerShell
-
-PowerShell is the canonical Windows installer:
+Windows PowerShell:
 
 ```powershell
 powershell -c "irm https://arashi.haphazard.dev/install.ps1 | iex"
 ```
 
-It verifies and installs one `arashi.bin.exe` plus `arashi`/`aw` wrappers for Git Bash, `arashi.ps1`/`aw.ps1`, and `arashi.bat`/`aw.bat` from the same release. The default directory is `%USERPROFILE%\.arashi\bin`; the installer adds it to the persistent user PATH. It does not create or modify `.bashrc` or another shell profile. Open a new Git Bash window before verifying the installed version so it inherits the PATH change.
+Open a new terminal after the Windows installer so it inherits the updated user `PATH`.
 
-### Option 3: Install with npm
+With npm:
 
 ```bash
 npm install -g arashi
 ```
 
-The npm package is script-free: it does not require package-manager lifecycle scripts or `postinstall` approval. It maps both npm bins to the same lightweight JavaScript entrypoint, then downloads the matching platform binary on first use through either name.
-
-To preinstall the binary explicitly, run:
-
-```bash
-aw install
-```
-
-To check for package updates or refresh the matching platform binary, run:
-
-```bash
-aw update --check
-aw update --dry-run
-aw update --yes
-```
-
-`aw update` can update npm-managed installs when it can confidently detect the package manager, including npm, pnpm, Yarn, Bun, and Vite+ (`vp update -g arashi`). For official direct-installer installs, `aw update --yes` reruns the platform installer against the current binary directory: the POSIX curl installer on macOS/Linux and a deferred PowerShell installer on Windows after the current Arashi process exits.
-
-Verify install:
+Verify the installation:
 
 ```bash
 aw --version
 ```
 
-If npm is unavailable or binary installation fails, use the curl installer command above or the manual release instructions in [`docs/INSTALLATION.md`](./docs/INSTALLATION.md).
+`aw` is the preferred command name. `arashi` remains available for existing scripts and workflows. See the [installation guide](./docs/INSTALLATION.md) for version pinning, manual installation, and troubleshooting, or the [`update` command guide](https://arashi.haphazard.dev/commands/update/) for upgrades.
 
-### Manual install from GitHub Releases
+## Quick start
 
-If you prefer not to use npm, download a platform binary from [GitHub Releases](https://github.com/corwinm/arashi/releases) and place it on your `PATH`.
-
-macOS (Apple Silicon):
-
-```bash
-curl -L https://github.com/corwinm/arashi/releases/latest/download/arashi-macos-arm64 -o arashi.bin
-curl -L https://github.com/corwinm/arashi/releases/latest/download/arashi -o arashi
-curl -L https://github.com/corwinm/arashi/releases/latest/download/aw -o aw
-chmod +x arashi.bin arashi aw
-sudo install -m 0755 arashi.bin arashi aw /usr/local/bin/
-```
-
-Linux (x64):
-
-```bash
-curl -L https://github.com/corwinm/arashi/releases/latest/download/arashi-linux-x64 -o arashi.bin
-curl -L https://github.com/corwinm/arashi/releases/latest/download/arashi -o arashi
-curl -L https://github.com/corwinm/arashi/releases/latest/download/aw -o aw
-chmod +x arashi.bin arashi aw
-sudo install -m 0755 arashi.bin arashi aw /usr/local/bin/
-```
-
-Windows (PowerShell and Git Bash):
-
-```powershell
-# Download arashi-windows-x64.exe, arashi, arashi.ps1, arashi.bat,
-# aw, aw.ps1, aw.bat,
-# and arashi-checksums.txt from the same release.
-# Verify all seven payload files against arashi-checksums.txt.
-# Rename arashi-windows-x64.exe to arashi.bin.exe and keep the seven files together on PATH.
-```
-
-Windows manual installation requires `arashi-windows-x64.exe`, `arashi`, `arashi.ps1`, `arashi.bat`, `aw`, `aw.ps1`, `aw.bat`, and `arashi-checksums.txt` from the same release. Verify all seven payload files, rename the executable to `arashi.bin.exe`, and keep the payload together on PATH. Manual release installations do not create the direct installer's ownership ledger; deliberately move or remove the manual payload before later using the direct installer.
-
-You can also build from source for local development. Development is pinned to Node.js 24.18.0, which satisfies pnpm 11's Node.js 22.13 minimum, and pnpm 11.20.0; nvm users can select the repository's development runtime with `nvm use`.
+From the repository that will coordinate your projects:
 
 ```bash
-nvm use # Optional; reads .nvmrc
-pnpm install
-pnpm run build
-```
-
-## Command Surface
-
-Arashi currently provides these commands:
-
-- `aw init`
-- [`aw init --zero-config`](docs/standalone.md) for a single repository with `.worktrees/<branch>` paths and no persisted Arashi configuration
-- `aw install`
-- `aw update [--check] [--dry-run] [--yes]`
-- `aw add <git-url>`
-- `aw clone [--all] [--base <branch>] [--repo-base <repository=branch>]`
-- `aw create <branch> [--base <branch>] [--repo-base <repository=branch>] [--tab] [--tmux|--sesh|--herdr]`
-- `aw list`
-- `aw status`
-- `aw remove <branch|path>`
-- `aw prune [--dry-run]` - clean stale Git worktree metadata
-- `aw switch [filter] [--repos|--all] [--tab] [--cd|--launch] [--tmux|--sesh|--herdr] [--ignore-configured-launcher]`
-- `aw completion <bash|zsh|fish>`
-- `aw shell init <bash|zsh|fish>`
-- `aw shell install`
-- `aw pull`
-- `aw push [--set-upstream] [--dry-run] [--only <repo>] [--json]`
-- `aw sync`
-- `aw setup [--only <repo>] [--verbose]`
-
-## Quick Example
-
-```bash
-aw init                         # repository-local ignore rules (default)
-aw init --ignore-scope tracked  # opt in to a shared .gitignore block
+aw init
 aw add git@github.com:your-org/frontend.git
 aw add git@github.com:your-org/backend.git
 aw create feature-auth-refresh
-aw create feature-auth-refresh --base feature/auth
-aw create feature-auth-refresh --repo-base @meta=develop --repo-base frontend=release/2.x
-aw clone --all --base main --repo-base frontend=release/2.x
-aw create feature-auth-refresh --launch
-aw create feature-auth-refresh --tmux
-aw create feature-auth-refresh --herdr
-aw create feature-auth-refresh --tab
-aw create feature-auth-refresh --no-launch
-aw shell install
-aw status
-aw switch feature-auth-refresh          # parent repo worktrees
-aw switch --repos feature-auth-refresh  # child repo worktrees in current workspace
-aw switch --all feature-auth-refresh    # all repos
-aw switch --repos docs                  # repo-name matching in child repos
-aw switch --cd feature-auth-refresh     # parent-shell cd when shell integration is active
-aw switch --launch feature-auth-refresh # force launch while preserving a configured launcher
-aw switch --tmux feature-auth-refresh   # force a new plain tmux window
-aw switch --herdr feature-auth-refresh  # open or focus a persistent Herdr workspace
-aw switch --tab feature-auth-refresh    # request a true tab or managed equivalent
-aw switch --ignore-configured-launcher  # bypass configured sesh/Herdr mode once
-aw switch --launch --ignore-configured-launcher # force generic automatic launch
-```
-
-### Add from a linked parent worktree
-
-When `aw add` runs from an active linked parent worktree, Arashi creates one canonical clone in the parent main checkout and leaves it on the child default branch. It then creates the active child as a linked worktree on the coordinated branch and updates only the active parent configuration. Direct-main and configured-bare adds keep their existing single-placement behavior. See the [add command guide](https://arashi.haphazard.dev/commands/add/) for branch, managed-ignore, JSON, and rollback details.
-
-Explicit `--tmux` is a per-invocation launcher override for `create` and `switch`; it is not a persisted configuration mode. It requires an active tmux context whose `TMUX` value is non-empty after trimming, uses the selected worktree path as one argv-safe `tmux new-window -c` argument, and does not fall back to another launcher when the prerequisite or launch fails. On `create`, it implies both launch and switch, while validation failures occur before worktree mutation.
-
-`--tab` is a CLI-only launch disposition for `create` and `switch`; it is never persisted. It requests a true terminal tab or documented managed-context equivalent, implies launch (and selection for `create`), overrides automatic parent-shell `cd`, and never degrades to a window or another launcher. For switch, it bypasses configured `sesh` or `herdr` launch defaults; for create, it bypasses configured generic or editor-scoped launch defaults. An explicit launcher selector remains authoritative. Unsupported adapters fail with `TAB_DISPOSITION_UNSUPPORTED`; launch/preflight failures use `LAUNCH_FAILED`. Human-only tab launch is incompatible with `--json`.
-
-### Managed Git ignore rules
-
-Configured workspaces keep `reposDir` and `worktreesDir` effectively ignored. Arashi asks Git
-first, so an existing tracked `.gitignore`, repository-local `.git/info/exclude`, or configured
-global excludes rule is honored without duplication. Missing safe repository-relative rules use
-the common repository's local exclude file by default, including when a command runs in a linked
-worktree.
-
-Use `aw init --ignore-scope tracked` when the team wants Arashi-owned rules committed in the
-workspace `.gitignore`. Use `aw init --ignore-scope none` for a fully manual workflow; Arashi
-will warn about unignored managed paths but will not edit ignore files. Running
-`aw init --ignore-scope local` resets that clone-local preference without recreating an
-existing workspace. The explicit `tracked` or `none` preference is stored only in local Git config
-as `arashi.ignoreScope`; Arashi never creates or modifies global Git ignore configuration.
-
-`init`, `pull`, `clone`, `add`, and `create` reconcile the same owned rules before materializing
-configured repositories or worktrees. `doctor` reports missing, unsafe, invalid, or stale managed
-ignore state without changing it.
-
-## Workflow Guides
-
-Use the docs site workflow guides when you want setup guidance by outcome instead of by individual command.
-
-For contributors working on Arashi itself, the project planning workflow in the `arashi-arashi` meta-repo now uses OpenSpec. Older SpecKit-oriented references in legacy planning artifacts are historical context only.
-
-- Hooks and configuration defaults: [arashi.haphazard.dev/workflows/hooks-and-config](https://arashi.haphazard.dev/workflows/hooks-and-config/)
-- Integrations for Herdr, VSCode, tmux, and `tmux` plus `sesh`: [arashi.haphazard.dev/workflows](https://arashi.haphazard.dev/workflows/)
-- Agent-assisted and spec-driven change flow: [arashi.haphazard.dev/workflows/agents-and-specs](https://arashi.haphazard.dev/workflows/agents-and-specs/)
-
-## Shell Integration
-
-Use shell integration for parent-shell directory switching and native tab completion. Bash, Zsh, and Fish are supported through both `arashi` and `aw`.
-
-The official curl installer can offer this automatically. If you skip it or use npm, install it for the active shell with:
-
-```bash
-aw shell install
 ```
 
-`aw shell install` adds a managed pair to the active shell startup file: the parent-shell wrapper first and completion activation second. Repeating the command is idempotent and upgrades older wrapper-only blocks.
-
-For manual setup, activate the wrapper and completion independently:
+Arashi creates matching worktrees for the configured repositories. From there, use:
 
 ```bash
-# Bash
-eval "$(command aw shell init bash)"
-source <(command aw completion bash)
-
-# Zsh
-eval "$(command aw shell init zsh)"
-source <(command aw completion zsh)
-
-# Fish
-command aw shell init fish | source
-command aw completion fish | source
+aw status                         # inspect the coordinated workspace
+aw switch feature-auth-refresh    # return to a worktree
+aw pull                           # update repositories
+aw push --set-upstream            # publish branches
+aw remove feature-auth-refresh    # remove the coordinated worktrees
 ```
 
-`aw shell init <shell>` remains wrapper-only and defines both parent-shell functions, unless an unrelated `aw` alias or function already owns that shell name. `aw completion <shell>` registers the same completion model for both executable names and emits only deterministic sourceable shell code, including on npm first use when the platform binary must be installed.
-
-Completion covers commands, aliases, options, finite choices, conflicts, and positional boundaries. In an Arashi workspace it also resolves configured repository and group selector segments, switch/remove worktrees and paths, and move source/target references. Dynamic lookup is local and read-only, silent on unavailable or broken metadata, and limited to a 200 ms whole-query budget; it performs no network requests, hooks, prompts, workspace mutations, or child operations. Static completion remains available outside a workspace.
-
-Once installed, you can use `aw switch --cd <filter>` for one-off parent-shell switching or set `.arashi/config.json` `defaults.switch.mode` to `"cd"` or contextual `"auto"`. The canonical modes are `auto` | `cd` | `launch` | `sesh` | `herdr`.
-
-If shell integration is inactive, `aw switch --cd` warns and skips launch fallback for that invocation.
-
-For automated installs, set `ARASHI_SHELL_INTEGRATION=yes` to enable it without prompting or `ARASHI_SHELL_INTEGRATION=no` to skip it.
-
-## Hooks
-
-Arashi can run file-backed or configured inline lifecycle hooks during `aw create` and
-`aw remove`. Inline workspace values live only at root `hooks.scripts.<lifecycle>`; repository
-values live only at `repos.<name>.hooks.<lifecycle>`. Use inline config for short reviewable commands
-and native files for substantial scripts. One inline/file source may own a logical location; a
-same-location collision fails preflight instead of running both.
+For a single repository without persisted Arashi configuration, use `aw init --zero-config`. See the [standalone workflow](https://arashi.haphazard.dev/workflows/standalone/).
 
-Configured create uses workspace `pre-create`/`post-create` plus repository-specific create locations.
-Configured remove evaluates repository, workspace, user-global targeted, and user-global shared scopes
-once per target repository. `--no-hooks` is create-only; `--no-hook-input` applies to both commands.
-Standalone mode remains file-only and activates only targeted and shared user-global hooks.
+## Core commands
 
-Hook failures participate in create rollback or remove finalization. Inline and file sources share the
-configured timeout, input, JSON isolation, dry-run, and ordered outcome policies. Public records expose
-source kind/owner metadata but never disclose configured snippet text.
+| Command                           | Purpose                                   |
+| --------------------------------- | ----------------------------------------- |
+| `aw init`                         | Initialize a workspace                    |
+| `aw add`                          | Add a repository                          |
+| `aw delete`                       | Delete configured repository dependencies |
+| `aw clone`                        | Clone configured repositories             |
+| `aw configure`                    | Edit existing workspace settings          |
+| `aw create`                       | Create coordinated worktrees              |
+| `aw list`                         | List worktrees                            |
+| `aw status`                       | Show repository status                    |
+| `aw switch`                       | Select and open a worktree                |
+| `aw pull` / `aw push` / `aw sync` | Synchronize repositories                  |
+| `aw setup`                        | Run repository setup steps                |
+| `aw remove` / `aw prune`          | Clean up branch worktrees and metadata    |
+| `aw doctor`                       | Diagnose workspace problems               |
+| `aw update`                       | Update Arashi                             |
 
-See [`docs/configuration.md`](./docs/configuration.md#inline-lifecycle-hook-configuration) for values and
-[`docs/hooks.md`](./docs/hooks.md) for exact lookup, lifecycle, environment, and automation behavior.
+Run `aw --help`, `aw <command> --help`, or use the [complete command reference](https://arashi.haphazard.dev/commands/) for options and examples.
 
-## Workflow Shortcuts
+## Shell integration
 
-Use `aw list` with `fzf` and optional keybinds to speed up daily navigation.
-
-### Jump to a worktree (`cd`)
-
-```bash
-# One-off jump
-cd "$(aw list | fzf)"
-```
+Install shell integration for parent-shell directory switching and completion in Bash, Zsh, or Fish:
 
 ```bash
-# Bash keybind (Ctrl+G)
-bind '"\C-g":"cd \$(aw list | fzf)\n"'
-```
-
-```zsh
-# Zsh keybind (Ctrl+G)
-bindkey -s '^g' 'cd $(aw list | fzf)\n'
-```
-
-### Open or switch tmux sessions with `sesh`
-
-```bash
-# One-off session connect
-sesh connect "$(aw list | fzf)"
-```
-
-```bash
-# Bash keybind (Ctrl+S)
-bind '"\C-s":"sesh connect \$(aw list | fzf)\n"'
-```
-
-```zsh
-# Zsh keybind (Ctrl+S)
-bindkey -s '^s' 'sesh connect $(aw list | fzf)\n'
+aw shell install
 ```
 
-You can also use `aw switch --sesh` directly inside tmux to open the selected worktree in a new tmux window.
-
-`aw switch` checks managed contexts in this order: tmux → Herdr → cmux → integrated IDE → Kitty. Managed Kitty selection applies when any one of `KITTY_PID`, `KITTY_WINDOW_ID`, or `TERM=xterm-kitty` is present after normalization.
-
-Managed Kitty requires Kitty 0.43 or newer plus working `kitten @` remote control. Arashi reuses only its exact worktree marker and focuses that tab before launching a new session-backed tab. Once managed Kitty is selected, missing or unsupported tooling, denied remote control, duplicate markers, and validation failures are reported directly instead of falling back to another launcher.
-
-`aw create --launch` and `defaults.create.launch: "auto"` use the same managed Kitty behavior. If that post-create launch fails, Arashi exits nonzero but preserves the successfully created worktree and reports the launch as partial success. Fix the launcher problem and use `aw switch`; do not retry creation for the same branch.
+You can then use `aw switch --cd <filter>` to change the current shell's directory. See the [shell command guide](https://arashi.haphazard.dev/commands/shell/) for manual setup.
 
-### Fast remove selection
+Remove only the exact managed shell block with `aw shell uninstall --dry-run`, then
+`aw shell uninstall --yes`. This leaves executables, PATH, manifests, and project data untouched.
 
-```bash
-# Select and remove a worktree quickly
-aw remove -f "$(aw list | fzf)"
-```
+## Uninstallation
 
-If you prefer the term `delete`, create a shell alias:
+Inspect the conservative removal plan first, then consent explicitly:
 
 ```bash
-alias arashi-delete='aw remove -f'
-```
-
-## Configuration Schema
-
-### Configured worktree files
-
-Configured repositories can copy isolated files or create native symlinks for intentionally shared state when coordinated worktrees are created. See [Worktree file materialization](docs/configuration.md#worktree-file-materialization) for direct `copy`/`symlink` arrays, Git-primary sourcing, lifecycle order, safety rules, dry-run previews, and doctor diagnostics.
-
-## Configuration Schema
-
-Arashi publishes a JSON Schema for `.arashi/config.json` so editors can validate and autocomplete your config.
-
-- Stable URL: `https://unpkg.com/arashi/schema/config.schema.json`
-- Version-pinned URL: `https://unpkg.com/arashi@1.7.0/schema/config.schema.json`
-
-Example config header:
-
-```json
-{
-  "$schema": "https://unpkg.com/arashi/schema/config.schema.json",
-  "version": "1.0.0",
-  "reposDir": "./repos",
-  "defaults": {
-    "create": {
-      "switch": true,
-      "launch": "none"
-    },
-    "editors": {
-      "vscode": {
-        "create": {
-          "launch": "sesh"
-        }
-      }
-    },
-    "switch": {
-      "mode": "sesh"
-    }
-  },
-  "repos": {}
-}
+aw uninstall --dry-run
+aw uninstall --yes
 ```
 
-`defaults.switch.mode` accepts `auto` | `cd` | `launch` | `sesh` | `herdr`. Contextual `auto` checks strict managed contexts in the order tmux → Herdr → cmux → integrated IDE → managed Kitty, then uses parent-shell `cd` when shell integration is active, and otherwise follows terminal/platform launch fallback. An absent mode preserves the built-in automatic `launch` behavior rather than newly preferring `cd`.
-
-Explicit launcher flags take precedence over `--cd` / `--launch`, which take precedence over the configured mode and automatic context detection. `--launch` forces launch while preserving a configured launcher. `--ignore-configured-launcher` bypasses only configured `sesh` or `herdr`; combine both canonical flags to force generic automatic launch. `--herdr` remains available on both `create` and `switch`; Herdr launch uses `herdr worktree open` with the Git-resolved non-bare main checkout and selected worktree.
-
-Legacy switch-only `launchMode` and `launch_mode` fields remain readable for a bounded compatibility window. Arashi warns with the exact replacement `defaults.switch.mode` on stderr; migrate promptly. Ambiguous `cd` plus an explicit legacy launcher and conflicting legacy aliases are rejected.
-
-Use `defaults.create` for terminal `aw create` behavior. Use `defaults.editors.<host>.create` for editor-specific overrides such as VS Code extension create flows. Supported hosts are `vscode`, `cursor`, and `kiro`. Each scope has one canonical `launch` choice: `none` | `auto` | `sesh` | `herdr`. `switch` stays independent, while any enabled launch implies switch handling for the newly created primary worktree.
+Package installations delegate to exactly one proven owner using `npm uninstall -g arashi`,
+`pnpm remove -g arashi`, `yarn global remove arashi`, `bun remove -g arashi`, or
+`vp uninstall -g arashi`. Current official direct installations are removed only when their
+schema-v2 manifest proves the exact payload and installer-created PATH state. Legacy,
+manual, modified, or ambiguous installations refuse automatic removal; refresh the same install
+with the current official installer and retry.
 
-Create precedence is: reject `--sesh` plus `--herdr`; then explicit `--sesh` / `--herdr`; `--tab` or `--launch`; `--no-launch`; the matching configured scope; and built-in `none`. `--tab` bypasses the matching configured scope unless an explicit launcher selector is present. An editor-hosted invocation does not fall back to terminal or another editor scope.
+If the CLI cannot run, use the installed `uninstall.sh` or `uninstall.ps1` helper with the exact
+install directory and dry-run first. Removal preserves workspaces, repositories, worktrees,
+`.arashi.yaml`, Git metadata, configuration, unrelated profile bytes, unrelated install-directory
+files, and the containing install directory.
 
-Legacy create booleans plus `launchMode` / `launch_mode` remain readable for a bounded compatibility window. Accepted combinations warn on stderr with the exact canonical replacement and do not rewrite the file. Disabled launch plus a launcher, conflicting aliases, and conflicting canonical/legacy choices are rejected before workspace mutation.
+## More documentation
 
-Defaults precedence for unrelated switch behavior remains unchanged.
-
-## skills.sh Integration
-
-Arashi also ships a dedicated `skills.sh` integration package for guided installation, workflow examples, and troubleshooting.
-
-- Skill repository: [`repos/arashi-skills`](../arashi-skills/README.md)
-- Canonical skill manifest: [`repos/arashi-skills/skills/arashi/SKILL.md`](../arashi-skills/skills/arashi/SKILL.md)
-- Workflow catalog: [`repos/arashi-skills/skills/arashi/references/workflows.md`](../arashi-skills/skills/arashi/references/workflows.md)
-- Session shortcuts: [`repos/arashi-skills/skills/arashi/references/session-shortcuts.md`](../arashi-skills/skills/arashi/references/session-shortcuts.md)
-
-## Documentation
-
-- Installation details: [`docs/INSTALLATION.md`](./docs/INSTALLATION.md)
-- Configuration details: [`docs/configuration.md`](./docs/configuration.md)
-- Clone command details: [`docs/commands/clone.md`](./docs/commands/clone.md)
-- Hook behavior: [`docs/hooks.md`](./docs/hooks.md)
-- Workflow guides: [https://arashi.haphazard.dev/workflows/](https://arashi.haphazard.dev/workflows/)
-- Shell integration details: [`docs/commands/shell.md`](./docs/commands/shell.md)
-- Setup command details: [`docs/commands/setup.md`](./docs/commands/setup.md)
-- Switch command details: [`docs/commands/switch.md`](./docs/commands/switch.md)
-- Remove command details: [`docs/commands/remove.md`](./docs/commands/remove.md)
-- Push command details: [`docs/commands/push.md`](./docs/commands/push.md)
-- FZF integration: [`docs/FZF_COMPATIBILITY.md`](./docs/FZF_COMPATIBILITY.md)
+- [Getting started](https://arashi.haphazard.dev/getting-started/)
+- [Configuration](https://arashi.haphazard.dev/workflows/config/)
+- [Hooks](https://arashi.haphazard.dev/workflows/hooks/)
+- [Editor and terminal integrations](https://arashi.haphazard.dev/workflows/)
+- [JSON automation](https://arashi.haphazard.dev/workflows/json-automation/)
+- [Local configuration reference](./docs/configuration.md)
 
 ## Contributing
 
-Use the canonical guide: [`CONTRIBUTING.md`](./CONTRIBUTING.md).
-
-For specs and planning workflow, see the specs repository: [github.com/corwinm/arashi-arashi](https://github.com/corwinm/arashi-arashi).
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Planning and specifications live in [corwinm/arashi-arashi](https://github.com/corwinm/arashi-arashi).
 
 ## License
 

package/bin/arashi.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, join, posix, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
 import { formatInstallError, getPlatformInfo, installBinary } from "./install-binary.js";
 import { runNpmManagedUpdate } from "./update.js";
 import { stringifyWrapperJsonEnvelope } from "./update-options.js";
@@ -88,6 +89,181 @@ export function isExplicitUpdateCommand(argv) {
   return argv[0] === "update";
 }
 
+export function isExplicitUninstallCommand(argv) {
+  return argv[0] === "uninstall";
+}
+
+const removalCommands = {
+  npm: ["npm", ["uninstall", "-g", "arashi"]],
+  pnpm: ["pnpm", ["remove", "-g", "arashi"]],
+  "yarn-classic": ["yarn", ["global", "remove", "arashi"]],
+  bun: ["bun", ["remove", "-g", "arashi"]],
+  "vite-plus": ["vp", ["uninstall", "-g", "arashi"]],
+};
+
+function normalizeEvidencePath(value, platform = currentPlatform) {
+  const normalized = String(value ?? "")
+    .replaceAll("\\", "/")
+    .replace(/\/+$/, "");
+  return platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function inferOwnerEvidence(
+  rootDir,
+  env = process.env,
+  realpath = realpathSync,
+  npmGlobalRoot,
+  platform = currentPlatform,
+) {
+  const normalized = normalizeEvidencePath(realpath(rootDir), platform);
+  const home = normalizeEvidencePath(env.HOME ?? env.USERPROFILE, platform);
+  const pnpmHome = normalizeEvidencePath(env.PNPM_HOME, platform);
+  const localAppData = normalizeEvidencePath(env.LOCALAPPDATA, platform);
+  const appData = normalizeEvidencePath(env.APPDATA, platform);
+  const configuredNpmPrefix = normalizeEvidencePath(env.NPM_CONFIG_PREFIX, platform);
+  const detectedNpmRoot = normalizeEvidencePath(npmGlobalRoot, platform);
+  const evidence = [];
+  const add = (owner) => {
+    if (!evidence.includes(owner)) evidence.push(owner);
+  };
+  if (
+    pnpmHome &&
+    normalized.startsWith(`${pnpmHome}/global/`) &&
+    /\/(?:\.pnpm\/[^/]+\/node_modules|node_modules)\/arashi$/.test(normalized)
+  )
+    add("pnpm");
+  if (home && normalized === `${home}/.bun/install/global/node_modules/arashi`) add("bun");
+  if (home && normalized === `${home}/.config/yarn/global/node_modules/arashi`)
+    add("yarn-classic");
+  if (
+    localAppData &&
+    normalized === `${localAppData}/yarn/data/global/node_modules/arashi`
+  )
+    add("yarn-classic");
+  if (normalized.includes("/.yarn/")) add("yarn-berry");
+  if (home && normalized === `${home}/.vite-plus/packages/arashi/current/package`)
+    add("vite-plus");
+  if (
+    normalized === "/usr/local/lib/node_modules/arashi" ||
+    normalized === "/usr/lib/node_modules/arashi" ||
+    normalized === "/opt/homebrew/lib/node_modules/arashi" ||
+    (home &&
+      (normalized === `${home}/.npm-global/lib/node_modules/arashi` ||
+        (normalized.startsWith(`${home}/.nvm/versions/node/`) &&
+          /\/lib\/node_modules\/arashi$/.test(normalized)))) ||
+    (appData && normalized === `${appData}/npm/node_modules/arashi`) ||
+    (configuredNpmPrefix &&
+      (normalized === `${configuredNpmPrefix}/lib/node_modules/arashi` ||
+        normalized === `${configuredNpmPrefix}/node_modules/arashi`)) ||
+    (detectedNpmRoot && normalized === `${detectedNpmRoot}/arashi`)
+  )
+    add("npm");
+  return evidence;
+}
+
+function spawnRemoval(command, args, options) {
+  const spawnImpl = options.spawnImpl ?? spawn;
+  return new Promise((resolve) => {
+    const child = spawnImpl(command, args, { stdio: "inherit" });
+    child.on("exit", (code) => resolve(typeof code === "number" ? code : 1));
+    child.on("error", (error) => {
+      (options.error ?? console.error)(`Failed to run ${command}. ${error.message}.`);
+      resolve(1);
+    });
+  });
+}
+
+export function detectNpmGlobalRoot(options = {}) {
+  try {
+    const output = (options.execFileSyncImpl ?? execFileSync)("npm", ["root", "-g"], {
+      encoding: "utf8",
+      env: options.env ?? process.env,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return String(output).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function runPackageUninstall(argv, options) {
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) {
+    (options.log ?? console.log)(`Usage: arashi uninstall [options]
+
+Conservatively remove a proven Arashi installation
+
+Options:
+  -n, --dry-run  Inspect the uninstall plan without changing anything
+  -y, --yes      Apply the completely preflighted uninstall plan
+  -h, --help     display help for command`);
+    return 0;
+  }
+  const unsupportedOption = argv.find((arg) => !["-n", "--dry-run", "-y", "--yes"].includes(arg));
+  if (unsupportedOption) {
+    (options.error ?? console.error)(`Unknown uninstall option: ${unsupportedOption}`);
+    return 1;
+  }
+  let evidence =
+    options.ownerEvidence ??
+    inferOwnerEvidence(
+      options.rootDir ?? join(__dirname, ".."),
+      options.env ?? process.env,
+      options.realpathSyncImpl ?? realpathSync,
+      options.npmGlobalRoot,
+      options.platform ?? currentPlatform,
+    );
+  if (options.ownerEvidence === undefined && evidence.length === 0 && options.npmGlobalRoot === undefined) {
+    const detectedNpmRoot = (options.detectNpmGlobalRoot ?? detectNpmGlobalRoot)({
+      env: options.env ?? process.env,
+    });
+    if (detectedNpmRoot) {
+      evidence = inferOwnerEvidence(
+        options.rootDir ?? join(__dirname, ".."),
+        options.env ?? process.env,
+        options.realpathSyncImpl ?? realpathSync,
+        detectedNpmRoot,
+        options.platform ?? currentPlatform,
+      );
+    }
+  }
+  if (evidence.length > 1) {
+    (options.error ?? console.error)(`Package-manager ownership is ambiguous: ${evidence.join(", ")}. No command was run.`);
+    return 1;
+  }
+  if (evidence.length === 0) {
+    (options.error ?? console.error)("Package-manager ownership is not proven. Remove the package manually with its known owner.");
+    return 1;
+  }
+  const selected = removalCommands[evidence[0]];
+  if (!selected) {
+    (options.error ?? console.error)(`Package-manager ownership is unsupported: ${evidence[0]}. No command was run.`);
+    return 1;
+  }
+  const [command, args] = selected;
+  (options.log ?? console.log)(`Package-manager uninstall: ${command} ${args.join(" ")}`);
+  if (argv.includes("-n") || argv.includes("--dry-run")) return 0;
+  if (!argv.includes("-y") && !argv.includes("--yes")) {
+    const interactive = options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (!interactive) {
+      (options.error ?? console.error)("Non-interactive package-manager uninstall requires --yes.");
+      return 1;
+    }
+    let accepted;
+    if (options.confirm) accepted = await options.confirm(false);
+    else {
+      const prompt = createInterface({ input: process.stdin, output: process.stdout });
+      try {
+        const answer = await prompt.question("Remove this package-managed Arashi installation? [y/N] ");
+        accepted = /^(?:y|yes)$/i.test(answer.trim());
+      } finally {
+        prompt.close();
+      }
+    }
+    if (!accepted) return 0;
+  }
+  return spawnRemoval(command, args, options);
+}
+
 async function runExplicitInstall(argv, options) {
   const binDir = options.binDir ?? __dirname;
   const rootDir = options.rootDir ?? join(binDir, "..");
@@ -169,6 +345,10 @@ export async function runEntrypoint(argv = process.argv.slice(2), options = {})
       return runNpmManagedUpdate(argv.slice(1), options);
     }
 
+    if (isExplicitUninstallCommand(argv)) {
+      return runPackageUninstall(argv.slice(1), options);
+    }
+
     await ensureInstalled({ ...options, argv });
   } catch (error) {
     errorLog(formatInstallError(error));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arashi",
-  "version": "1.33.0",
+  "version": "1.35.0",
   "description": "Git worktree manager for meta-repositories - The eye of the storm for your development workflow",
   "keywords": [
     "cli",
@@ -40,6 +40,8 @@
     "bin/aw.bat",
     "bin/aw.ps1",
     "schema/config.schema.json",
+    "scripts/uninstall.sh",
+    "scripts/uninstall.ps1",
     "README.md",
     "LICENSE"
   ],
@@ -110,5 +112,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "packageManager": "pnpm@11.20.0"
+  "packageManager": "pnpm@11.22.0"
 }

package/schema/config.schema.json

@@ -83,6 +83,10 @@
           "$ref": "#/definitions/ConfigVersion",
           "description": "Configuration schema version for migrations"
         },
+        "worktreeNaming": {
+          "$ref": "#/definitions/WorktreeNamingConfig",
+          "description": "Optional filesystem naming policy for configured create"
+        },
         "worktreesDir": {
           "description": "Base directory where worktrees are created (workspace-relative)",
           "type": "string"
@@ -285,6 +289,36 @@
     "SwitchMode": {
       "enum": ["auto", "cd", "launch", "sesh", "herdr"],
       "type": "string"
+    },
+    "WorktreeNamingBranchSlashes": {
+      "enum": ["preserve", "flatten"],
+      "type": "string"
+    },
+    "WorktreeNamingConfig": {
+      "additionalProperties": false,
+      "description": "Filesystem naming policy for configured create destinations.",
+      "properties": {
+        "branchSlashes": {
+          "$ref": "#/definitions/WorktreeNamingBranchSlashes",
+          "description": "Preserve branch slash hierarchy or flatten slashes to hyphens"
+        },
+        "maxPathLength": {
+          "description": "Maximum UTF-16 code units for each absolute newly planned configured-worktree destination",
+          "maximum": 2147483647,
+          "minimum": 1,
+          "multipleOf": 1,
+          "type": "number"
+        },
+        "style": {
+          "$ref": "#/definitions/WorktreeNamingStyle",
+          "description": "Repository-shape-aware default, branch-only, or repository-prefixed naming"
+        }
+      },
+      "type": "object"
+    },
+    "WorktreeNamingStyle": {
+      "enum": ["default", "branch", "repo-branch"],
+      "type": "string"
     }
   }
 }

package/scripts/uninstall.ps1

@@ -0,0 +1,208 @@
+#requires -Version 5.1
+[CmdletBinding()]
+param(
+    [string]$InstallDir = $env:ARASHI_INSTALL_DIR,
+    [switch]$DryRun,
+    [switch]$Yes,
+    [string]$ParentPid,
+    [switch]$TemporarySelf
+)
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+if ([string]::IsNullOrWhiteSpace($InstallDir)) { $InstallDir = Join-Path $env:USERPROFILE ".arashi\bin" }
+$InstallDir = [System.IO.Path]::GetFullPath($InstallDir)
+$ManifestPath = Join-Path $InstallDir ".arashi-managed-entrypoints.json"
+
+function Get-ProfileEncoding([byte[]]$Bytes) {
+    if ($Bytes.Length -ge 4 -and $Bytes[0] -eq 0x00 -and $Bytes[1] -eq 0x00 -and $Bytes[2] -eq 0xFE -and $Bytes[3] -eq 0xFF) { return @((New-Object System.Text.UTF32Encoding($true, $false, $true)), 4) }
+    if ($Bytes.Length -ge 4 -and $Bytes[0] -eq 0xFF -and $Bytes[1] -eq 0xFE -and $Bytes[2] -eq 0x00 -and $Bytes[3] -eq 0x00) { return @((New-Object System.Text.UTF32Encoding($false, $false, $true)), 4) }
+    if ($Bytes.Length -ge 3 -and $Bytes[0] -eq 0xEF -and $Bytes[1] -eq 0xBB -and $Bytes[2] -eq 0xBF) { return @((New-Object System.Text.UTF8Encoding($false, $true)), 3) }
+    if ($Bytes.Length -ge 2 -and $Bytes[0] -eq 0xFE -and $Bytes[1] -eq 0xFF) { return @((New-Object System.Text.UnicodeEncoding($true, $false, $true)), 2) }
+    if ($Bytes.Length -ge 2 -and $Bytes[0] -eq 0xFF -and $Bytes[1] -eq 0xFE) { return @((New-Object System.Text.UnicodeEncoding($false, $false, $true)), 2) }
+    return @((New-Object System.Text.UTF8Encoding($false, $true)), 0)
+}
+
+function Find-ByteSequence([byte[]]$Bytes, [byte[]]$Needle) {
+    $matches = New-Object System.Collections.Generic.List[int]
+    for ($offset = 0; $offset -le $Bytes.Length - $Needle.Length; $offset++) {
+        $matched = $true
+        for ($index = 0; $index -lt $Needle.Length; $index++) {
+            if ($Bytes[$offset + $index] -ne $Needle[$index]) { $matched = $false; break }
+        }
+        if ($matched) { $matches.Add($offset) }
+    }
+    return @($matches)
+}
+
+function Test-BytesAt([byte[]]$Bytes, [int]$Offset, [byte[]]$Needle) {
+    if ($Offset -lt 0 -or $Offset + $Needle.Length -gt $Bytes.Length) { return $false }
+    for ($index = 0; $index -lt $Needle.Length; $index++) {
+        if ($Bytes[$Offset + $index] -ne $Needle[$index]) { return $false }
+    }
+    return $true
+}
+
+function Get-CanonicalMarkerPlan([byte[]]$Bytes) {
+    $encodingInfo = Get-ProfileEncoding $Bytes
+    $encoding = $encodingInfo[0]
+    $contentStart = [int]$encodingInfo[1]
+    $beginBytes = $encoding.GetBytes("# >>> arashi shell integration >>>")
+    $endBytes = $encoding.GetBytes("# <<< arashi shell integration <<<")
+    $lfBytes = $encoding.GetBytes("`n")
+    $crlfBytes = $encoding.GetBytes("`r`n")
+    $rawBegins = @(Find-ByteSequence $Bytes $beginBytes)
+    $rawEnds = @(Find-ByteSequence $Bytes $endBytes)
+    $canonicalBegins = @($rawBegins | Where-Object {
+        ($_ -eq $contentStart -or (Test-BytesAt $Bytes ($_ - $lfBytes.Length) $lfBytes)) -and
+        ($_ + $beginBytes.Length -eq $Bytes.Length -or (Test-BytesAt $Bytes ($_ + $beginBytes.Length) $lfBytes) -or (Test-BytesAt $Bytes ($_ + $beginBytes.Length) $crlfBytes))
+    })
+    $canonicalEnds = @($rawEnds | Where-Object {
+        ($_ -eq $contentStart -or (Test-BytesAt $Bytes ($_ - $lfBytes.Length) $lfBytes)) -and
+        ($_ + $endBytes.Length -eq $Bytes.Length -or (Test-BytesAt $Bytes ($_ + $endBytes.Length) $lfBytes) -or (Test-BytesAt $Bytes ($_ + $endBytes.Length) $crlfBytes))
+    })
+    if ($rawBegins.Count -eq 0 -and $rawEnds.Count -eq 0) { return $null }
+    if ($rawBegins.Count -ne 1 -or $rawEnds.Count -ne 1 -or $canonicalBegins.Count -ne 1 -or $canonicalEnds.Count -ne 1 -or $canonicalBegins[0] -ge $canonicalEnds[0]) {
+        throw "Ambiguous Arashi shell integration markers; only a complete canonical marker line can be removed."
+    }
+    $blockEnd = $canonicalEnds[0] + $endBytes.Length
+    $after = New-Object byte[] ($Bytes.Length - ($blockEnd - $canonicalBegins[0]))
+    [System.Array]::Copy($Bytes, 0, $after, 0, $canonicalBegins[0])
+    [System.Array]::Copy($Bytes, $blockEnd, $after, $canonicalBegins[0], $Bytes.Length - $blockEnd)
+    return [PSCustomObject]@{ Start = $canonicalBegins[0]; End = $blockEnd; After = $after }
+}
+
+try {
+    if (-not [string]::IsNullOrWhiteSpace($ParentPid)) {
+        $parsed = 0
+        if (-not [int]::TryParse($ParentPid, [ref]$parsed) -or $parsed -le 0) { throw "Invalid parent PID." }
+        try {
+            Wait-Process -Id $parsed -Timeout 120 -ErrorAction Stop
+        } catch [Microsoft.PowerShell.Commands.ProcessCommandException] {
+            if (Get-Process -Id $parsed -ErrorAction SilentlyContinue) { throw "Timed out waiting for parent process $parsed." }
+        }
+    }
+    $installItem = Get-Item -LiteralPath $InstallDir -Force -ErrorAction Stop
+    if (-not $installItem.PSIsContainer -or ($installItem.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) { throw "Install directory is not a non-reparse directory." }
+    $manifestItem = Get-Item -LiteralPath $ManifestPath -Force -ErrorAction Stop
+    if ($manifestItem.PSIsContainer -or ($manifestItem.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) { throw "Ownership manifest is not a regular non-reparse file." }
+    $manifestBytes = [System.IO.File]::ReadAllBytes($ManifestPath)
+    $manifestEncoding = New-Object System.Text.UTF8Encoding($false, $true)
+    $manifestText = $manifestEncoding.GetString($manifestBytes).TrimStart([char]0xFEFF)
+    $manifest = $manifestText | ConvertFrom-Json
+    $manifestProperties = @($manifest.PSObject.Properties.Name | Sort-Object)
+    if (($manifestProperties -join ',') -cnotin @('files,installationChannel,installDirectory,platform,schemaVersion', 'files,installationChannel,installDirectory,pathMutation,platform,schemaVersion')) { throw "Manifest property set is not closed." }
+    if ($manifest.schemaVersion -isnot [int] -or $manifest.schemaVersion -ne 2 -or $manifest.installationChannel -isnot [string] -or $manifest.installationChannel -cne "official-direct" -or $manifest.platform -isnot [string] -or $manifest.platform -cne "windows" -or $manifest.installDirectory -isnot [string]) { throw "Unsupported manifest; refresh this direct install first." }
+    if ([System.IO.Path]::GetFullPath($manifest.installDirectory) -cne $InstallDir) { throw "Manifest installDirectory mismatch." }
+    $expected = @(
+        @("arashi.bin.exe", "native-executable"), @("arashi", "canonical-wrapper"),
+        @("arashi.ps1", "canonical-powershell-wrapper"), @("arashi.bat", "canonical-cmd-wrapper"),
+        @("aw", "alias-wrapper"), @("aw.ps1", "alias-powershell-wrapper"),
+        @("aw.bat", "alias-cmd-wrapper"), @("uninstall.ps1", "uninstall-helper")
+    )
+    if (@($manifest.files).Count -ne $expected.Count) { throw "Manifest payload mismatch." }
+    $removable = New-Object System.Collections.Generic.List[string]
+    for ($index = 0; $index -lt $expected.Count; $index++) {
+        $record = @($manifest.files)[$index]
+        $properties = @($record.PSObject.Properties.Name | Sort-Object)
+        if (($properties -join ',') -cne 'digest,relativePath,role' -or $record.relativePath -isnot [string] -or $record.role -isnot [string] -or $record.digest -isnot [string] -or $record.relativePath -cne $expected[$index][0] -or $record.role -cne $expected[$index][1] -or $record.digest -cnotmatch '^[a-f0-9]{64}$') { throw "Invalid payload record $index." }
+        $path = [System.IO.Path]::GetFullPath((Join-Path $InstallDir $record.relativePath))
+        if ((Split-Path -Parent $path) -cne $InstallDir) { throw "Escaping payload path." }
+        $item = Get-Item -LiteralPath $path -Force -ErrorAction SilentlyContinue
+        if ($null -eq $item) { continue }
+        if ($item.PSIsContainer -or ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) { throw "$($record.relativePath) is not a regular non-reparse file." }
+        if ((Get-FileHash -Algorithm SHA256 -LiteralPath $path).Hash.ToLowerInvariant() -cne $record.digest) { throw "$($record.relativePath) digest mismatch." }
+        $removable.Add($path)
+    }
+    $pathEntryToRemove = $null
+    if ($manifestProperties -contains 'pathMutation') {
+        $pathProperties = @($manifest.pathMutation.PSObject.Properties.Name | Sort-Object)
+        if (($pathProperties -join ',') -cne 'created,entry' -or $manifest.pathMutation.created -isnot [bool] -or $manifest.pathMutation.entry -isnot [string] -or [string]::IsNullOrEmpty($manifest.pathMutation.entry)) { throw "Invalid user PATH provenance." }
+        if ($manifest.pathMutation.created) {
+            $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+            $userPathEntries = if ([string]::IsNullOrEmpty($userPath)) { @() } else { @($userPath -split ';') }
+            $matches = @($userPathEntries | Where-Object { $_ -ceq $manifest.pathMutation.entry })
+            if ($matches.Count -eq 1) { $pathEntryToRemove = $manifest.pathMutation.entry }
+            elseif ($matches.Count -gt 1) { Write-Warning "Created user PATH entry is ambiguous and will be preserved." }
+        }
+        # created: false is deliberately preserved.
+    }
+    $shellPlans = @()
+    $shellHome = if (-not [string]::IsNullOrWhiteSpace($env:HOME)) { $env:HOME } else { $env:USERPROFILE }
+    if (-not [string]::IsNullOrWhiteSpace($shellHome)) {
+        $shellCandidates = @(
+            (Join-Path $shellHome ".zshrc"),
+            (Join-Path $shellHome ".config\fish\config.fish"),
+            (Join-Path $shellHome ".bashrc"),
+            (Join-Path $shellHome ".bash_profile"),
+            (Join-Path $shellHome ".profile")
+        ) | Select-Object -Unique
+        foreach ($shellTarget in $shellCandidates) {
+            $shellItem = Get-Item -LiteralPath $shellTarget -Force -ErrorAction SilentlyContinue
+            if ($null -eq $shellItem) { continue }
+            if ($shellItem.PSIsContainer -or ($shellItem.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) {
+                Write-Warning "Preserving unsafe shell startup target: $shellTarget"
+                continue
+            }
+            $shellBytes = [System.IO.File]::ReadAllBytes($shellTarget)
+            try { $markerPlan = Get-CanonicalMarkerPlan $shellBytes } catch { throw "$($_.Exception.Message) Target: $shellTarget" }
+            if ($null -ne $markerPlan) { $shellPlans += [PSCustomObject]@{ Path = $shellTarget; Before = $shellBytes; After = $markerPlan.After } }
+        }
+    }
+    Write-Host "Installation channel: official-direct"
+    foreach ($path in $removable) { Write-Host "- remove: $path" }
+    foreach ($shellPlan in $shellPlans) { Write-Host "- remove exact managed shell block: $($shellPlan.Path)" }
+    Write-Host "Preserved: projects, Git data, unrelated user state, and install-directory neighbors."
+    if ($DryRun) { exit 0 }
+    if (-not $Yes) {
+        if ([Console]::IsInputRedirected -or [Console]::IsOutputRedirected) { throw "Non-interactive uninstall requires -Yes." }
+        if ((Read-Host "Remove this proven Arashi installation? [y/N]") -notmatch '^(?i:y|yes)$') { Write-Host "Uninstall declined."; exit 0 }
+    }
+    $currentInstallItem = Get-Item -LiteralPath $InstallDir -Force -ErrorAction Stop
+    if (-not $currentInstallItem.PSIsContainer -or ($currentInstallItem.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) { throw "Install directory changed after preflight." }
+    $currentManifestItem = Get-Item -LiteralPath $ManifestPath -Force -ErrorAction Stop
+    if ($currentManifestItem.PSIsContainer -or ($currentManifestItem.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) { throw "Ownership manifest changed after preflight." }
+    $currentManifestBytes = [System.IO.File]::ReadAllBytes($ManifestPath)
+    if ([Convert]::ToBase64String($currentManifestBytes) -cne [Convert]::ToBase64String($manifestBytes)) { throw "Ownership manifest changed after preflight." }
+    for ($index = 0; $index -lt $expected.Count; $index++) {
+        $record = @($manifest.files)[$index]
+        $path = [System.IO.Path]::GetFullPath((Join-Path $InstallDir $record.relativePath))
+        if ($removable -notcontains $path) { continue }
+        $item = Get-Item -LiteralPath $path -Force -ErrorAction Stop
+        if ($item.PSIsContainer -or ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) { throw "$($record.relativePath) changed after preflight." }
+        if ((Get-FileHash -Algorithm SHA256 -LiteralPath $path).Hash.ToLowerInvariant() -cne $record.digest) { throw "$($record.relativePath) changed after preflight." }
+    }
+    foreach ($shellPlan in $shellPlans) {
+        $currentShellBytes = [System.IO.File]::ReadAllBytes($shellPlan.Path)
+        if ([Convert]::ToBase64String($currentShellBytes) -cne [Convert]::ToBase64String($shellPlan.Before)) { throw "Shell startup file changed after preflight." }
+        $shellTemporary = "$($shellPlan.Path).arashi-uninstall-$([System.Guid]::NewGuid().ToString('N')).tmp"
+        try {
+            [System.IO.File]::WriteAllBytes($shellTemporary, $shellPlan.After)
+            Move-Item -LiteralPath $shellTemporary -Destination $shellPlan.Path -Force
+        } finally { Remove-Item -LiteralPath $shellTemporary -Force -ErrorAction SilentlyContinue }
+    }
+    if ($null -ne $pathEntryToRemove) {
+        $currentUserPath = [Environment]::GetEnvironmentVariable("Path", "User")
+        $entriesBeforeRemoval = if ([string]::IsNullOrEmpty($currentUserPath)) { @() } else { @($currentUserPath -split ';') }
+        $currentMatches = @($entriesBeforeRemoval | Where-Object { $_ -ceq $pathEntryToRemove })
+        if ($currentMatches.Count -ne 1) { throw "Created user PATH entry changed after preflight." }
+        $removed = $false
+        $entries = @($entriesBeforeRemoval | Where-Object {
+            if (-not $removed -and $_ -ceq $pathEntryToRemove) { $removed = $true; return $false }
+            return $true
+        })
+        [Environment]::SetEnvironmentVariable("Path", ($entries -join ';'), "User")
+    }
+    foreach ($path in $removable) { Remove-Item -LiteralPath $path -Force }
+    Remove-Item -LiteralPath $ManifestPath -Force
+} catch {
+    [Console]::Error.WriteLine("error: $($_.Exception.Message)")
+    exit 1
+} finally {
+    if ($TemporarySelf) {
+        $self = $MyInvocation.MyCommand.Path
+        $selfDirectory = Split-Path -Parent $self
+        if ([System.IO.Path]::GetFileName($selfDirectory) -like "arashi-uninstall-*" -and [System.IO.Path]::GetFileName($self) -ceq "uninstall.ps1") {
+            Start-Process -FilePath "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -WindowStyle Hidden -ArgumentList @('-NoProfile','-Command',"Start-Sleep -Milliseconds 100; Remove-Item -LiteralPath '$($self.Replace("'", "''"))' -Force; Remove-Item -LiteralPath '$($selfDirectory.Replace("'", "''"))' -Force -ErrorAction SilentlyContinue")
+        }
+    }
+}

package/scripts/uninstall.sh

@@ -0,0 +1,303 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+INSTALL_DIR="${ARASHI_INSTALL_DIR:-}"
+HOME_DIR="${HOME:-}"
+DRY_RUN=false
+YES=false
+PARENT_PID=""
+TEMPORARY_SELF=false
+
+fail() { printf 'error: %s\n' "$*" >&2; exit 1; }
+usage() {
+  printf '%s\n' 'Usage: uninstall.sh [--install-dir <path>] [--home-dir <path>] [--dry-run|-n] [--yes|-y] [--parent-pid <pid>]'
+}
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --install-dir) shift; [ "$#" -gt 0 ] || fail "Missing --install-dir value"; INSTALL_DIR="$1" ;;
+    --home-dir) shift; [ "$#" -gt 0 ] || fail "Missing --home-dir value"; HOME_DIR="$1" ;;
+    --dry-run|-n) DRY_RUN=true ;;
+    --yes|-y) YES=true ;;
+    --parent-pid) shift; [ "$#" -gt 0 ] || fail "Missing --parent-pid value"; PARENT_PID="$1" ;;
+    --temporary-self) TEMPORARY_SELF=true ;;
+    --help|-h) usage; exit 0 ;;
+    *) fail "Unknown argument: $1" ;;
+  esac
+  shift
+done
+
+if [ -z "$INSTALL_DIR" ]; then
+  [ -n "$HOME_DIR" ] || fail "HOME is required when --install-dir is omitted"
+  INSTALL_DIR="$HOME_DIR/.arashi/bin"
+fi
+if [ -n "$HOME_DIR" ]; then
+  case "$HOME_DIR" in /*) ;; *) fail "--home-dir must be an absolute path" ;; esac
+fi
+
+cleanup_self() {
+  if [ "$TEMPORARY_SELF" = true ]; then
+    self_path="${BASH_SOURCE[0]}"
+    self_dir="$(dirname "$self_path")"
+    case "$(basename "$self_dir"):$(basename "$self_path")" in
+      arashi-uninstall-*:uninstall.sh)
+        rm -f -- "$self_path"
+        rmdir "$self_dir" 2>/dev/null || true
+        ;;
+    esac
+  fi
+}
+trap cleanup_self EXIT
+
+case "$PARENT_PID" in
+  "") ;;
+  *[!0-9]*) fail "Invalid parent PID" ;;
+  *)
+    waited=0
+    while kill -0 "$PARENT_PID" 2>/dev/null; do
+      [ "$waited" -lt 120 ] || fail "Timed out waiting for parent process $PARENT_PID"
+      sleep 1
+      waited=$((waited + 1))
+    done
+    ;;
+esac
+
+normalize_absolute_path() {
+  local input="$1" part output="" index
+  local parts=() normalized=()
+  case "$input" in /*) ;; *) input="$(pwd)/$input" ;; esac
+  IFS='/' read -r -a parts <<< "$input"
+  for part in "${parts[@]}"; do
+    case "$part" in
+      ''|.) ;;
+      ..) if [ "${#normalized[@]}" -gt 0 ]; then index=$((${#normalized[@]} - 1)); unset "normalized[$index]"; fi ;;
+      *) normalized+=("$part") ;;
+    esac
+  done
+  for index in "${!normalized[@]}"; do output="$output/${normalized[$index]}"; done
+  printf '%s\n' "${output:-/}"
+}
+
+INSTALL_DIR="$(normalize_absolute_path "$INSTALL_DIR")"
+[ ! -L "$INSTALL_DIR" ] && [ -d "$INSTALL_DIR" ] || fail "install directory is not a regular non-link directory"
+MANIFEST_PATH="$INSTALL_DIR/.arashi-managed-entrypoints.json"
+[ ! -L "$MANIFEST_PATH" ] && [ -f "$MANIFEST_PATH" ] && [ -r "$MANIFEST_PATH" ] || fail "ownership manifest is not a regular non-link file"
+
+sha256_file() {
+  if command -v shasum >/dev/null 2>&1; then shasum -a 256 "$1" | cut -d ' ' -f1
+  elif command -v sha256sum >/dev/null 2>&1; then sha256sum "$1" | cut -d ' ' -f1
+  elif command -v openssl >/dev/null 2>&1; then openssl dgst -sha256 "$1" | awk '{print $NF}'
+  else fail "No SHA-256 tool found (tried shasum, sha256sum, and openssl)"
+  fi
+}
+
+decode_hex() {
+  LC_ALL=C awk -v value="$1" 'function d(c){return index("0123456789abcdef",c)-1} BEGIN{for(i=1;i<=length(value);i+=2)printf "%c",d(substr(value,i,1))*16+d(substr(value,i+1,1))}'
+}
+
+parse_manifest() {
+  LC_ALL=C awk '
+  function bad(message) { print "error: " message > "/dev/stderr"; exit 2 }
+  function ws() { while (p <= n && substr(s,p,1) ~ /[ \t\r\n]/) p++ }
+  function take(c) { ws(); if (substr(s,p,1) != c) bad("malformed ownership manifest"); p++ }
+  function string(    out,c,e) {
+    ws(); if (substr(s,p,1) != "\"") bad("expected manifest string"); p++; out=""
+    while (p <= n) {
+      c=substr(s,p++,1)
+      if (c == "\"") return out
+      if (c == "\\") {
+        if (p > n) bad("malformed string escape"); e=substr(s,p++,1)
+        if (e == "\"" || e == "\\" || e == "/") c=e
+        else if (e == "b") c=sprintf("%c",8)
+        else if (e == "f") c=sprintf("%c",12)
+        else if (e == "n") c="\n"
+        else if (e == "r") c="\r"
+        else if (e == "t") c="\t"
+        else bad("unsupported manifest string escape")
+      } else if (c ~ /[\001-\037]/) bad("control byte in manifest string")
+      out=out c
+    }
+    bad("unterminated manifest string")
+  }
+  function hex(value,    i,c,out) { out=""; for(i=1;i<=length(value);i++){c=substr(value,i,1); out=out sprintf("%02x",ord[c])} return out }
+  function scalar_number(    start) { ws(); start=p; while(substr(s,p,1) ~ /[0-9]/)p++; if(start==p)bad("expected manifest number"); return substr(s,start,p-start) }
+  function file_record(idx,    key,path,role,digest,count) {
+    take("{"); count=0; delete file_seen
+    while (1) {
+      ws(); if (substr(s,p,1)=="}"){p++;break}
+      if(count++)take(","); key=string(); if(file_seen[key]++)bad("duplicate payload property"); take(":")
+      if(key=="relativePath")path=string(); else if(key=="role")role=string(); else if(key=="digest")digest=string(); else bad("payload property set is not closed")
+    }
+    if(count!=3 || path!=expected_path[idx] || role!=expected_role[idx] || digest !~ /^[a-f0-9]{64}$/)bad("invalid payload record")
+    print "FILE " idx " " digest
+  }
+  function files(    count) {
+    take("["); count=0
+    while (1) { ws(); if(substr(s,p,1)=="]"){p++;break}; if(count)take(","); if(count>=4)bad("payload file set mismatch"); file_record(count); count++ }
+    if(count!=4)bad("payload file set mismatch")
+  }
+  function mutation(    key,profile,inserted,count) {
+    take("{"); count=0; delete mutation_seen
+    while(1){ws();if(substr(s,p,1)=="}"){p++;break};if(count++)take(",");key=string();if(mutation_seen[key]++)bad("duplicate pathMutation property");take(":");if(key=="profilePath")profile=string();else if(key=="insertedBytes")inserted=string();else bad("pathMutation property set is not closed")}
+    if(count!=2 || profile=="" || substr(profile,1,1)!="/" || inserted=="")bad("invalid POSIX pathMutation")
+    print "PROFILE " hex(profile); print "INSERT " hex(inserted)
+  }
+  BEGIN {
+    for(i=0;i<256;i++)ord[sprintf("%c",i)]=i
+    expected_path[0]="arashi.bin"; expected_role[0]="native-executable"
+    expected_path[1]="arashi"; expected_role[1]="canonical-wrapper"
+    expected_path[2]="aw"; expected_role[2]="alias-wrapper"
+    expected_path[3]="uninstall.sh"; expected_role[3]="uninstall-helper"
+    while((getline line)>0){if(seen_line++)s=s"\n";s=s line} n=length(s);p=1;take("{");count=0
+    while(1){ws();if(substr(s,p,1)=="}"){p++;break};if(count++)take(",");key=string();if(top_seen[key]++)bad("duplicate manifest property");take(":")
+      if(key=="schemaVersion"){if(scalar_number()!="2")bad("unsupported schema; refresh this direct install first")}
+      else if(key=="installationChannel"){if(string()!="official-direct")bad("unsupported installation ownership")}
+      else if(key=="platform"){if(string()!="posix")bad("unsupported installation ownership")}
+      else if(key=="installDirectory")print "INSTALL " hex(string())
+      else if(key=="files")files()
+      else if(key=="pathMutation")mutation()
+      else bad("manifest property set is not closed")
+    }
+    ws();if(p<=n)bad("trailing manifest data")
+    if(!top_seen["schemaVersion"]||!top_seen["installationChannel"]||!top_seen["platform"]||!top_seen["installDirectory"]||!top_seen["files"]||count<5||count>6)bad("manifest property set is not closed")
+  }' "$MANIFEST_PATH"
+}
+
+PARSED_MANIFEST="$(mktemp "${TMPDIR:-/tmp}/arashi-manifest.XXXXXX")" || fail "Unable to stage manifest validation"
+INSERTED_FILE="$(mktemp "${TMPDIR:-/tmp}/arashi-inserted.XXXXXX")" || fail "Unable to stage PATH provenance"
+cleanup_work_files() { rm -f -- "$PARSED_MANIFEST" "$PARSED_MANIFEST.recheck" "$INSERTED_FILE"; }
+trap 'cleanup_work_files; cleanup_self' EXIT
+parse_manifest > "$PARSED_MANIFEST" || fail "ownership manifest validation failed"
+
+MANIFEST_INSTALL=""
+PROFILE_PATH=""
+FILE_DIGESTS=()
+while IFS=' ' read -r kind first second; do
+  case "$kind" in
+    INSTALL) MANIFEST_INSTALL="$(decode_hex "$first")" ;;
+    FILE) FILE_DIGESTS[$first]="$second" ;;
+    PROFILE) PROFILE_PATH="$(decode_hex "$first")" ;;
+    INSERT) decode_hex "$first" > "$INSERTED_FILE" ;;
+    *) fail "invalid parsed manifest record" ;;
+  esac
+done < "$PARSED_MANIFEST"
+[ "$MANIFEST_INSTALL" = "$INSTALL_DIR" ] || fail "installDirectory mismatch"
+
+file_occurrences() {
+  local haystack="$1" needle="$2" haystack_size needle_size offset count=0 first=-1 candidate first_byte
+  haystack_size="$(wc -c < "$haystack" | tr -d '[:space:]')"
+  needle_size="$(wc -c < "$needle" | tr -d '[:space:]')"
+  [ "$needle_size" -gt 0 ] || { printf '0 -1\n'; return; }
+  candidate="$(mktemp "${TMPDIR:-/tmp}/arashi-match.XXXXXX")" || fail "Unable to stage byte comparison"
+  first_byte="$(od -An -N1 -t u1 "$needle" | tr -d '[:space:]')"
+  while read -r offset; do
+    [ "$offset" -le $((haystack_size - needle_size)) ] || continue
+    dd if="$haystack" of="$candidate" bs=1 skip="$offset" count="$needle_size" 2>/dev/null
+    if cmp -s "$candidate" "$needle"; then count=$((count + 1)); [ "$first" -ge 0 ] || first="$offset"; fi
+  done < <(od -An -v -t u1 "$haystack" | awk -v wanted="$first_byte" '{for(i=1;i<=NF;i++){if($i==wanted)print offset;offset++}}')
+  rm -f -- "$candidate"
+  printf '%s %s\n' "$count" "$first"
+}
+
+marker_state() {
+  LC_ALL=C awk -v begin='# >>> arashi shell integration >>>' -v end='# <<< arashi shell integration <<<' '
+    function occurrences(line,needle,  at,count,rest){rest=line;while((at=index(rest,needle))>0){count++;rest=substr(rest,at+length(needle))}return count}
+    { raw_begin+=occurrences($0,begin);raw_end+=occurrences($0,end);if($0==begin || $0==begin "\r"){exact_begin++;begin_offset=offset}if($0==end || $0==end "\r"){exact_end++;end_offset=offset+length(end)}offset+=length($0)+1 }
+    END{print raw_begin+0,raw_end+0,exact_begin+0,exact_end+0,begin_offset+0,end_offset+0}' "$1"
+}
+
+copy_without_range() {
+  local path="$1" start="$2" end="$3" size temporary
+  size="$(wc -c < "$path" | tr -d '[:space:]')"
+  temporary="$(mktemp "$(dirname "$path")/.arashi-uninstall.XXXXXX")" || fail "Unable to stage profile rewrite"
+  cp -p "$path" "$temporary" || { rm -f -- "$temporary"; fail "Unable to preserve profile metadata"; }
+  : > "$temporary"
+  if [ "$start" -gt 0 ]; then dd if="$path" of="$temporary" bs=1 count="$start" 2>/dev/null; fi
+  if [ "$end" -lt "$size" ]; then dd if="$path" of="$temporary" bs=1 skip="$end" seek="$start" 2>/dev/null; fi
+  mv -f -- "$temporary" "$path"
+}
+
+EXPECTED_NAMES=("arashi.bin" "arashi" "aw" "uninstall.sh")
+FILE_ACTIONS=()
+SHELL_PATHS=()
+SHELL_STARTS=()
+SHELL_ENDS=()
+SHELL_DIGESTS=()
+SHELL_PRESERVED=()
+SHELL_PRESERVED_COUNT=0
+PROFILE_ACTION=""
+PROFILE_OFFSET=-1
+
+preflight() {
+  local blockers="" index name path actual state raw_begin raw_end exact_begin exact_end begin_offset end_offset count offset normalized_profile
+  FILE_ACTIONS=(); SHELL_PATHS=(); SHELL_STARTS=(); SHELL_ENDS=(); SHELL_DIGESTS=(); SHELL_PRESERVED=(); SHELL_PRESERVED_COUNT=0; PROFILE_ACTION=""; PROFILE_OFFSET=-1
+  [ ! -L "$MANIFEST_PATH" ] && [ -f "$MANIFEST_PATH" ] || fail "ownership manifest changed after preflight"
+  parse_manifest > "$PARSED_MANIFEST.recheck" || fail "ownership manifest changed after preflight"
+  cmp -s "$PARSED_MANIFEST" "$PARSED_MANIFEST.recheck" || fail "ownership manifest changed after preflight"
+  rm -f -- "$PARSED_MANIFEST.recheck"
+  for index in 0 1 2 3; do
+    name="${EXPECTED_NAMES[$index]}"; path="$INSTALL_DIR/$name"
+    if [ ! -e "$path" ] && [ ! -L "$path" ]; then FILE_ACTIONS[$index]="absent"
+    elif [ -L "$path" ]; then blockers="${blockers}\n- $name is a symbolic link"
+    elif [ ! -f "$path" ]; then blockers="${blockers}\n- $name is not a regular file"
+    else actual="$(sha256_file "$path")"; if [ "$actual" != "${FILE_DIGESTS[$index]}" ]; then blockers="${blockers}\n- $name digest mismatch (modified)"; else FILE_ACTIONS[$index]="remove"; fi
+    fi
+  done
+  if [ -n "$PROFILE_PATH" ]; then
+    case "$PROFILE_PATH" in /*) ;; *) fail "invalid POSIX pathMutation" ;; esac
+    if [ ! -e "$PROFILE_PATH" ] && [ ! -L "$PROFILE_PATH" ]; then PROFILE_ACTION="absent"
+    elif [ -L "$PROFILE_PATH" ] || [ ! -f "$PROFILE_PATH" ] || [ ! -r "$PROFILE_PATH" ]; then PROFILE_ACTION="preserved"
+    else
+      normalized_profile="$(normalize_absolute_path "$PROFILE_PATH")"
+      [ "$normalized_profile" = "$PROFILE_PATH" ] || fail "invalid POSIX pathMutation"
+      read -r count offset < <(file_occurrences "$PROFILE_PATH" "$INSERTED_FILE")
+      if [ "$count" -eq 1 ]; then PROFILE_ACTION="remove"; PROFILE_OFFSET="$offset"
+      elif [ "$count" -eq 0 ]; then PROFILE_ACTION="absent"
+      else PROFILE_ACTION="preserved"
+      fi
+    fi
+  fi
+  if [ -n "$HOME_DIR" ]; then
+    local candidates=("$HOME_DIR/.zshrc" "$HOME_DIR/.config/fish/config.fish")
+    if [ "$(uname -s 2>/dev/null || true)" = "Darwin" ]; then candidates+=("$HOME_DIR/.bash_profile" "$HOME_DIR/.bashrc" "$HOME_DIR/.profile"); else candidates+=("$HOME_DIR/.bashrc" "$HOME_DIR/.bash_profile" "$HOME_DIR/.profile"); fi
+    for path in "${candidates[@]}"; do
+      [ -e "$path" ] || [ -L "$path" ] || continue
+      if [ -L "$path" ] || [ ! -f "$path" ] || [ ! -r "$path" ]; then SHELL_PRESERVED[$SHELL_PRESERVED_COUNT]="$path"; SHELL_PRESERVED_COUNT=$((SHELL_PRESERVED_COUNT + 1)); continue; fi
+      read -r raw_begin raw_end exact_begin exact_end begin_offset end_offset < <(marker_state "$path")
+      if [ "$raw_begin" -eq 0 ] && [ "$raw_end" -eq 0 ]; then continue; fi
+      if [ "$raw_begin" -ne 1 ] || [ "$raw_end" -ne 1 ] || [ "$exact_begin" -ne 1 ] || [ "$exact_end" -ne 1 ] || [ "$begin_offset" -ge "$end_offset" ]; then blockers="${blockers}\n- ambiguous shell integration markers in $path"; continue; fi
+      index="${#SHELL_PATHS[@]}"; SHELL_PATHS[$index]="$path"; SHELL_STARTS[$index]="$begin_offset"; SHELL_ENDS[$index]="$end_offset"; SHELL_DIGESTS[$index]="$(sha256_file "$path")"
+    done
+  fi
+  [ -z "$blockers" ] || fail "preflight refused:$(printf '%b' "$blockers")"
+}
+
+preflight
+printf 'Installation channel: official-direct\nInstall directory: %s\n' "$INSTALL_DIR"
+for index in 0 1 2 3; do printf -- '- %s: %s\n' "${FILE_ACTIONS[$index]}" "${EXPECTED_NAMES[$index]}"; done
+[ -z "$PROFILE_ACTION" ] || printf -- '- PATH state: %s\n' "$PROFILE_ACTION"
+if [ "${#SHELL_PATHS[@]}" -gt 0 ]; then
+  for path in "${SHELL_PATHS[@]}"; do printf -- '- remove exact managed shell block: %s\n' "$path"; done
+fi
+if [ "$SHELL_PRESERVED_COUNT" -gt 0 ]; then
+  for path in "${SHELL_PRESERVED[@]}"; do printf -- '- preserved unsafe shell startup target: %s (not a readable regular non-link file)\n' "$path"; done
+fi
+printf '%s\n' 'Preserved: projects, Git data, configuration, unrelated profile bytes, install-directory neighbors, and the install directory.'
+[ "$DRY_RUN" = false ] || exit 0
+if [ "$YES" = false ]; then
+  [ -t 0 ] && [ -t 1 ] || fail "Non-interactive uninstall requires --yes"
+  read -r -p 'Remove this proven Arashi direct installation? [y/N] ' answer
+  case "$answer" in y|Y|yes|YES) ;; *) printf '%s\n' 'Uninstall declined.'; exit 0 ;; esac
+fi
+
+preflight
+for index in "${!SHELL_PATHS[@]}"; do
+  [ "$(sha256_file "${SHELL_PATHS[$index]}")" = "${SHELL_DIGESTS[$index]}" ] || fail "shell target changed after preflight"
+  copy_without_range "${SHELL_PATHS[$index]}" "${SHELL_STARTS[$index]}" "${SHELL_ENDS[$index]}"
+done
+if [ "$PROFILE_ACTION" = "remove" ]; then
+  read -r current_count current_offset < <(file_occurrences "$PROFILE_PATH" "$INSERTED_FILE")
+  [ "$current_count" -eq 1 ] && [ "$current_offset" -eq "$PROFILE_OFFSET" ] || fail "PATH profile changed after preflight"
+  copy_without_range "$PROFILE_PATH" "$PROFILE_OFFSET" "$((PROFILE_OFFSET + $(wc -c < "$INSERTED_FILE" | tr -d '[:space:]')))"
+fi
+for index in 0 1 2 3; do [ "${FILE_ACTIONS[$index]}" != "remove" ] || rm -f -- "$INSTALL_DIR/${EXPECTED_NAMES[$index]}"; done
+rm -f -- "$MANIFEST_PATH"