mixdog 0.7.11 → 0.7.13

package/README.md

@@ -2,7 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  [![Runtime: bun](https://img.shields.io/badge/runtime-bun-black.svg)](https://bun.sh)
- ![Version: 0.7.1](https://img.shields.io/badge/version-0.7.1-blue.svg)
+ [![npm](https://img.shields.io/npm/v/mixdog.svg)](https://www.npmjs.com/package/mixdog)
 
 All-in-one agent plugin for the Claude Code CLI — autonomous sub-agents,
 continuous memory, multi-provider routing, and syntax-aware code tools,
@@ -13,42 +13,10 @@ behind a single MCP server. Zero telemetry; all state under
 - **Continuous memory** — conversations, decisions, and work persist across sessions; a prebuilt Postgres + pgvector runtime is auto-downloaded and supervised, with no database to install
 - **Lower cost** — session-spanning prompt cache with per-provider / per-role token tracking
 - **Natural-language search** — web search and URL scraping in one tool
-- **Syntax-aware code tools** — AST-based symbol / reference / caller lookup, keyword→symbol search via `code_graph` `search`, and precise edits
+- **Syntax-aware code tools** — AST-based symbol / reference / caller lookup, keyword→symbol search via `code_graph`, and precise edits
 - **Channels & automation** — Discord front-end, cron schedules, and inbound webhooks
 
-## Contents
-
-- [Why mixdog](#why-mixdog)
-- [Install](#install) · [Quick start](#quick-start)
-- [Modules & tools](#modules--tools)
-- [Skills & commands](#skills--commands)
-- [Providers](#providers)
-- [Channels & automation](#channels--automation)
-- [Configuration](#configuration)
-- [Architecture & hooks](#architecture--hooks)
-- [Safety](#safety) · [Windows support](#windows-support)
-- [Contributing](#contributing) · [License](#license)
-
-## Why mixdog
-
-Claude Code is powerful, but out of the box it forgets everything between
-sessions, treats every request as a fresh context, and has no built-in way
-to delegate to cheaper or specialised models. Cost runs high, answers
-drift, and long-lived projects lose the thread.
-
-mixdog replaces that pattern with a single MCP server that bundles four
-cooperating modules — **agent**, **memory**, **search**, and **channels** —
-so your Claude Code session gains persistent memory, multi-provider
-sub-agents, web lookup, and an optional Discord front-end,
-all behind one install.
-
-The goal is deployment-grade: plain ESM, zero build step for runtime
-code, documented local state, and every configuration surface readable
-as JSON you can diff.
-
-## Install
-
-**From npm (terminal):**
+## Quickstart
 
 ```bash
 npm i -g mixdog                          # install the `mixdog` command
@@ -59,91 +27,88 @@ mixdog --dangerously-skip-permissions    # launch with full permissions
 `npm i -g mixdog` adds the `mixdog` command to your PATH; `mixdog` then launches
 Claude Code with mixdog pre-loaded. The first `mixdog` run walks you through
 setup (logins + plugin registration) and launches the moment it finishes — no
-second run needed. Any extra Claude flags (e.g. `--dangerously-skip-permissions`)
-pass straight through; the `claude` CLI must be on your PATH. (If `mixdog` isn't
-recognized right after install, open a new terminal and run it again.)
+second run needed. Any extra Claude flags pass straight through; the `claude`
+CLI must be on your PATH. (If `mixdog` isn't recognized right after install,
+open a new terminal and run it again.)
 
-Other entry points: `npx mixdog` (one-off, no global install — leaves no
-persistent `mixdog` command); `mixdog install` / `--dry-run` / `--demo` (run
-setup only, or preview the steps without writing).
+Anthropic OAuth (the Claude Code login) is the default provider, so
+`bridge` / `recall` / `explore` / `memory` work immediately — no API keys
+required. Configure providers, presets, and role bindings in the in-browser
+config UI — open it any time with `/mixdog:config`. (The config server is
+pre-warmed in the background each session, so the window opens instantly.)
 
-**Inside Claude Code (slash commands):**
+**Or install from inside Claude Code:**
 
 ```
 /plugin marketplace add trib-plugin/mixdog
 /plugin install mixdog@trib-plugin
 ```
 
-Claude Code will register the repository as a marketplace, clone it,
-run `bun install --frozen-lockfile`, and register the MCP server declared in
-`.mcp.json`. bun is auto-installed on first launch if missing (node + npm
-provided by Claude Code). To skip the first-boot install step, install bun
-manually: https://bun.sh
-
-First-launch flow: `scripts/bootstrap.mjs` (node, no deps) locates bun via
-system PATH, falls back to plugin-local `node_modules/.bin/bun`, and finally
-runs `npm install --no-save bun` if neither is present. node + npm are
-provided by Claude Code, so the npm fallback works on a clean machine.
-
-## Quick start
-
-1. **Install.**
-   ```
-   /plugin marketplace add trib-plugin/mixdog
-   /plugin install mixdog@trib-plugin
-   ```
-
-2. **Restart Claude Code.** The node bootstrap layer locates or installs
-   bun, then bun installs runtime dependencies into a shared data
-   directory and seeds working defaults under
-   `~/.claude/plugins/data/mixdog-trib-plugin/`. On first boot the memory
-   runtime (a prebuilt Postgres + pgvector build) is also downloaded and
-   checksum-verified once, then reused on every later boot. First boot
-   takes 10-15 extra seconds if bun was not pre-installed, plus the
-   one-time runtime download; subsequent boots are unaffected.
-
-   First boot also reconfigures two Claude Code surfaces, with the
-   originals preserved for restore: the built-in `autoMemoryEnabled` and
-   `awaySummaryEnabled` settings are turned off in `~/.claude/settings.json`
-   (mixdog's continuous memory and recap replace both), and rules
-   persistence takes over `~/.claude/CLAUDE.md` (see **Configuration**).
-   Prior values and the original file are snapshotted under
-   `~/.claude/backups/mixdog-user-data/install-restore/`, and
-   `node scripts/uninstall.mjs` restores them (`CLAUDE.md` + the two
-   settings keys; see UNINSTALL.md for the full manual teardown).
-
-3. **That's it.** Anthropic OAuth (the Claude Code login) is the default
-   provider, so `bridge` / `recall` / `explore` / `memory` work immediately —
-   no API keys required.
-
-4. **Config UI.** On first launch the config UI opens automatically at
-   `http://localhost:3458` for providers, presets, and role bindings.
-   You can re-open it any time with `/mixdog:config`.
-
-5. **Optional external web search.** Add a Firecrawl / Tavily / Exa key in
-   the config UI (or edit the `search` section of `mixdog-config.json`
-   directly in the data directory). xAI search uses the Agent xAI key (set
-   in the config UI / keychain), not a separate search key.
-
-6. **Optional channels.** To enable Discord / voice / schedule / webhook
-   channels, restart Claude Code with the development channel flag
-   (see **Channels & automation** below), then set the Discord bot token and
-   channel IDs in the config UI — the token is stored in the OS keychain,
-   not a file — and enable channels.
+<details>
+<summary>Other entry points & what first boot does</summary>
+
+```bash
+npx mixdog                # one-off run without a global install (leaves no persistent `mixdog` command)
+mixdog install            # (re)run setup only: detect Claude CLI, register plugin, OAuth login, prewarm deps
+mixdog install --dry-run  # preview the steps (no writes, prompts, or installs)
+mixdog install --demo     # preview in an isolated sandbox (no writes to your real config)
+```
+
+Claude Code clones the repo as a marketplace, runs `bun install --frozen-lockfile`,
+and registers the MCP server in `.mcp.json`. On first boot, `scripts/bootstrap.mjs`
+locates bun (system PATH → plugin-local → `npm install --no-save bun` fallback),
+installs runtime deps into the shared data dir, and seeds defaults under
+`~/.claude/plugins/data/mixdog-trib-plugin/`. The memory runtime (a prebuilt
+Postgres + pgvector build) is downloaded and checksum-verified once, then reused.
+First boot takes 10–15 extra seconds if bun wasn't pre-installed, plus the
+one-time runtime download; later boots are unaffected.
+
+First boot also reconfigures two Claude Code surfaces, originals preserved for
+restore: the built-in `autoMemoryEnabled` and `awaySummaryEnabled` settings are
+turned off in `~/.claude/settings.json` (mixdog's continuous memory and recap
+replace both), and rules persistence takes over `~/.claude/CLAUDE.md` (see
+Configuration). Prior values are snapshotted under
+`~/.claude/backups/mixdog-user-data/install-restore/`, and
+`node scripts/uninstall.mjs` restores them (see UNINSTALL.md for full teardown).
+
+To enable Discord / voice / schedule / webhook channels, launch with the
+development channel flag (see Channels & automation) and set the Discord token
+and channel IDs in the config UI.
+
+</details>
+
+## Why mixdog
+
+Claude Code is powerful, but out of the box it forgets everything between
+sessions, treats every request as a fresh context, and has no built-in way
+to delegate to cheaper or specialised models. Cost runs high, answers drift,
+and long-lived projects lose the thread.
+
+mixdog replaces that pattern with a single MCP server that bundles four
+cooperating modules — **agent**, **memory**, **search**, and **channels** — so
+your Claude Code session gains persistent memory, multi-provider sub-agents,
+web lookup, and an optional Discord front-end, all behind one install. The goal
+is deployment-grade: plain ESM, zero build step for runtime code, documented
+local state, and every configuration surface readable as JSON you can diff.
 
 ## Modules & tools
 
-mixdog is one MCP server composing four user-facing modules. Code and
-filesystem tools are shared across all of them.
+One MCP server composes four user-facing modules, plus code and filesystem
+tools shared across all of them:
+
+- **agent** — a session orchestrator with a single `bridge` entry point: delegated sub-agent sessions, role → preset bindings, multi-provider routing, and session-spanning cache / cost handling.
+- **memory** — native Postgres + `pgvector` + `pg_trgm` hybrid store; a prebuilt runtime is fetched and supervised automatically. A three-cycle pipeline scores, dedupes, and promotes durable knowledge to core memory.
+- **search** — one natural-language entry point routing across providers, scraping URLs through a Readability + Puppeteer pipeline, formatted for model consumption.
+- **channels** — Discord, cron schedules, inbound webhooks, voice STT, and a heartbeat status surface (requires the channel flag).
+
+<details>
+<summary>Full tool reference</summary>
 
 ### agent
 
-A session orchestrator with a single `bridge` entry point: delegated
-sub-agent sessions, role → preset bindings (`user-workflow.json`),
-multi-provider routing, and session-spanning cache / cost handling.
-Sessions run as long-lived loops with trim / compress, a stream
-watchdog, and background job tracking. A `<final-answer>` tag protocol
-separates a worker's final reply from its internal deliberation.
+Sessions run as long-lived loops with trim / compress, a stream watchdog, and
+background job tracking. A `<final-answer>` tag protocol separates a worker's
+final reply from its internal deliberation.
 
 | Tool | Purpose |
 | --- | --- |
@@ -154,17 +119,12 @@ separates a worker's final reply from its internal deliberation.
 
 ### memory
 
-Native PostgreSQL with `pgvector` and `pg_trgm` backs a hybrid FTS +
-vector store; a prebuilt runtime is fetched from the release manifest on
-first boot, checksum-verified, and supervised automatically — there is no
-separate database to install or configure. Every conversation chunk is
-scored, deduped, and — if durable — promoted to core memory. A three-cycle
-pipeline keeps it compact: cycle 1 extracts and scores chunks, cycle 2 is a
-unified curator gate that holds the active set to a cap (~100 entries), and
-cycle 3 reviews user-curated core memory. Keep/discard decisions follow a
-3-layer framework — L1 relationship/communication, L2 behavior rules, L3
-current project map — so only durable standing knowledge survives. SessionStart
-injects durable context plus a recent recap.
+Every conversation chunk is scored, deduped, and — if durable — promoted to core
+memory. Cycle 1 extracts and scores chunks, cycle 2 is a unified curator gate
+that holds the active set to a cap (~100 entries), and cycle 3 reviews
+user-curated core memory. Keep/discard decisions follow a 3-layer framework
+(L1 relationship/communication, L2 behavior rules, L3 current project map).
+SessionStart injects durable context plus a recent recap.
 
 | Tool | Purpose |
 | --- | --- |
@@ -173,11 +133,6 @@ injects durable context plus a recent recap.
 
 ### search
 
-One natural-language entry point routes across multiple search
-providers and scrapes URLs through a Readability + Puppeteer pipeline.
-Results are cached and formatted for model
-consumption, not browser consumption.
-
 | Tool | Purpose |
 | --- | --- |
 | `search` | Web SERP search (string or array of queries) |
@@ -185,10 +140,8 @@ consumption, not browser consumption.
 
 ### channels
 
-Discord, cron schedules, inbound webhooks, voice STT, and a heartbeat
-status surface. Inbound chat / webhook events drive a turn, schedules
-fire on cadence, and the status feed keeps long-running sessions
-observable. (Requires the channel flag — see **Channels & automation**.)
+Inbound chat / webhook events drive a turn, schedules fire on cadence, and the
+status feed keeps long-running sessions observable.
 
 | Tool | Purpose |
 | --- | --- |
@@ -199,16 +152,13 @@ observable. (Requires the channel flag — see **Channels & automation**.)
 ### Code & filesystem tools
 
 Shared across all modules — AST navigation (`@ast-grep/cli`) plus
-content-addressed edits with a session read-dedup cache, so navigation
-stays syntax-correct without dumping whole files into context. Tool
-results are compressed before they hit the model (head/tail truncation,
-ANSI / repeated-line dedup, file-grouped grep output). The `Module` column
-matches the `module` tag in `tools.json`. `apply_patch` accepts unified and
-V4A hunks with order-independent matching, so multi-hunk patches apply
-regardless of the order the hunks are listed. `read` decodes UTF-8 and
-UTF-16 (LE/BE, with or without BOM). `bash` auto-backgrounds a foreground
-command that outlives 30s into a tracked job and streams live progress over
-MCP, so long commands never block the session.
+content-addressed edits with a session read-dedup cache, so navigation stays
+syntax-correct without dumping whole files into context. Tool results are
+compressed before they hit the model (head/tail truncation, ANSI / repeated-line
+dedup, file-grouped grep output). `apply_patch` accepts unified and V4A hunks
+with order-independent matching. `read` decodes UTF-8 and UTF-16 (LE/BE, with or
+without BOM). `bash` auto-backgrounds a foreground command that outlives 30s into
+a tracked job and streams live progress over MCP.
 
 | Tool | Module | Purpose |
 | --- | --- | --- |
@@ -221,9 +171,19 @@ MCP, so long commands never block the session.
 | `inject_input` | `host_input` | Inject input into the host Claude Code session (Windows only) |
 | `cwd` | `cwd` | Get / set / list the session working directory for relative-path resolution |
 
+</details>
+
 ## Skills & commands
 
-**Skills** (auto-triggered by intent; Claude Code also surfaces them by name):
+**Skills** are auto-triggered by intent (Claude Code also surfaces them by name):
+`setup` (onboarding & config), `schedule-add`, `webhook-add`, `retro-skill-proposer`.
+
+**Commands:** `/mixdog:setup` (prerequisites + config UI), `/mixdog:doctor`
+(health diagnostics), `/mixdog:config` (open the in-browser settings UI — **the
+primary way to change any configuration**).
+
+<details>
+<summary>Details</summary>
 
 | Skill | Use |
 | --- | --- |
@@ -232,30 +192,42 @@ MCP, so long commands never block the session.
 | `setup` | Onboarding and config editing (channels, presets, roles, memory) |
 | `retro-skill-proposer` | Propose a reusable skill draft after a session |
 
-**Commands** (`/mixdog:<name>`):
-
 | Command | Purpose |
 | --- | --- |
 | `/mixdog:setup` | Check prerequisites and open the config UI |
 | `/mixdog:doctor` | Health diagnostics (versions, runtime, cache, deps, log count/size, Postgres `pgdata` size, hook-pipe reachability) |
-| `/mixdog:config` | Open the in-browser config page directly |
+| `/mixdog:config` | Open the in-browser settings UI — the primary way to change configuration (providers, presets, roles, channels, memory) |
 
 **Hidden maintenance roles** (under `agents/`, not user-invoked):
 `scheduler-task`, `webhook-handler`, `maintenance`, `memory-classification`.
-Any public roles (worker, reviewer, debugger, etc.) are defined locally in
+Public roles (worker, reviewer, debugger, etc.) are defined locally in
 `user-workflow.json`, not bundled.
 
+</details>
+
 ## Providers
 
-Anthropic (direct or OAuth), OpenAI (direct or OAuth), Google Gemini,
-and any OpenAI-compatible endpoint (LM Studio, Ollama, vLLM, LiteLLM)
-are first-class providers. Switch a role to a cheaper or faster model by
-editing one line in `user-workflow.json`. A shared-prefix cache strategy
-propagates Anthropic and OpenAI prompt caching across every role in a
-session, and token usage is logged per provider and per role so you can
-see where cost lands before the bill arrives.
+Anthropic (direct or OAuth), OpenAI (direct or OAuth), Google Gemini, and any
+OpenAI-compatible endpoint (LM Studio, Ollama, vLLM, LiteLLM) are first-class
+providers. Switch a role to a cheaper or faster model by editing one line in
+`user-workflow.json`. A shared-prefix cache strategy propagates Anthropic and
+OpenAI prompt caching across every role in a session, and token usage is logged
+per provider and per role so you can see where cost lands before the bill arrives.
+
+## Safety
+
+- **Zero telemetry.** No outbound calls beyond the providers you configure and the search endpoints you opt into.
+- **Protected paths.** Destructive shell patterns (recursive root deletes, force pushes, disk formatting) are hard-blocked, unconditionally, with no override flag.
+- **Approval gates & tool scope.** Out-of-workspace writes by sub-agents require confirmation; system paths are hard-denied; each role has an explicit tool preset (`readonly` / `full` / custom).
+- **Untrusted inbound data.** Webhook payloads are fenced as untrusted data, never executed as instructions.
+- **Fail-open hooks.** Permission hooks are a guard layer, not a sandbox: if the daemon or hook pipe is down, decisions default to allow (`/mixdog:doctor` warns explicitly).
+
+Full local-state, secret, and network model: [SECURITY.md](SECURITY.md) and
+[DATA-FLOW.md](DATA-FLOW.md). To restore the pre-install `CLAUDE.md` and Claude
+Code settings, run `node scripts/uninstall.mjs` ([UNINSTALL.md](UNINSTALL.md)).
 
-## Channels & automation
+<details>
+<summary>Channels & automation</summary>
 
 Channel-driven features require launching Claude Code with the channel flag.
 mixdog is not in Anthropic's curated channel allowlist, so `--channels` is
@@ -267,139 +239,111 @@ claude --dangerously-load-development-channels plugin:mixdog@trib-plugin
 
 This activates the Discord backend, voice STT, schedule runner, and webhook
 receiver. Without the flag the plugin still works for direct tools (`recall`,
-`memory`, `bridge`, `explore`, `search`, `bash`, etc.) — channel inbound
-events are silently disabled.
+`memory`, `bridge`, `explore`, `search`, `bash`, etc.) — channel inbound events
+are silently disabled.
 
 **Schedules and webhooks** each live as a per-entry directory under the data
 directory (`schedules/<name>/`, `webhooks/<name>/`), holding `config.json`
-(cron `time` / `secret` / optional `channel` / `model`) and `instructions.md`
-(what to do on fire / delivery). Routing is decided purely by **channel
-presence**:
+(cron `time` / `secret` / optional `channel` / `model`) and `instructions.md`.
+Routing is decided purely by **channel presence**:
 
-- **No `channel`** → the delivery is **injected into the current (Lead)
-  session**, which handles it with full context.
-- **`channel` set** → it is **dispatched directly to that Discord channel** by
-  a standalone handler (which then requires a `model` preset).
+- **No `channel`** → injected into the current (Lead) session, which handles it with full context.
+- **`channel` set** → dispatched directly to that Discord channel by a standalone handler (which then requires a `model` preset).
 
 When a handler has nothing to report (no code change, non-default branch,
-docs-only, dedup), it emits `[meta:silent]` as the first line — the
-notification is then dropped entirely (no session turn, no channel post).
+docs-only, dedup), it emits `[meta:silent]` as the first line — the notification
+is dropped entirely (no session turn, no channel post).
 
-Outbound notifications respect a shared quiet-hours window (timezone-aware,
-with weekend and holiday handling); each channel system can opt out of
-quieting via its own `respectQuiet` flag in the config UI's DND tab.
+Outbound notifications respect a shared quiet-hours window (timezone-aware, with
+weekend and holiday handling); each channel can opt out via its `respectQuiet`
+flag in the config UI's DND tab.
 
 To switch to plain `--channels`, either submit mixdog to
 `claude-plugins-official` (Anthropic curates the allowlist), or add
 `{marketplace: "trib-plugin", plugin: "mixdog"}` to your organization's
 `allowedChannelPlugins` managed setting (Team / Enterprise).
 
-## Configuration
+</details>
+
+<details>
+<summary>Configuration</summary>
 
 All user-editable config lives in the plugin data directory
-(`~/.claude/plugins/data/mixdog-trib-plugin/`), NOT in the repository.
-The easiest way to edit it is `/mixdog:config` — this opens the in-browser
-UI. Editing the JSON files directly is also fully supported.
-
-New installs default to `CLAUDE.md` mode: mixdog persists its rules block
-into `~/.claude/CLAUDE.md`. On the first takeover of an existing file, the
-original is backed up once to
-`~/.claude/backups/mixdog-user-data/install-restore/claude-md-original.md`
-and the file is replaced with the marker-delimited managed block; if that
-backup cannot be written, mixdog appends the block instead and leaves your
-content in place. If you prefer ephemeral injection, switch to SessionStart
-hook mode in the config UI — that mode never writes to `~/.claude/CLAUDE.md`.
+(`~/.claude/plugins/data/mixdog-trib-plugin/`), NOT in the repository. The
+easiest way to edit it is `/mixdog:config` (the in-browser UI); editing the JSON
+files directly is also fully supported.
+
+New installs default to `CLAUDE.md` mode: mixdog persists its rules block into
+`~/.claude/CLAUDE.md`. On the first takeover of an existing file, the original is
+backed up once to
+`~/.claude/backups/mixdog-user-data/install-restore/claude-md-original.md` and
+the file is replaced with the marker-delimited managed block; if that backup
+can't be written, mixdog appends the block instead and leaves your content in
+place. Prefer ephemeral injection? Switch to SessionStart hook mode in the config
+UI — that mode never writes to `~/.claude/CLAUDE.md`.
 
 First install also disables Claude Code's built-in `autoMemoryEnabled` and
-`awaySummaryEnabled` in `~/.claude/settings.json` — mixdog's memory and
-recap replace both — after snapshotting the prior values to
+`awaySummaryEnabled` in `~/.claude/settings.json` (mixdog's memory and recap
+replace both) after snapshotting the prior values to
 `install-restore/claude-settings-original.json`. Run
-`node scripts/uninstall.mjs` to restore the original file and settings.
-
-The following files are managed in the data directory:
+`node scripts/uninstall.mjs` to restore.
 
 | File | How it gets there | Purpose |
 | --- | --- | --- |
-| `mixdog-config.json` | Auto-seeded on first boot | All user-configurable settings under named sections (`channels`, `memory`, `agent`, `search`, plus UI-managed extras). See `src/shared/seed.mjs` for the default structure. |
+| `mixdog-config.json` | Auto-seeded on first boot | All user-configurable settings under named sections (`channels`, `memory`, `agent`, `search`, plus UI-managed extras). See `src/shared/seed.mjs`. |
 | `user-workflow.json` | Seeded by the setup server when missing | Role → preset bindings for delegated agents |
-| `user-workflow.md` | Auto-generated on first launch | Human-readable workflow description derived from `user-workflow.json`; used by the Lead as a role reference |
+| `user-workflow.md` | Auto-generated on first launch | Human-readable workflow description derived from `user-workflow.json` |
 | `schedules/<name>/` | Created via config UI or `schedule-add` | Per-schedule `config.json` + `instructions.md` |
 | `webhooks/<name>/` | Created via config UI or `webhook-add` | Per-webhook `config.json` + `instructions.md` |
 
-Seed defaults and templates live under `defaults/`
-(`mixdog-config.template.json`, `user-workflow.json`) — useful as a
-reference or for diffing after manual edits.
-
-**Discord setup (optional).** Set the Discord bot token in the config UI
-(`/mixdog:config`) — it is stored in the OS keychain, not a file — and add
-your channel IDs there, then enable channels.
-
-## Architecture & hooks
-
-The MCP server starts via `scripts/bootstrap.mjs → scripts/run-mcp.mjs`
-(stdio supervisor) `→ server.mjs` (thin client or shared daemon) `→
-server-main.mjs`. Hooks are declared in `hooks/hooks.json` and routed through
-a native shim + CJS files. SessionStart is split into three parts — `rules`
-(workflow / rules injection + first-boot setup), `core` (durable memory
-context), and `recap` (recent-session recap); PreToolUse / PostToolUse enforce
-permission gates, sandbox checks, and status updates. Session state is
-journalled every turn, so a mid-session crash resumes cleanly on next boot.
-SessionStart also installs a version-independent status line: a stable launcher
-is copied into the data directory and registered in `~/.claude/settings.json`
-(tagged `"source": "mixdog-auto"`), so the status line survives plugin version
-bumps and self-heals without a restart. A genuine user-configured `statusLine`
-is left untouched.
+Seed defaults and templates live under `defaults/`. **Discord setup (optional):**
+set the bot token in the config UI (stored in the OS keychain, not a file) and
+add channel IDs there, then enable channels.
+
+</details>
+
+<details>
+<summary>Architecture & hooks</summary>
+
+The MCP server starts via `scripts/bootstrap.mjs → scripts/run-mcp.mjs` (stdio
+supervisor) `→ server.mjs` (thin client or shared daemon) `→ server-main.mjs`.
+Hooks are declared in `hooks/hooks.json` and routed through a native shim + CJS
+files. SessionStart is split into three parts — `rules` (workflow / rules
+injection + first-boot setup), `core` (durable memory context), and `recap`
+(recent-session recap); PreToolUse / PostToolUse enforce permission gates,
+sandbox checks, and status updates. Session state is journalled every turn, so a
+mid-session crash resumes cleanly on next boot. SessionStart also installs a
+version-independent status line (a stable launcher tagged
+`"source": "mixdog-auto"` in `~/.claude/settings.json`) that survives version
+bumps and self-heals; a genuine user-configured `statusLine` is left untouched.
+
 See [ARCHITECTURE.md](ARCHITECTURE.md) and [DATA-FLOW.md](DATA-FLOW.md).
 
-## Safety
+</details>
+
+<details>
+<summary>Windows support</summary>
+
+mixdog is developed on Windows and tested on Windows + Linux. All scripts use
+forward slashes or `path.join`, line endings are normalised to LF via
+`.gitattributes` (except `.cmd` / `.bat` / `.ps1`, which stay CRLF), and Node
+child-process calls resolve binaries through `process.platform`-aware shims.
 
-- **Protected paths.** The MCP server hard-blocks destructive shell
-  patterns (recursive root deletes, force pushes, disk formatting) —
-  these are unconditional, with no override flag.
-- **Approval gates.** Out-of-workspace filesystem writes by sub-agents
-  require a confirmation prompt, and system paths are hard-denied.
-- **Tool scope.** Each role has an explicit tool preset
-  (`readonly` / `full` / custom) — there is no ambient access.
-- **Untrusted inbound data.** Webhook payloads are fenced as untrusted
-  data and never executed as instructions.
-- **No background exfiltration.** The plugin makes no outbound calls
-  beyond the providers you configure and the search endpoints you
-  opt into.
-- **Fail-open hooks.** Permission hooks are a guard layer, not a
-  sandbox: if the mixdog daemon or its hook pipe is down, hook
-  decisions default to allow. `/mixdog:doctor` warns explicitly when
-  the hook pipe is unreachable. See the "Fail-open Hook Model" section
-  in [SECURITY.md](SECURITY.md).
-
-For the full local state, secret, and network model, see
-[SECURITY.md](SECURITY.md) and [DATA-FLOW.md](DATA-FLOW.md). To restore the
-pre-install `CLAUDE.md` and Claude Code settings, run
-`node scripts/uninstall.mjs`; for full removal, see
-[UNINSTALL.md](UNINSTALL.md).
-
-## Windows support
-
-mixdog is developed on Windows and tested on Windows + Linux.
-All scripts use forward slashes or `path.join`, line endings are
-normalised to LF via `.gitattributes` (except `.cmd` / `.bat` /
-`.ps1`, which stay CRLF), and Node child-process calls resolve
-binaries through `process.platform`-aware shims.
-
-The prebuilt memory runtime ships for Windows (`win32-x64`), Linux
-(`linux-x64`), and macOS on both Apple Silicon (`darwin-arm64`) and Intel
-(`darwin-x64`); the optional voice helper publishes verified assets for the
-same platforms. `linux-arm64` is not yet built.
+The prebuilt memory runtime ships for Windows (`win32-x64`), Linux (`linux-x64`),
+and macOS on Apple Silicon (`darwin-arm64`) and Intel (`darwin-x64`); the optional
+voice helper publishes verified assets for the same platforms. `linux-arm64` is
+not yet built.
 
 The `bash` MCP tool is OS-native: Windows runs commands through PowerShell
-(`pwsh.exe` when available, otherwise Windows PowerShell), while macOS/Linux
-use `/bin/sh`. No extra Windows shell runtime is required or auto-installed.
+(`pwsh.exe` when available, otherwise Windows PowerShell), while macOS/Linux use
+`/bin/sh`. No extra Windows shell runtime is required or auto-installed.
 
-## Contributing
+</details>
 
-Architecture notes live in [ARCHITECTURE.md](ARCHITECTURE.md). Contributor
-setup and PR expectations live in [CONTRIBUTING.md](CONTRIBUTING.md).
+## Contributing
 
-Before opening a PR, run:
+Architecture notes live in [ARCHITECTURE.md](ARCHITECTURE.md); contributor setup
+and PR expectations in [CONTRIBUTING.md](CONTRIBUTING.md). Before opening a PR, run:
 
 ```sh
 bun run ci

package/bin/statusline-launcher.mjs

@@ -21,6 +21,10 @@ function failSoft() {
   process.exit(0);
 }
 
+function claudeConfigDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
 async function main() {
   // CC stdin JSON (may be empty). Never block the tick on a read error.
   let stdinBuf = Buffer.alloc(0);
@@ -29,7 +33,7 @@ async function main() {
   // Resolve the ACTIVE install from the manifest — manifest-canonical, no
   // version pin. Any failure here → fail-soft.
   const manifestPath = path.join(
-    os.homedir(), '.claude', 'plugins', 'installed_plugins.json'
+    claudeConfigDir(), 'plugins', 'installed_plugins.json'
   );
   let installPath = '';
   try {