@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/adr/ADR-011-nushell-tier3-keep.md

@@ -1,144 +0,0 @@
----
-render_with_liquid: false
----
-
-# ADR-011: Keep Nushell as Tier-3 Reference with Minimum-Viable Caching
-
-## Status
-
-Accepted
-
-## Date
-
-2026-05-13
-
-## Context
-
-ADR-007 (Multi-Shell Parity Strategy) classified the three supported
-shells:
-
-| Tier | Shells | Definition |
-|---|---|---|
-| Tier 1 (Full) | zsh, bash | Native aliases, functions, lazy loading, `_cached_eval` |
-| Tier 2 (Bridged) | fish | Aliases + functions via bridge, `_cached_eval` |
-| Tier 3 (Compatible) | nushell | Simple aliases only, functions via bash delegation |
-
-The 2026 audit (slice 3 of #880's deep-dive) flagged Nushell as a
-maintenance candidate:
-
-- < 5% feature parity with zsh.
-- No async / deferred-load support.
-- No equivalent of `_cached_eval` — meaning every Nushell start spawns
-  `starship init nu`, `mise activate nu`, `zoxide init nushell`,
-  `atuin init nu` as fresh subprocesses, costing 100–200 ms aggregated.
-- 5 config files (`config.nu.tmpl`, `env.nu.tmpl`, `aliases.nu`,
-  `completions.nu.tmpl`, `functions.nu.tmpl`) totalling ~270 lines —
-  enough to be meaningful, not enough to be self-sustaining.
-
-Three paths were proposed:
-
-1. **Keep as-is** — accept the gap, defer maintenance.
-2. **Reduce to a stub** — leave the config but stop investing.
-3. **Remove entirely** — delete all references.
-
-## Decision
-
-**Keep Nushell as Tier-3 with explicit limitations + a minimum-viable
-`_cached_eval` equivalent.**
-
-Specifically:
-
-- Ship `dot_config/nushell/cached_eval.nu` — a Nushell module that
-  ports the binary-mtime-based init caching pattern from zsh/fish.
-  It handles the four tools that matter most for shell start:
-  starship, mise, zoxide, atuin. See the Nushell-specific tradeoffs
-  in the "Consequences" section below.
-- Wire `env.nu.tmpl` to use the new module so subsequent shells skip
-  the subprocess spawns when binaries haven't moved.
-- Continue maintaining the existing `aliases.nu` (hand-curated simple
-  aliases — `l`, `ll`, `la`, etc.) but accept that the bash-bridge
-  approach for full alias parity isn't worth the complexity.
-- Update `README.md`'s shell list to call Nushell out as "best-effort
-  / Tier-3" so users have correct expectations.
-- Reject the "remove entirely" option for now (see Rationale below).
-
-## Rationale
-
-**Why not remove**: Nushell is shipped with the canonical `mise`
-toolchain in this repo (it's installable via `mise install nushell`)
-and is gaining adoption in the Rust + data-engineering communities
-that overlap with this distribution's audience. Removing it would
-break promises to a small-but-vocal segment of users. The maintenance
-cost of the current 270-line surface is low.
-
-**Why not reduce to a stub**: A stub config is worse than the current
-moderate config — users who type `nu` and get a featureless shell
-without any of the integrations the README promised would feel
-betrayed. Either we keep the shell working well enough to use, or we
-delete it.
-
-**Why the minimum-viable cache layer**: The biggest waste on every
-Nushell start was the four uncached subprocess spawns
-(`starship init nu` etc.). Adding mtime-based caching for those costs
-~50 lines of Nushell code and saves 100–200 ms per shell. That's the
-cheapest meaningful improvement; deeper investments (async hydration,
-plugin system, bash bridge for aliases) await an actual user request.
-
-## Consequences
-
-### Positive
-
-- Nushell starts substantially faster than before (TBD — needs
-  measurement on a host with all four tools installed). The
-  subprocess elimination saves ~50–80 ms per cached tool, per cold
-  shell after the cache is populated.
-- The mtime-invalidation pattern matches what zsh / fish do, so a
-  contributor familiar with one of the other shells can read the
-  Nushell code without learning a new mental model.
-- Explicit Tier-3 documentation avoids the "wait, this is supposed to
-  be at parity" surprise.
-
-### Negative
-
-- Nushell's parse-time evaluator means we can't wrap source calls in
-  the cache function — the caller has to `source <path>` directly.
-  Slightly more boilerplate than the zsh/fish APIs.
-- No malware-pattern screening in the cached output. The zsh / fish
-  implementations grep for `curl ... | sh`, `nc -e`, etc. before
-  sourcing; the Nushell version trusts its inputs. For the four tools
-  we ship (`starship`, `mise`, `zoxide`, `atuin`) this is acceptable
-  — they're official binaries pinned via `mise.toml`. Future tools
-  added to the cache must be similarly trusted.
-- No per-tool timing telemetry. The `EVALCACHE_TIMING` infrastructure
-  zsh has (#863) isn't ported. If Nushell perf becomes a sustained
-  user concern, this is the next layer to add.
-
-### Risks
-
-- Nushell's syntax evolves quickly between 0.x releases. The
-  `cached_eval.nu` module uses `path exists`, `ls | get -i modified`,
-  and `run-external` which have been stable since 0.86 (Q3 2024).
-  If a future Nushell release breaks the API, the module fails fast
-  (saving an empty cache file) rather than corrupting state.
-- Cache invalidation by mtime is fragile when the user installs a
-  tool via a non-mtime-respecting method (e.g. unpacking a tarball
-  with `--no-touch-mtimes`). The fallback is the user running
-  `dot prewarm` or deleting `~/.cache/nushell/*.nu`. Documented in
-  `docs/operations/PERFORMANCE.md`.
-
-## Alternatives Considered
-
-| Alternative | Why rejected |
-|---|---|
-| **Bash bridge for full alias parity** | Adds a `bash --norc --noprofile -c '...'` subprocess on every Nushell start (~30 ms). Defeats the perf gain from the cache layer. |
-| **Port `_cached_eval` 1:1 (malware screen + JSONL telemetry)** | The full zsh implementation is 100+ lines. The Nushell version covers the 80% case at 50 lines; the remaining 20% (advanced features) aren't load-bearing for Tier-3 status. |
-| **Delete Nushell entirely** | See "Why not remove" above. |
-| **Reduce to a stub** | See "Why not reduce to a stub" above. |
-
-## References
-
-- [`dot_config/nushell/cached_eval.nu`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/nushell/cached_eval.nu) — the new module.
-- [`dot_config/nushell/env.nu.tmpl`](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/nushell/env.nu.tmpl) — adopter.
-- ADR-007 (Multi-Shell Parity Strategy) — establishes the tier definitions.
-- ADR-002 (Shell Performance Optimization Strategy) — establishes `_cached_eval` semantics this module ports.
-- Issue [#880](https://github.com/sebastienrousseau/dotfiles/issues/880).

package/docs/adr/ADR-012-ai-fleet-local-proxy.md

@@ -1,79 +0,0 @@
----
-render_with_liquid: false
----
-
-# ADR-012: AI Fleet — Native Local Claude Proxy and Cockpit
-
-## Status
-
-Accepted
-
-## Date
-
-2026-06-27
-
-## Context
-
-The dotfiles manage a fleet of ~18 AI CLIs (claude, codex, copilot, goose,
-crush, amp, cursor-agent, grok, aider, opencode, agy, sgpt, ollama, autohand, vibe,
-qwen, zai, kiro-cli). Three problems had accumulated:
-
-1. **Incoherent command surface.** The fleet was driven by three incompatible
-   shapes — `dot ai <thing>`, `dot <tool>`, and `dot ai-<thing>` — with opaque
-   names (`cl`, `agy`, `dash`) and no stated reason to prefer `dot ai` over
-   running a tool directly.
-2. **No way to share one subscription.** Each tool needed its own provider/key.
-   Running the whole fleet on a single Claude subscription required a gateway,
-   but adding a third-party proxy (e.g. Meridian) meant a new runtime dependency
-   and 7k+ lines of engine to track.
-3. **No unified cockpit.** Status, cost, and launching were scattered.
-
-## Decision
-
-Build the capability **in-tree**, with no third-party runtime dependency, and
-present it behind a flat, verb-first surface modelled on the Claude CLI.
-
-- **Command surface.** A single `dot ai` namespace: bare opens a cockpit; a
-  bare prompt runs a one-shot on Claude; `<tool> "<prompt>"` targets a tool;
-  plus `chat`, `tools`, `install`, `serve`, `cost`, `login`, `doctor`, and a
-  `--style` steering flag. Old forms remain as deprecated aliases that print a
-  one-line hint. (`scripts/dot/commands/ai.sh`, `lib/dot/ai-commands.sh`.)
-- **Local gateway (`dot ai serve`).** `dot-ai-serve` is a stdlib-only Python
-  server that wraps the already-installed `claude` CLI in headless
-  `stream-json` mode and exposes the Anthropic (`/v1/messages`) and OpenAI
-  (`/v1/chat/completions`) protocols. The `claude` CLI owns auth, caching, and
-  rate limits — the server only translates wire formats. There is **no API key
-  anywhere**; the native Claude session is the credential.
-- **Routing safety.** The primary `claude` is **never** routed through the
-  gateway (it keeps its native session and claude.ai connectors). Routing is
-  applied per-invocation to non-Claude tools only and is never written into the
-  interactive shell environment.
-- **Cockpit (`dot-ai-tui`).** A Bubble Tea (Go) TUI built on `chezmoi apply`
-  via the mise-managed Go toolchain. It shells out to the `dot ai` verbs so
-  behaviour has one source of truth.
-
-## Consequences
-
-- **No new dependency for the headline feature.** The gateway leans on the
-  `claude` CLI the user already has; the cockpit is the only Go artefact and is
-  opt-in (built when `DOTFILES_AI` is set or already installed).
-- **Single source of truth.** The cockpit and completions both derive from the
-  `ai.sh` verb dispatch; a completion-parity test and the docs-coverage contract
-  keep them from drifting.
-- **Scope (v2).** The gateway does chat/completions for both protocols with
-  real token-by-token streaming, model routing/aliases, cost metering
-  (`/metrics`, `/v1/usage`), an optional daily budget cap, `/v1/models`, and
-  `/health`. Because it wraps the `claude` CLI (an agent, not the raw API),
-  tool-call passthrough and multimodal image input are handled gracefully but
-  not forwarded, and session resumption stays out of scope — documented in
-  [`docs/AI.md`](../AI.md).
-- **Naming churn.** Existing muscle memory (`dot cl`, `dot ai dashboard`,
-  `dot ai proxy`) is preserved via deprecated aliases, so nothing breaks while
-  users migrate.
-
-## References
-
-- [`docs/AI.md`](../AI.md) — user guide for the full surface
-- [ADR-004](ADR-004-cli-architecture.md) — the `dot` CLI wrapper this extends
-- [ADR-008](ADR-008-alias-system-architecture.md) — the alias system the
-  deprecated bridges live in

package/docs/adr/README.md

@@ -1,40 +0,0 @@
----
-render_with_liquid: false
----
-
-# Architecture Decision Records
-
-This directory contains Architecture Decision Records (ADRs) that document
-significant architectural decisions made in this project.
-
-## Index
-
-| ADR | Title | Status |
-|-----|-------|--------|
-| [ADR-001](ADR-001-ci-cd-pipeline.md) | Multi-stage CI/CD Pipeline Design | Accepted |
-| [ADR-002](ADR-002-shell-performance.md) | Shell Performance Optimization Strategy | Accepted |
-| [ADR-003](ADR-003-security-first.md) | Security-First Approach | Accepted |
-| [ADR-004](ADR-004-cli-architecture.md) | Chezmoi + Custom CLI Wrapper Architecture | Accepted |
-| [ADR-005](ADR-005-chezmoi-choice.md) | Chezmoi as Dotfiles Manager | Accepted |
-| [ADR-006](ADR-006-shell-selection.md) | Zsh as Default Shell | Accepted |
-| [ADR-007](ADR-007-multi-shell-parity.md) | Multi-Shell Parity Strategy | Accepted |
-| [ADR-008](ADR-008-alias-system-architecture.md) | Alias System Architecture | Accepted |
-| [ADR-009](ADR-009-wallpaper-driven-theming.md) | Wallpaper-Driven Theming Engine | Accepted |
-| [ADR-010](ADR-010-starship-transient-prompt.md) | Enable Starship Transient Prompt in Zsh and Fish | Accepted |
-| [ADR-011](ADR-011-nushell-tier3-keep.md) | Keep Nushell as Tier-3 Reference with Minimum-Viable Caching | Accepted |
-| [ADR-012](ADR-012-ai-fleet-local-proxy.md) | AI Fleet — Native Local Claude Proxy and Cockpit | Accepted |
-
-## ADR Format
-
-Each ADR follows this structure:
-
-- **Status**: Proposed, Accepted, Deprecated, Superseded
-- **Context**: The situation and forces at play
-- **Decision**: The change being made
-- **Consequences**: The resulting context after applying the decision
-
-## References
-
-- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
-- [ADR Tools](https://github.com/npryce/adr-tools)
-

package/docs/architecture/AI_COST_OPTIMIZATION.md

@@ -1,144 +0,0 @@
----
-title: "AI Cost Optimization"
-date: 2026-05-24
----
-
-# AI Cost Optimization
-
-This dotfiles framework ships an opinionated AI-cost layer designed to
-keep token spend predictable and low while still using the smartest
-model for orchestration. Two ideas drive it:
-
-1. **Delegate the grunt work.** Have the expensive smart model
-   orchestrate, and a cheap fast model do the file reads, edits, and
-   verification. The smart model sees one tool call and the final
-   `git diff` instead of every intermediate read.
-2. **Account every call.** Every invocation through `dot ai <provider>`
-   appends a JSONL entry so you can see spend across all providers in
-   one report, not just per-tool dashboards.
-
-## Quick reference
-
-```sh
-dot ai delegate "rename every UserService method that starts with get to fetch"
-dot ai cost                # all-time overview
-dot ai cost --since 7      # last 7 days
-dot ai cost --fails        # only failures + breakdown by failure type
-```
-
-Inside Claude Code: `/vibe`, `/vibe-report`, `/vibeon`, `/vibeoff`,
-`/vibestatus`, `/vibe-model-pick`, `/vibe-model-clear`.
-
-## The delegator pattern
-
-The pattern comes from [pcx-wave/vibe-skill][vibe-skill]. Mistral Vibe
-is the default delegate but the same wrapper accepts any model Vibe
-knows about (DeepSeek V4 Flash, Gemini Flash, etc.).
-
-[vibe-skill]: https://github.com/pcx-wave/vibe-skill
-
-Cost comparison (May 2026 list prices, blended 85 in / 15 out typical
-of coding tasks):
-
-| Task | Claude Sonnet 4.6 ($3 / $15) | Mistral Medium 3.5 ($1.50 / $7.50) | DeepSeek V4 Flash ($0.14 / $0.28) |
-|---|---|---|---|
-| 1-file tweak (800 tok) | ~$0.004 | ~$0.002 | ~$0.0001 |
-| 6-read task (4,800 tok) | ~$0.023 | ~$0.012 | ~$0.0008 |
-| Multi-file refactor (12,000 tok) | ~$0.058 | ~$0.029 | ~$0.002 |
-
-Real-world stats from 254 vibe-skill runs over 10 days (May 2026):
-
-| | Amount |
-|---|---|
-| Actually paid (Mistral Pro prorated + DeepSeek pay-as-you-go) | **$10.35** |
-| Same workload pay-as-you-go via Mistral API | $46.61 |
-| Same workload on Claude Sonnet 4.6 | $179.91 |
-| Saved vs Claude | **$169.56 (17.4× cheaper)** |
-
-Claude itself contributes ~500-1500 tokens per delegation as
-orchestration overhead. Even with that overhead the savings dominate
-for anything beyond a one-line edit.
-
-## Pieces deployed by this repo
-
-| Component | Source path | Deployed to | Role |
-|---|---|---|---|
-| `vibe` skill | `defaults/dot_claude/skills/vibe/` | `~/.claude/skills/vibe/` | Claude Code slash commands (`/vibe`, `/vibe-report`, etc.) |
-| Delegator binary | `defaults/dot_claude/skills/vibe/tools/executable_vibe-delegate` | `~/.claude/skills/vibe/tools/vibe-delegate` | Runs the cheap-model task in a pseudo-TTY, parses streaming JSON, syntax-checks changes, logs the run |
-| Reporter | `defaults/dot_claude/skills/vibe/tools/executable_delegate-report` | `~/.claude/skills/vibe/tools/delegate-report` | Reads the JSONL log, prints overview / by-model / by-project / failure tables |
-| CLI shim | `scripts/dot/commands/ai.sh` | `bin/dot ai delegate` / `bin/dot ai cost` | Same delegator + reporter, callable from the terminal without Claude Code |
-| Unified log hook | `_ai_log_run` in `ai.sh` | runs inside `run_ai_with_context` | Appends one JSONL line per `dot ai <provider>` invocation |
-| Log file | runtime-managed | `~/.local/share/delegate-runs.jsonl` | One line per run; `dot ai cost` reads it |
-
-## State files
-
-| File | Owner | Purpose |
-|---|---|---|
-| `~/.local/share/delegate-runs.jsonl` | runtime | One JSONL entry per AI invocation (vibe + every other provider) |
-| `~/.local/share/vibe-auto.flag` | `/vibeon` / `/vibeoff` | When present, Claude auto-delegates coding tasks to Vibe |
-| `~/.local/share/vibe-model.flag` | `/vibe-model-pick` | Override the Vibe model for the next runs; cleared by `/vibe-model-clear` |
-| `~/.vibe/config.toml` | user | Vibe's own provider / model configuration |
-
-## Reading the report
-
-```
-DELEGATE REPORT  2026-05-17 → 2026-05-24
-  Runs          : 27  (ok: 25, failed: 2, timeout: 0)
-  Success rate  :  92%
-  Avg duration  : 18.4s
-  Tokens total  : 4,231,082
-  Delegate cost : $1.4711
-  Claude equiv  : $14.8294
-  Saved         : $13.3583  (90% cheaper than Claude)
-```
-
-`Claude equiv` is what the same workload would have cost on Claude
-Sonnet 4.6 ($3 / $15 per M tokens, blended at the same in/out ratio).
-The savings line is the difference. Failure types are broken out per
-model so you can see which delegate is most reliable for your repo.
-
-## Provider coverage
-
-Every provider exposed via `dot ai <provider>` is logged best-effort.
-For providers that don't surface token counts in their CLI output, the
-report still tracks: timestamp, project, exit code, duration, prompt
-word count. Token / cost fields stay zero for those providers — the
-report tolerates the gap and aggregates by `model` regardless.
-
-Providers tracked today:
-
-| Provider | Binary | Logged | Tokens surfaced? |
-|---|---|---|---|
-| Claude Code | `claude` | yes | no (CLI doesn't expose) |
-| Codex | `codex` | yes | no |
-| Copilot CLI | `copilot` | yes | no |
-| Gemini CLI | `gemini` | yes | no |
-| Goose | `goose` | yes | no |
-| Kimi CLI | `kimi` | yes | no |
-| Aider | `aider` | yes | no |
-| OpenCode | `opencode` | yes | no |
-| Autohand | `autohand` | yes | no |
-| Mistral Vibe | `vibe` | yes | **yes** (via delegator) |
-| Qwen | `qwen` | yes | no |
-| ZAI | `zai` | yes | no |
-| Shell-GPT | `sgpt` | yes | no |
-| Ollama (local) | `ollama` | yes | n/a (no cost) |
-| Kiro CLI | `kiro-cli` | yes | no |
-
-## Future work
-
-Not implemented yet, ordered roughly by likely impact:
-
-1. **Provider-level budget guard.** `dot ai budget --set 50/month`
-   would warn at 80% and refuse new requests at 100% (overridable).
-   Needs per-provider cost estimation hooks beyond what each CLI
-   surfaces today.
-2. **Prompt response cache.** Many coding-helper queries are
-   deterministic ("syntax for X in Y"). A local cache keyed on prompt
-   hash + provider could short-circuit repeat queries.
-3. **Per-task-class model routing.** `dot ai delegate --class refactor`
-   would pick the cheapest model that meets the quality bar for the
-   task class. Today the user picks the model.
-4. **Rate-limit awareness.** Track API rate limits from response
-   headers, queue requests, surface a `dot ai cost --limits` view that
-   shows time-to-reset for every provider with an active limit.

package/docs/architecture/ARCHITECTURE.md

@@ -1,117 +0,0 @@
----
-render_with_liquid: false
----
-
-# Architecture
-
-Core architectural decisions and system design of the dotfiles shell distribution.
-
----
-
-## Philosophy
-
-- **XDG-First**: Configuration lives under `~/.config/` to keep the home directory clean.
-- **Multi-Shell**: First-class support for Zsh, Fish, and Nushell with a shared logic core.
-- **Fast Startup**: Heavy features are deferred or autoloaded to keep the first prompt under 50ms.
-- **Deterministic**: Nix Flakes provide bit-for-bit identical environments across machines.
-- **Non-Blocking**: Background daemons (Pueue) handle upgrades and builds without stalling the shell.
-
-## System Layout
-
-```text
-~/.dotfiles/
-├── dot_config/          # Managed application configurations (~/.config/)
-│   ├── zsh/             # Modular Zsh rc.d architecture
-│   ├── fish/            # Autoloading Fish configuration
-│   ├── nushell/         # Structured data shell config
-│   ├── shell/           # Shared logic (aliases, paths, functions)
-│   └── ...              # 50+ tool configurations (nvim, tmux, ghostty, etc.)
-├── dot_local/           # Local binaries and scripts (~/.local/bin/)
-├── .chezmoitemplates/   # Unified source for aliases, functions, and paths
-├── scripts/             # Internal libraries and diagnostics
-├── nix/                 # Nix Flake for deterministic toolchains
-├── lib/wasm-tools/      # Rust source for Wasm utilities
-└── install.sh           # Universal bootstrap script (zero dependencies)
-```
-
----
-
-## Shell Startup Strategies
-
-### Shared: `_cached_eval`
-
-Across Zsh, Fish, and Bash, an idempotent caching wrapper avoids redundant tool initialization (Starship, Zoxide, Atuin).
-
-1. **Intercept** — check if a cached version of the tool's `eval` output exists in `~/.cache/shell/`.
-2. **Validate** — compare the cache timestamp against the tool binary's mtime.
-3. **Bypass** — if valid, `source` the cached text directly, saving 20-50ms per tool.
-
-### Lazy-Hydration Model
-
-To reach a fluid first-prompt target (< 50ms), the shell uses a three-phase startup:
-
-1. **Phase 1 (Visual Paint)** — render the prompt immediately using static escape codes.
-2. **Phase 2 (Async Hydration)** — dispatch tool initializations (mise, atuin, etc.) to background workers.
-3. **Phase 3 (On-Demand Activation)** — environment hydration occurs on first user interaction or after 500ms of idle time.
-
----
-
-## Artifact Mode
-
-A minimal environment triggered by `DOTFILES_ARTIFACT_MODE=1`.
-
-- **Minimalist UI** — strips prompt complexity, leaving only a green `->`.
-- **Intelligence Surface** — an async Bento-style dashboard rendered via `bento.sh` that provides environment context (Node version, cloud status, Git health) without blocking the main thread.
-- **Redraw Signaling** — uses `SIGWINCH` to return control after background hydration completes.
-
----
-
-## Ultra-Fast Mode
-
-Set `DOTFILES_ULTRA_FAST=1` to skip all non-essential initialization. Only core paths, aliases, and the prompt are loaded. Useful for:
-
-- CI/CD pipelines where full shell setup is unnecessary
-- Rapid scripting sessions where startup latency matters
-- Benchmarking baseline shell performance
-
----
-
-## Debug and Trace Modes
-
-### DOTFILES_DEBUG=1
-
-Enables verbose diagnostic output during shell startup. Prints which files are sourced and their load times.
-
-### DOTFILES_TRACE=1
-
-Enables `set -x` tracing for the entire shell startup sequence. Output is written to `~/.local/state/dotfiles/debug.log` for post-mortem analysis.
-
----
-
-## Function Groups (groups.json)
-
-Functions are organized into groups defined in `.chezmoitemplates/functions/groups.json`:
-
-| Group | Functions | Description |
-|-------|-----------|-------------|
-| `api` | apihealth, apilatency, apiload | API testing utilities |
-| `curl` | curlheader, curlstatus, curltime, httpdebug | HTTP debugging |
-| `text` | encode64, kebabcase, lowercase, titlecase, ... | Text transformation |
-| `system` | environment, freespace, hostinfo, myproc, sysinfo | System introspection |
-| `files` | backup, extract, hexdump, hiddenfiles, size, zipf | File operations |
-| `interactive` | banner, emoji, matrix, rainbow, stopwatch | Terminal fun |
-| `nav` | cdls, goto, ql | Navigation shortcuts |
-| `security` | genpass, keygen, mount_read_only | Security utilities |
-| `misc` | dothelp, view-source, prependpath, caffeine | Miscellaneous |
-
-Groups are lazy-loaded: stub functions are defined at startup, and the real implementation is loaded on first invocation. This keeps startup fast while providing 52+ functions on demand.
-
-The `groups.json` schema maps group names to arrays of relative paths (including subdirectory):
-
-```json
-{
-  "group_name": ["group_name/function1.sh", "group_name/function2.sh"]
-}
-```
-
-Each `.sh` file lives in a subdirectory matching its group and defines a single function with the same name as the file (minus `.sh` extension).

package/docs/architecture/INTEROP.md

@@ -1,44 +0,0 @@
----
-render_with_liquid: false
----
-
-# Cross-Platform Interoperability
-
-How dotfiles commands and shims map across macOS, Linux, and WSL2.
-
-## Command Mapping
-
-| Alias / Command | macOS | Linux (Debian/Arch) | WSL2 (Windows Host) |
-| :--- | :--- | :--- | :--- |
-| `cb` (Clipboard) | `pbcopy` / `pbpaste` | `xclip` / `wl-copy` | `clip.exe` / `powershell.exe` |
-| `open` | `open` | `xdg-open` | `wslview` / `explorer.exe` |
-| `notify` | `osascript` (AppleScript) | `notify-send` / `gum log` | `powershell.exe` (Toast) / `gum` |
-| `win` (Paths) | N/A | N/A | `wslpath` |
-| `browser` | `open` | `xdg-open` | `powershell.exe Start-Process` |
-
-## Infrastructure Parity
-
-| Feature | macOS | Linux | WSL2 |
-| :--- | :--- | :--- | :--- |
-| **Package Manager** | Homebrew (`brew`) | `apt` / `pacman` / `nix` | `apt` + Windows binaries |
-| **Shell Startup** | Async lazy-hydration | Async lazy-hydration | Async (optimized for IO) |
-| **Environment** | native plist / launchctl | systemd / dbus | systemd (if enabled) / init |
-| **Hardware** | Secure Enclave | TPM 2.0 / LUKS | Windows Hello bridge |
-
-## Troubleshooting
-
-### WSL2 IO Latency
-
-Keep projects in the Linux filesystem (`~/...`), not under `/mnt/c/`.
-
-### WSL2 Windows Binary Path
-
-If you've disabled WSL path sharing, make sure Windows-side binaries like `clip.exe` and `explorer.exe` are still reachable in `$PATH`.
-
-### macOS Permissions
-
-Grant your terminal "Full Disk Access" in System Settings so dotfiles can manage all configurations.
-
-### Linux GUI Fallbacks
-
-In headless environments, GUI commands like `cb` and `open` fall back to `gum log` or terminal bell instead of hanging.