mixdog 0.7.1

package/README.md

@@ -0,0 +1,389 @@
+# mixdog
+
+[![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)
+
+All-in-one agent plugin for the Claude Code CLI — autonomous sub-agents,
+continuous memory, multi-provider routing, and syntax-aware code tools,
+behind a single MCP server. Zero telemetry; all state under
+`~/.claude/plugins/data/mixdog-trib-plugin/`.
+
+- **Role-based sub-agents** — delegate scoped work to any provider through one `bridge` entry point
+- **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
+- **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
+
+```
+/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.
+
+## Modules & tools
+
+mixdog is one MCP server composing four user-facing modules. Code and
+filesystem tools are shared across all of them.
+
+### 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.
+
+| Tool | Purpose |
+| --- | --- |
+| `bridge` | Unified worker session control: `type=spawn` (default) delegates one scoped task to a role-bound worker; `type=send` resumes a worker by `tag`; `type=close` stops one; `type=list` enumerates active worker sessions |
+| `explore` | Open-ended codebase exploration when scope is unknown; fans out one read-only sub-agent per query, each pinned to its own topic, and is ESC-cancellable mid-run |
+| `list_models` | List configured provider presets |
+| `open_config` | Open the settings UI (Providers + Presets) in the browser; starts the resident config server if needed and returns the UI URL |
+
+### 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.
+
+| Tool | Purpose |
+| --- | --- |
+| `recall` | Retrieve stored memory (string or array fan-out; category / period / scope filters) |
+| `memory` | Persistent memory operations (status / core add-edit-delete-list / manage / prune / rebuild / cycle1-3 / flush / backfill / purge) |
+
+### 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) |
+| `web_fetch` | Fetch a full page body from a URL (follow-up to `search`) |
+
+### 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**.)
+
+| Tool | Purpose |
+| --- | --- |
+| `reply` / `react` / `edit_message` / `download_attachment` / `fetch` | Discord message operations |
+| `schedule_status` / `trigger_schedule` / `schedule_control` | Inspect, fire, or defer / skip schedules |
+| `activate_channel_bridge` / `reload_config` / `inject_command` | Runtime channel control |
+
+### 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.
+
+| Tool | Module | Purpose |
+| --- | --- | --- |
+| `code_graph` (`find_symbol`, `references`, `callers`, `search`, …) | `code_graph` | AST symbol lookup, keyword→symbols (`search`), references, callers |
+| `read` / `glob` / `list` / `grep` | `builtin` | Read files, find paths, list dirs, ripgrep content |
+| `edit` / `write` | `builtin` | Exact-string edit, whole-file write |
+| `apply_patch` | `patch` | Unified / V4A multi-hunk, multi-file patch |
+| `bash` / `job_wait` | `builtin` | Run shell commands; await background jobs |
+| `diagnostics` | `builtin` | Run the matching project type/lint checker (tsc / eslint / ruff / …) once; no resident LSP |
+| `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 |
+
+## Skills & commands
+
+**Skills** (auto-triggered by intent; Claude Code also surfaces them by name):
+
+| Skill | Use |
+| --- | --- |
+| `schedule-add` | Register a recurring cron schedule |
+| `webhook-add` | Register an inbound webhook endpoint |
+| `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 |
+
+**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
+`user-workflow.json`, not bundled.
+
+## 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.
+
+## Channels & automation
+
+Channel-driven features require launching Claude Code with the channel flag.
+mixdog is not in Anthropic's curated channel allowlist, so `--channels` is
+rejected at boot. Use the development variant instead:
+
+```sh
+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.
+
+**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**:
+
+- **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).
+
+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).
+
+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.
+
+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
+
+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`.
+
+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
+`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:
+
+| 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. |
+| `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 |
+| `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.
+See [ARCHITECTURE.md](ARCHITECTURE.md) and [DATA-FLOW.md](DATA-FLOW.md).
+
+## Safety
+
+- **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 `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.
+
+## Contributing
+
+Architecture notes live in [ARCHITECTURE.md](ARCHITECTURE.md). Contributor
+setup and PR expectations live in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Before opening a PR, run:
+
+```sh
+bun run ci
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,138 @@
+# Security Policy
+
+mixdog is a local Claude Code plugin. Its security boundary is the user's
+machine, the active Claude Code workspace, and any external providers the user
+explicitly configures.
+
+## Supported Versions
+
+Security fixes are accepted for the latest published version. If you maintain a
+fork or an older pinned install, upgrade to the latest release before reporting
+an issue unless the vulnerability is only present in a new release.
+
+## Reporting a Vulnerability
+
+Please report suspected vulnerabilities privately first. Use a private GitHub
+security advisory on the repository when advisories are enabled, or email the
+address listed in the `author` field of `package.json`.
+
+Include:
+
+- The mixdog version.
+- Operating system and Claude Code version.
+- Whether channels, Discord, webhooks, voice, or external search providers were
+  enabled.
+- A minimal reproduction or the smallest relevant log excerpt.
+
+Do not include real API keys, Discord tokens, OAuth tokens, private prompts, or
+conversation transcripts in public issues.
+
+## Security Model
+
+mixdog exposes one MCP server plus Claude Code hooks. It is designed around
+explicit local state and layered permission gates:
+
+- Destructive shell patterns are hard-blocked before execution, with no escape
+  flag: recursive deletes of root/home (`rm -rf /`, `rd /s`,
+  `Remove-Item -Recurse -Force`), `git push --force`, `git reset --hard`, disk
+  formatting (`format`, `mkfs`, `diskpart clean`, `dd if=/dev/...`), and system
+  shutdown/reboot. PowerShell `-EncodedCommand` payloads are decoded first so
+  base64-smuggled variants are caught too. Other risky commands (`git clean -f`,
+  `kubectl delete`, `terraform destroy`, `DROP TABLE`, …) get a non-blocking
+  inline warning instead of a block.
+- File tools are scoped to the active working directory by default; HOME-wide
+  writes require the `homeAccess` capability opt-in.
+- Bridge sub-agent `Edit`/`Write` to any path outside the session workspace is
+  routed through a Discord approval prompt before it runs.
+- Dangerous system paths (`/etc`, `/proc`, `/sys`, `/dev`, `C:\Windows`,
+  `System32`, Program Files, UNC shares) are hard-denied by hook policy before
+  any permission-mode check.
+- Each role runs with a fixed permission preset — `full` (read/write tools) or
+  `read` (write/edit/bash refused at the session runtime guard). Roles do not
+  gain ambient access beyond their preset.
+- Discord tokens, webhook authtokens, and LLM provider API keys are read only
+  from `MIXDOG_*` (or standard provider) environment variables or the OS
+  keychain — never from `mixdog-config.json`, which is itself written
+  owner-only.
+- Webhook payloads and headers are wrapped in untrusted-data fences and handed
+  to the agent as data to inspect, never executed as instructions.
+- Discord, webhooks, schedules, and voice are disabled unless the user starts
+  Claude Code with the development channel flag
+  (`--dangerously-load-development-channels`).
+
+## Fail-open Hook Model
+
+The permission hooks are a convenience and guard layer, not a sandbox. They
+raise the cost of an accidental destructive action; they do not contain a
+determined or compromised agent.
+
+Hook decisions travel over a local IPC channel between Claude Code and the
+mixdog daemon:
+
+- A small Rust shim (`mixdog-shim`) receives the hook payload from Claude Code
+  and forwards it to the daemon over a named pipe (`\\.\pipe\mixdog-hooks` on
+  Windows) or a Unix domain socket (`${XDG_RUNTIME_DIR:-/tmp}/mixdog-hooks.sock`).
+- A long-lived listener inside the channels worker
+  (`src/channels/lib/hook-pipe-server.mjs`) evaluates the payload and returns a
+  decision, or `"null"` to allow.
+
+This path is **fail-open by design**. When the daemon is not running, the pipe
+is unreachable, or dispatch raises an error, the components default to allow:
+the server emits `"null"` and the shim exits `0`, so nothing is blocked. A
+missing daemon therefore never wedges the user's session — but it also means
+permission hooks are silently bypassed until the daemon is restored.
+
+Run `bun scripts/doctor.mjs` to confirm the supervisor and hook pipe are
+healthy. Do not rely on the hooks alone as a security boundary; the operating
+system account, workspace isolation, and provider-side credentials remain the
+real perimeter.
+
+## Local Writes
+
+New installs seed configuration under:
+
+```text
+~/.claude/plugins/data/mixdog-trib-plugin/
+```
+
+The seeded default prompt-injection mode is `CLAUDE.md`, which writes a
+marker-delimited managed block to the configured target file, usually
+`~/.claude/CLAUDE.md`:
+
+```text
+<!-- BEGIN mixdog managed -->
+...
+<!-- END mixdog managed -->
+```
+
+mixdog only owns the content inside those markers.
+
+## Network Surface
+
+mixdog makes outbound requests only for features the user configures or invokes:
+
+- LLM providers: Anthropic, OpenAI, Gemini, or OpenAI-compatible endpoints.
+- Search providers: Firecrawl, Tavily, Exa, the configured LLM search backends,
+  and URL fetches requested through search/fetch tools.
+- Discord and webhook endpoints when channels are enabled.
+- Runtime downloads when the user installs those optional components: signed
+  manifests from `raw.githubusercontent.com` (the memory, voice, code-graph, and
+  patch manifests, plus the LiteLLM model-pricing catalog) and the
+  checksum-verified binaries/archives they point at, served from GitHub release
+  assets (`github.com/trib-plugin/mixdog/releases`) and the upstream
+  `ffmpeg-static` releases for voice.
+
+The config UI binds to `127.0.0.1` and rejects cross-origin requests.
+
+## Dependency Hygiene
+
+Run these before publishing:
+
+```sh
+bun install --frozen-lockfile
+bun run ci
+```
+
+`bun audit` is part of `bun run ci`. If a transitive dependency is vulnerable,
+prefer a narrow `overrides` pin and document why the pin exists.
+

package/UNINSTALL.md

@@ -0,0 +1,112 @@
+# Uninstall
+
+This guide removes mixdog code, local state, and optional global rule injection.
+
+## 0. Restore User-Owned Files (recommended)
+
+Run the restore helper first. It restores your pre-mixdog `~/.claude/CLAUDE.md`
+and the `autoMemoryEnabled` / `awaySummaryEnabled` keys in
+`~/.claude/settings.json` from the snapshot captured at install time. It deletes
+nothing — data/plugin/backup removal stays manual (it prints those steps).
+
+```text
+node scripts/uninstall.mjs        # or: bun scripts/uninstall.mjs
+node scripts/uninstall.mjs --dry-run   # preview without modifying anything
+```
+
+The helper covers only the restore portion (CLAUDE.md and the two settings
+keys) and prints guidance. The remaining steps below — plugin removal, deleting
+the data and backups directories, and statusLine/secrets/credential cleanup —
+are required regardless of whether you run it.
+
+## 1. Uninstall the Plugin
+
+From Claude Code:
+
+```text
+/plugin uninstall mixdog@trib-plugin
+```
+
+If the marketplace is no longer needed:
+
+```text
+/plugin marketplace remove trib-plugin
+```
+
+## 2. Remove Local Data
+
+Delete the plugin data directory if you do not want to keep memory, schedules,
+webhooks, logs, or local configuration (the unified `mixdog-config.json`):
+
+```text
+~/.claude/plugins/data/mixdog-trib-plugin/
+```
+
+This removes local memory and runtime state. It does not revoke external API
+keys at their providers.
+
+If you ran the config-preserving reinstall flow, mixdog may also have stored a
+backup of your user data. Remove it as well if you do not need it:
+
+```text
+~/.claude/backups/mixdog-user-data
+```
+
+## 3. Remove the Managed CLAUDE.md Block
+
+The restore helper in step 0 handles this automatically. To do it by hand,
+open the configured target file, usually:
+
+```text
+~/.claude/CLAUDE.md
+```
+
+Remove only the marker-delimited block:
+
+```text
+<!-- BEGIN mixdog managed -->
+...
+<!-- END mixdog managed -->
+```
+
+Older installs may contain legacy markers:
+
+```text
+<!-- BEGIN trib-plugin managed -->
+...
+<!-- END trib-plugin managed -->
+```
+
+Remove those legacy blocks as well if present.
+
+## 4. Remove the statusLine Entry
+
+If a status line appeared, mixdog injected a `statusLine` entry into:
+
+```text
+~/.claude/settings.json
+```
+
+Open that file and delete the `statusLine` object whose
+`"source": "mixdog-auto"`. Leave any status line you configured yourself
+untouched — mixdog only manages entries tagged `mixdog-auto`.
+
+## 5. Remove Secrets
+
+Delete any mixdog-related secrets from your OS keychain or credential manager.
+Common account names include:
+
+- `discord.token`
+- `webhook.authtoken`
+- `search.firecrawl.apiKey`
+- `search.tavily.apiKey`
+- `search.exa.apiKey`
+- `agent.<provider>.apiKey` (e.g. `agent.openai.apiKey`, `agent.xai.apiKey`)
+
+Also remove any `MIXDOG_*` environment variables you created.
+
+## 6. Revoke External Credentials
+
+If you configured Discord, search providers, webhooks, or direct LLM API keys,
+rotate or revoke those credentials in the provider dashboards.
+

package/agents/maintenance.md

@@ -0,0 +1,5 @@
+# Maintenance
+
+Memory cycle maintenance agent. Runs periodically (~10min) to process transcript chunks, promote facts, and keep the memory system healthy.
+
+Stateless: no transcript carried between dispatches. Each cycle is independent.

package/agents/memory-classification.md

@@ -0,0 +1,30 @@
+# Memory Classification Shared
+
+Shared category taxonomy referenced by the memory cycle agents (cycle1 chunker/classifier, cycle2 curator).
+
+## Category grades
+
+Higher grade = more permanent weight.
+
+| grade | category | meaning |
+|---|---|---|
+| 2.0 | `rule` | permanent rules, identity, operating policies |
+| 1.9 | `constraint` | hard limits (security / cost / time) |
+| 1.8 | `decision` | agreed decisions |
+| 1.6 | `fact` | verified facts / observed patterns |
+| 1.5 | `goal` | long-term direction |
+| 1.4 | `preference` | user taste / style |
+| 1.1 | `task` | active work (volatile; rarely core) |
+| 1.0 | `issue` | known problems (only if permanently relevant) |
+
+When ambiguous, pick the higher-grade category that fits (rule > constraint > decision > fact > goal > preference > task > issue).
+
+## Edge examples
+
+| contrast | A | B |
+|---|---|---|
+| rule / constraint | rule: "Commit uses `YYYY-MM-DD HH:MM` prefix" | constraint: "Never push to main without approval" |
+| decision / fact | decision: "Use bridge as the single agent entry point" | fact: "bridge dispatches via role mapping in user-workflow.json" |
+| fact / preference | fact: "User prefers Korean replies" (verified, hard) | preference: "User prefers warm polite tone" (taste) |
+| task / issue | task: "Implement chunk grouping in cycle1" | issue: "vec_memory has 6,000 stale rows" |
+| goal / decision | goal: "Cut LLM cost 50% next quarter" | decision: "Drop semantic_cache to simplify" |