mixdog 0.7.1

package/skills/retro-skill-proposer/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: retro-skill-proposer
+description: Use ONLY during the Retro phase of a Plan/Execute/Verify/Ship/Retro workflow to evaluate whether the completed session produced a reusable pattern worth saving as a skill draft. Never triggers during other phases. Skip if session was trivial or no distinctive pattern emerged. User-approval gated — never saves without explicit OK.
+version: 0.1.0
+---
+
+# Retro Skill Proposer
+
+## When to invoke
+
+Only at the Retro phase of the `Plan -> Execute -> Verify -> Ship -> Retro` workflow. Never during Plan/Execute/Verify/Ship. If the session did not follow this workflow at all (pure Q&A, quick lookup, etc.), do not invoke.
+
+Skip entirely when any of:
+- Fewer than 5 tool calls in session
+- Pure reading / research with no state change
+- No distinctive pattern emerged
+- An existing skill already covers the pattern (check `~/.claude/skills/`, `~/.claude/skills/auto/`, `~/.claude/skills/auto-drafts/`, plugin bundled skills)
+
+## Trigger conditions (ANY ONE is sufficient)
+
+1. **Complex success** — a 5+ tool call workflow completed successfully
+2. **Error recovery** — got past an error and found a working path
+3. **User correction** — user revealed a better approach mid-session
+4. **Novel sequence** — a non-obvious reusable tool chain worth remembering
+
+## Procedure
+
+1. **Silent scan** — review the current session's tool calls, decisions, user corrections. Do NOT narrate this step.
+2. **Match conditions** — evaluate against the four trigger conditions above.
+3. **Dedup check** — compare the candidate pattern against existing skills in:
+   - `~/.claude/skills/` (user global)
+   - `~/.claude/skills/auto/` (auto-generated, promoted)
+   - `~/.claude/skills/auto-drafts/` (auto-generated, pending)
+   - plugin bundled skills
+4. **Propose** — if eligible and non-duplicate, write a concise proposal in the user's configured language:
+   - Skill name (slug form)
+   - Which trigger condition matched
+   - When to invoke the skill
+   - Procedure (step by step)
+   - Verification method
+   - Why this is worth saving (1-2 sentences)
+5. **Wait for user approval** — the user MUST explicitly say "save" or equivalent. Silence or ambiguity means skip.
+6. **On approval** — use the `write` tool to create:
+   - `~/.claude/skills/auto-drafts/{name}/SKILL.md` with proper frontmatter (name, description, version: 0.1.0)
+   - Include the full procedure in markdown body
+7. **On skip or rejection** — leave no trace, no explanation needed. Continue the Retro normally.
+
+## Non-goals
+
+- Do NOT propose for every session
+- Do NOT save without explicit user approval
+- Do NOT duplicate existing skills
+- Do NOT modify CLAUDE.md or bridge common instructions
+- Do NOT propose during Plan/Execute/Verify/Ship phases
+- Do NOT force-inject the skill into future sessions — saved drafts sit dormant until the LLM naturally picks them up via Progressive Disclosure
+
+## SKILL.md frontmatter template for the draft
+
+```yaml
+---
+name: <slug-form-name>
+description: <one-line trigger description; keep under 200 chars; lead with "Use when..."; be specific about conditions so the LLM can match accurately>
+version: 0.1.0
+source: retro-skill-proposer
+session: <current session id or date>
+---
+```
+
+## Proposal output format (to the user, in their configured language)
+
+```
+Proposed skill: {name}
+Trigger: {which of the 4 conditions matched}
+When to use: {when to invoke this skill}
+
+Procedure:
+1. ...
+2. ...
+3. ...
+
+Verification: {how to confirm the skill worked}
+
+Why it is worth saving: {1-2 sentences}
+
+On approval, save to ~/.claude/skills/auto-drafts/{name}/SKILL.md.
+```
+
+## Verification
+
+After saving, confirm the file exists at the expected path and the frontmatter parses cleanly. Do not auto-test the skill — it sits as a draft until:
+- A batch run promotes it to `auto/` after frequency validation, OR
+- The user manually moves it to `~/.claude/skills/`

package/skills/schedule-add/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: schedule-add
+description: Invoke when the user's intent is to register a new recurring/cron-style task in mixdog so the scheduler fires it on a future cadence. Writes a new entry under `${CLAUDE_PLUGIN_DATA}/schedules/<name>/` and reloads the channels config. Do not invoke for one-shot in-session reminders (use `/loop`) or for inspecting existing schedules.
+version: 0.3.0
+---
+
+# schedule-add
+
+Register a new schedule item in mixdog.
+
+## When to invoke
+
+User intent: register a new recurring task in the mixdog scheduler. The trigger is the intent, not specific phrasing — invoke whenever the user is asking for a future-cadence task that should persist across sessions.
+
+Skip if the user only wants a one-shot run within the current session (use `/loop` for that), or asks to *list* existing schedules (just read the directory directly).
+
+## Routing model (channel presence — no `type`)
+
+A schedule with **no `channel`** is injected into the current (Lead) session when it fires — the session handles it with full context, like a webhook. A schedule **with a `channel`** is dispatched directly to that Discord channel by a standalone LLM (so it needs a `model`). Channel presence is the only switch; there is no `type` field. `src/channels/lib/config.mjs` buckets entries by `!!channel`.
+
+A channel-direct schedule that fires with nothing worth posting can suppress its own notification: emit `[meta:silent]` as the **first line** of the response and the turn/post is skipped (Discord still gets the body for audit). Mention this in `instructions.md` when the task is a conditional "only ping if X". See `rules/bridge/20-skip-protocol.md`.
+
+## Storage contract
+
+The on-disk schema MUST match what `setup-server` (POST /schedules) writes, because the scheduler reader (`src/channels/lib/scheduler.mjs`) and the setup UI consume the same `config.json` shape. Drift silently disables the entry: `scheduler.mjs` skips cron registration when `time` is absent.
+
+## Required fields
+
+Collect from the user message; ask only for the truly missing ones in plain text (no AskUserQuestion).
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `name` | yes | — | slug `[a-z0-9-]+`, becomes directory name |
+| `time` | yes | — | 5- or 6-field cron expression ONLY (e.g. `0 9 * * *`). Legacy formats (`HH:MM`, `every<N>m`, `hourly`, `daily`) are rejected by the scheduler — translate them: daily 09:00 = `0 9 * * *`; every 15 min = `*/15 * * * *`; weekday 18:00 = `0 18 * * 1-5` |
+| `timezone` | no | `Asia/Seoul` | IANA name; used by node-cron and the DND / holiday guards |
+| `days` | no | `daily` | `daily` / `weekday` / `weekend` |
+| `channel` | no | — (inject to current session) | set to a Discord channel label to dispatch DIRECT to that channel instead of injecting |
+| `model` | conditional | — | REQUIRED when `channel` is set (direct dispatch runs a standalone LLM preset, e.g. `haiku`). Omit when injecting — the session handles it, no preset needed. |
+| `enabled` | no | `true` | omit unless the user explicitly wants the entry pre-disabled (reader filters `enabled !== false`) |
+| `instructions` | yes | — | what the schedule should do when it fires (markdown body) |
+
+## Procedure
+
+1. Parse the user's request. Extract whatever is unambiguous (name, time, channel, instructions). For missing required fields ask in one short message; do NOT proceed with partial data.
+2. Validate:
+   - `name` matches `^[a-z0-9][a-z0-9-]*$`, length ≤ 64
+   - `time` is a valid 5- or 6-field cron expression. Legacy formats (`HH:MM`, `every<N>m`, `hourly`, `daily`) are NOT accepted — convert the user's phrasing to cron before writing
+   - if `channel` is set, `model` MUST also be set (direct dispatch has no preset fallback)
+   - target directory `${CLAUDE_PLUGIN_DATA}/schedules/<name>/` does NOT already exist (if it does, ask user whether to overwrite or rename)
+3. Create directory + write two files atomically (tmp + rename):
+   - `config.json` — omit fields that equal their default; NEVER write `type`:
+     ```json
+     // inject into current session (no channel)
+     { "time": "0 9 * * *" }
+
+     // direct to a channel (channel + model required)
+     { "time": "0 9 * * *", "channel": "main", "model": "haiku" }
+     ```
+   - `instructions.md`: the user-provided body as-is.
+4. Call `mcp__plugin_mixdog_mixdog__reload_config` to re-register schedules.
+5. Call `mcp__plugin_mixdog_mixdog__schedule_status` and confirm the new entry appears.
+6. Report back to the user in their configured language with: name, next fire (local time), and where it goes (current session vs which channel). One short paragraph; no bullet padding.
+
+## Failure handling
+
+- File write error → report path:error, do not retry blindly.
+- `reload_config` error → file is written but not live; tell user to restart Claude Code or rerun.
+- `schedule_status` missing the new entry → `time` expression rejected; show the raw status response.
+
+## Anti-patterns
+
+- Do not invent a `time` value when the cadence the user gave is ambiguous — ask for a specific time.
+- Do not write a legacy `time` format (`HH:MM` / `every<N>m` / `hourly` / `daily`) — the scheduler rejects it and the entry never registers; always convert to a cron expression.
+- Do not auto-overwrite an existing schedule with the same name without explicit confirmation.
+- Do not skip the `reload_config` + `schedule_status` round trip; without it the user has no proof of registration.
+- Do not write a `type` / `cron` / `mode` / `role` key. Routing is decided purely by `channel` presence; the scheduler reader does not consume those keys. Use `time` (+ optional `channel`/`model`) only.
+- Do not set `channel` without `model` — direct dispatch is rejected with no LLM preset.

package/skills/setup/SKILL.md

@@ -0,0 +1,346 @@
+---
+name: setup
+description: Invoke for ANY mixdog setup or config task — onboarding a fresh install AND editing existing config. Covers agent providers/models, bridge role→preset mapping (changing worker/reviewer/tester/debugger models), agent.presets, channels/Discord, memory, search, webhook/ngrok, quiet hours, DM access, address form (user title), launch flag, and secrets. Trigger on intents like "mixdog config", "edit/change settings", "set up", "세팅"/"설정 수정", "호칭 변경" (change how the assistant addresses the user), "조용시간"/quiet hours, DM access, "change worker (or any role) model", "add a preset", "switch provider", or first-time "what goes where". Also handles uninstall/restore intents ("remove mixdog", "restore pre-install state", "원상복구") — route those to `node scripts/uninstall.mjs` and UNINSTALL.md.
+version: 0.1.0
+---
+
+# setup
+
+Guided onboarding for a fresh mixdog install **and** a reference for editing existing user config.
+
+## Which file do I edit? (decide FIRST — do not guess paths)
+
+| You want to change… | Edit this | Never edit |
+|---|---|---|
+| Any setting value (channels, memory, agent presets, search, capabilities, cwd) | `${DATA}/mixdog-config.json` | `defaults/*.template.json`, anything under `<plugin>/cache/` |
+| Which model a role uses | `${DATA}/user-workflow.json` (`roles[].preset`) | `defaults/user-workflow.json` |
+| A secret (bot token, API key, authtoken) | OS keychain / `MIXDOG_*` env | any JSON file |
+| Skill text / prompts / plugin code | the marketplace **source** (`<plugin>/marketplaces/trib-plugin/`; dev installs: the source repo, then sync) | the `cache/` copy — it is overwritten on update/sync |
+
+`${DATA}` = `~/.claude/plugins/data/mixdog-trib-plugin/`. Rule of thumb:
+**user config → `${DATA}`; code/templates → marketplace source; `cache/` and
+`defaults/` are never the edit target.**
+
+## Key facts
+
+- The default agent provider is **Anthropic OAuth** — it reuses Claude Code's
+  own login (`~/.claude/.credentials.json`). A fresh user needs **no** Anthropic
+  API key. Direct provider API keys (OpenAI, Gemini, Anthropic, etc.) are
+  optional and only needed if the user wants a non-default provider.
+- OpenAI OAuth is also available: it logs in and writes `openai-oauth.json` in
+  the plugin data dir, or reuses an existing `~/.codex/auth.json`.
+- All settings live in a **single unified config** at
+  `${CLAUDE_PLUGIN_DATA}/mixdog-config.json` with sections
+  `channels`, `memory`, `agent`, and `search`. There are no separate
+  `search-config.json` or `bot.json` files anymore. (Anthropic OAuth reuses
+  Claude Code's credentials, so there is no Anthropic token file to create; an
+  `anthropic-oauth-models.json` cache may appear automatically and is not user
+  config.)
+- **Secrets are never written into the JSON.** Discord bot token,
+  agent/search provider API keys, and the webhook authtoken live in the **OS
+  keychain** (or `MIXDOG_*` env vars). The config file holds only non-secret
+  settings.
+- **First install reconfigures Claude Code** (originals preserved): the
+  built-in `autoMemoryEnabled` / `awaySummaryEnabled` settings are turned off
+  in `~/.claude/settings.json` (mixdog memory/recap replace them), and
+  `~/.claude/CLAUDE.md` is backed up once, then taken over by the managed
+  rules block. Snapshots live under
+  `~/.claude/backups/mixdog-user-data/install-restore/`;
+  `node scripts/uninstall.mjs` restores both.
+
+## Config structure & editing
+
+- Config lives under the plugin data dir `~/.claude/plugins/data/mixdog-trib-plugin/` (the `CLAUDE_PLUGIN_DATA` env var overrides it). Two files matter:
+- **user-workflow.json** — `roles[] {name, preset, permission}` maps each bridge role to a preset (the active role set is whatever this file defines — e.g. worker / reviewer / debugger / tester). This sets which model each role uses. To change a role's model, set its `preset` to one of the preset names below (takes effect LIVE — bridge dispatch re-reads this file on every spawn; only the Lead's injected `# Roles` list waits for the next SessionStart).
+- **mixdog-config.json → `agent.presets[] {id, name, type, provider, model, tools, effort?, fast?, xaiCacheMaxInFlight?}`** defines each preset, e.g. opus-high → claude-opus-4-8 / high, composer-2.5 → grok-composer-2.5-fast, gpt-5.5-xhigh → gpt-5.5 / xhigh. `type` is `"bridge"` and `tools` is `"full"` for normal worker presets; `xaiCacheMaxInFlight` is a grok-oauth-only tuning knob. `agent.default` is the fallback preset for any role without its own mapping. To offer a new model, add a preset here first, then point a role at it in user-workflow.json.
+- Edit via the Setup UI (Custom Workflow for role→preset, Agent presets for presets) or edit the JSON files directly (reloads next session). These are user data — no rebuild needed.
+
+## Agent providers — supported list & onboarding
+
+A preset's `provider` field selects the backend. Authoritative allow-list:
+`initProviders()` in `src/agent/orchestrator/providers/registry.mjs`; the
+openai-compatible ids + base URLs come from `OPENAI_COMPAT_PRESETS` in
+`providers/openai-compat.mjs`. Any other id throws `unknown enabled provider`.
+
+### Supported providers
+
+| `provider` | Kind | Auth | Default base URL |
+|---|---|---|---|
+| `anthropic-oauth` | first-class | OAuth — reuses Claude Code login (default, no key) | — |
+| `anthropic` | first-class | API key | — |
+| `openai-oauth` | first-class (Codex) | OAuth (`openai-oauth.json` / `~/.codex/auth.json`) | — |
+| `openai` | first-class | API key | — |
+| `gemini` | first-class | API key | — |
+| `grok-oauth` | first-class (Grok/xAI) | OAuth | — |
+| `deepseek` | openai-compat | API key | `https://api.deepseek.com` |
+| `xai` | openai-compat | API key | `https://api.x.ai/v1` |
+| `nvidia` | openai-compat | API key | `https://integrate.api.nvidia.com/v1` |
+| `ollama` | openai-compat (local) | none | `http://localhost:11434/v1` |
+| `lmstudio` | openai-compat (local) | none | `http://localhost:1234/v1` |
+
+### Where an API key goes (never in JSON)
+
+Key-bearing providers (`openai`, `anthropic`, `gemini`, `deepseek`, `xai`,
+`nvidia`) resolve their key in this precedence (`getAgentApiKey`):
+`<PROVIDER>_API_KEY` env → `MIXDOG_AGENT_<PROVIDER>_APIKEY` env → OS keychain
+account `agent.<provider>.apiKey` → alias env (`GROK_API_KEY` for `xai`).
+
+Keychain is the canonical store — a provider key placed in `mixdog-config.json`
+is ignored. On Windows the secret is a DPAPI file at
+`${DATA}/secrets/agent.<provider>.apiKey.dpapi`; macOS/Linux use the OS keychain.
+Store it via the Setup UI agent-key field (moves it to keychain, strips from
+JSON), via `saveSecret('agent.<provider>.apiKey', key)`, or by exporting the
+standard `<PROVIDER>_API_KEY` env. `ollama` / `lmstudio` are local and need no key.
+
+### End-to-end: add a provider + model + role (e.g. DeepSeek as a worker)
+
+1. **Validate + store the key.** Confirm it works (`GET <baseURL>/models` → 200),
+   then save it to keychain `agent.deepseek.apiKey` (or export `DEEPSEEK_API_KEY`).
+2. **Enable the provider** (optional — auto-enabled once the key is present): add
+   `agent.providers.deepseek = { "enabled": true, "baseURL": "https://api.deepseek.com" }`
+   to `mixdog-config.json`.
+3. **Register a preset** in `agent.presets[]`:
+   `{ "id": "deepseek-v4-pro", "name": "DEEPSEEK V4 PRO", "type": "bridge", "provider": "deepseek", "model": "deepseek-v4-pro", "tools": "full" }`
+   — use the provider's real model id (e.g. `deepseek-v4-pro`, `deepseek-v4-flash`).
+4. **Map a role → preset** in `user-workflow.json`: repoint an existing role's
+   `preset`, or add `{ "name": "deepseek-worker", "preset": "deepseek-v4-pro", "permission": "full" }`.
+   For maintenance slots (explore / cycle* / scheduler / webhook) set
+   `agent.maintenance.<slot>` to a preset id instead.
+
+**Effect timing:** new presets / providers / `agent.maintenance.*` and API keys
+apply **next session** (daemon reload); a role→preset change in
+`user-workflow.json` is **live** (re-read per bridge spawn). Ad-hoc one-off
+override: `bridge spawn role=<any> preset=<id>`.
+
+## File locations — defaults vs user data
+
+`<plugin>` = `~/.claude/plugins/`. `<ver>` = the installed mixdog version
+directory (check `<plugin>/cache/trib-plugin/mixdog/` for the actual value).
+`${CLAUDE_PLUGIN_DATA}` (`${DATA}`) defaults to
+`<plugin>/data/mixdog-trib-plugin/` and can be overridden by the env var.
+
+| Layer | Path | What it is | Edit here? |
+|---|---|---|---|
+| **Defaults (seed)** | source `<plugin>/marketplaces/trib-plugin/defaults/` · active `<plugin>/cache/trib-plugin/mixdog/<ver>/defaults/` | shipped templates copied into user data on first run | no — read-only |
+| **User config (live)** | `${DATA}/` = `<plugin>/data/mixdog-trib-plugin/` | the real config you actually edit | **yes** |
+| **Secrets** | OS keychain · `MIXDOG_*` env · `${DATA}/secrets/` | tokens & API keys | yes — never inside config JSON |
+| **Plugin / skill code** | active `<plugin>/cache/trib-plugin/mixdog/<ver>/` · source `<plugin>/marketplaces/trib-plugin/` | skill md, builtin tools, prompts | source-of-truth = marketplace |
+
+**Default file → live file** (edit the live one):
+
+| Purpose | Default (seed, do not edit) | Live (edit this) |
+|---|---|---|
+| Unified config | `defaults/mixdog-config.template.json` | `${DATA}/mixdog-config.json` |
+| Role → preset | `defaults/user-workflow.json` | `${DATA}/user-workflow.json` |
+| Hidden/internal roles | `defaults/hidden-roles.json` (loaded directly from plugin root, not seeded) | — |
+| Per-role extra brief (optional) | — | `${DATA}/roles/<role>.md` |
+| Prompt templates | `defaults/*-prompt.md`, `defaults/user-workflow.md` | seeded into `${DATA}` runtime |
+
+**Precedence:** on first launch the `defaults/` seeds (incl.
+`mixdog-config.template.json`) are copied into `${DATA}`. After that **`${DATA}`
+wins** — editing a file under `defaults/` does NOT change an already-initialized
+install. To change settings, edit the live file under `${DATA}`. A live file
+that is deleted is **not** auto-recreated once the install is initialized — the
+seed guard (`shouldSeedMissingUserData`) refuses it, drops a
+`RECOVERY-REQUIRED.txt`, and asks you to restore from the `${DATA}` backup (or
+intentionally reset the init marker). Only a never-initialized install seeds
+`mixdog-config.json` from `defaults/`. Everything else
+under `${DATA}` (logs, `pgdata/`, `sessions/`, `channels/`, `webhooks/`,
+`*-oauth*.json`, model caches) is runtime state, not user config — leave it
+alone.
+
+## Config map — where every setting lives
+
+Single source of truth is `${CLAUDE_PLUGIN_DATA}/mixdog-config.json` unless the
+row names another file. `${DATA}` = `~/.claude/plugins/data/mixdog-trib-plugin/`.
+**Effect** = when the change is picked up: `reload_config` (channels hot-reload
+now) · `SessionStart` (next session inject) · `restart` (relaunch Claude Code /
+dev full-restart) · `relaunch+flag` (relaunch with the channels flag).
+
+**Channels / Discord**
+
+| Setting | Key path | Example | Secret | Effect |
+|---|---|---|---|---|
+| Discord application id | `channels.discord.applicationId` | `"1485…"` | no | `reload_config` |
+| Channel backend | `channels.backend` | `"discord"` | no | restart |
+| Discord bot token | OS keychain / `MIXDOG_DISCORD_TOKEN` env | — | **yes** | restart |
+| Main channel | `channels.channelsConfig.main.channelId` + `channels.mainChannel` | `"1485…"` | no | `reload_config` |
+| Per-channel access | `channels.access.channels.<id>.{requireMention,allowFrom}` | `false` / `[]` | no | `reload_config` |
+| DM policy | `channels.access.dmPolicy` (`allowlist` \| `disabled`) | `"allowlist"` | no | `reload_config` |
+| Mention patterns | `channels.access.mentionPatterns[]` | `[]` | no | `reload_config` |
+| Prompt injection | `channels.promptInjection.{mode,targetPath}` | `"claude_md"` / `"~/.claude/CLAUDE.md"` | no | restart |
+| Quiet hours | `channels.quiet.{schedule,holidays}` | `"23:00-09:00"` / `"KR"` | no | `reload_config` |
+| Quiet exceptions | `channels.schedules.respectQuiet` / `channels.webhook.respectQuiet` | `false` | no | `reload_config` |
+| Webhook | `channels.webhook.{enabled,ngrokDomain}` | `true` / `"…ngrok-free.dev"` | no | `reload_config` |
+| Webhook authtoken | keychain / env | — | **yes** | restart |
+| `NGROK_BIN` | env var · Windows `HKCU\Environment\NGROK_BIN` | `…\ngrok.exe` | no | webhook restart (win) / relaunch (posix) |
+
+**Memory**
+
+| Setting | Key path | Example | Secret | Effect |
+|---|---|---|---|---|
+| Enable | `memory.enabled` | `true` | no | restart |
+| Module gate | `modules.memory.enabled` | `true` | no | restart |
+| Address form | `memory.user.title` | `"길동님"` | no | `SessionStart` |
+| Cycle intervals | `memory.cycle1.interval` / `memory.cycle2.interval` | `"10m"` / `"1h"` | no | restart |
+
+> `memory.enabled: false` only pauses the periodic cycle scheduler.
+> `modules.memory.enabled: false` (Setup UI → General → Modules) is the real
+> off switch: it stops the memory worker, hides the `recall` / `memory` tools,
+> and skips the channels worker that depends on them.
+
+**Agent / models**
+
+| Setting | File · key path | Example | Secret | Effect |
+|---|---|---|---|---|
+| Preset definitions | `agent.presets[] {id,provider,model,effort,fast,name}` | see file | no | next session |
+| Default preset | `agent.default` | `"opus-high"` | no | next session |
+| Maintenance presets | `agent.maintenance.{explore,cycle1,cycle2,cycle3,scheduler,webhook}` (unset keys fall back to the built-in `haiku` default) | `"haiku"` (all) | no | restart |
+| Role → preset | **user-workflow.json** `roles[].preset` (must equal a `presets[].id`) | `"composer-2.5"` | no | `SessionStart` (`# Roles`) |
+| Anthropic access | reuses Claude Code login `~/.claude/.credentials.json` | — | OAuth | — (default; no key) |
+| OpenAI OAuth | `${DATA}/openai-oauth.json` or `~/.codex/auth.json` | — | OAuth | restart |
+| Grok / xAI OAuth | `grok-oauth` login token (keychain) | — | OAuth | restart |
+| Direct provider API key | keychain / `MIXDOG_*` env | — | **yes** | restart |
+
+**Search**
+
+| Setting | Key path | Example | Secret | Effect |
+|---|---|---|---|---|
+| Enable | `search.enabled` | `true` | no | restart |
+| Provider | `search.provider` | `"grok-oauth"` | no | restart |
+| Raw-search keys | `search.rawSearch.credentials.<firecrawl\|tavily\|exa>.apiKey` (prefer keychain) | `""` | **sensitive** | restart |
+| xAI search key | uses the **Agent xAI key** (config UI / keychain), not a raw-search key | — | **sensitive** | restart |
+| Result / timeout limits | `search.rawSearch.maxResults` · `search.requestTimeoutMs` | `10` / `120000` | no | restart |
+| Crawl bounds | `search.crawl.{maxPages,maxDepth,sameDomainOnly}` | `10` / `2` / `true` | no | restart |
+| Per-provider model opts | `search.modelOptions.<provider>.{effort,fast}` | `"medium"` / `true` | no | restart |
+
+**Misc**
+
+| Setting | File · key path | Example | Secret | Effect |
+|---|---|---|---|---|
+| Home dir access | `capabilities.homeAccess` | `true` | no | restart |
+| Commit identity emails | `cwd.identityEmails[]` | `["dev@…","…@gmail.com"]` | no | restart |
+| Extra repo-scan roots | `cwd.extraRoots[]` | `[]` | no | restart |
+| Channels launch flag | CLI `claude --dangerously-load-development-channels plugin:mixdog@trib-plugin` | — | no | relaunch+flag |
+
+> The `search.rawSearch.credentials.*.apiKey` slots are a write-side input
+> only: a value placed there is moved into the OS keychain on Setup save and
+> stripped from the JSON. Runtime key lookup reads `MIXDOG_*` env and the
+> keychain — a plaintext key left in the JSON is ignored.
+
+## Procedure (onboarding — fill what's missing)
+
+1. Read `${CLAUDE_PLUGIN_DATA}/mixdog-config.json` and list what's missing or
+   empty across its sections:
+   - `channels` — Discord application/channel wiring.
+   - `memory` — `memory.user.title` is the address form the assistant uses for
+     the user.
+   - `agent` — provider selection (default: Anthropic OAuth; no key required).
+   - `search` — search provider selection (optional).
+   - `NGROK_BIN` env var (only when webhook public exposure is wanted).
+   For secrets, check whether they are *present* (keychain/env), not their
+   values — never read or echo a secret.
+2. Pick one missing item. For a secret, tell the user where to get the value
+   (provider console URL + the exact field to copy) and wait for them to paste
+   it. For agent access, remind them the default already works via Claude Code
+   login — a key is only needed for a different provider.
+   - `memory.user.title`: ask for the exact address form they want
+     (e.g., "길동님", "Alex"); do not ask for or store a separate first/last
+     name. The builder injects only this title.
+3. Persist the value:
+   - **Non-secret settings** → write to the right section of
+     `mixdog-config.json`.
+   - **Secrets** (Discord token, agent/search API keys, webhook authtoken) →
+     store in the OS keychain. Never write them into the JSON, never echo them
+     back, never pass them through tool args / logs.
+   - **OAuth** → no key to store: Anthropic uses Claude Code's `~/.claude`
+     credentials; OpenAI OAuth runs its login flow (`openai-oauth.json`) or
+     reuses `~/.codex/auth.json`.
+4. After a `channels`-related change (schedules / webhooks / events), call
+   `reload_config` to re-register them. Note this is **channels-focused** —
+   it does not hot-reload agent/search providers.
+5. Loop to the next missing item.
+6. When nothing critical is missing, confirm with one short line and stop.
+
+## Procedure (editing existing config)
+
+1. Identify what the user wants to change (preset for a role, new preset,
+   channels, memory title, search provider, etc.).
+2. Use **Config structure & editing** above to pick the correct file/section.
+3. Apply **one field per turn** unless the user explicitly batches related
+   edits.
+4. For role model changes: confirm the target `agent.presets` id exists (or
+   add the preset first), then update `user-workflow.json` `roles[].preset`.
+   Remind that `# Roles` in the system prompt updates on the next SessionStart.
+5. After `channels`-related edits, call `reload_config`.
+
+## Launching with channels
+
+Discord channels are gated behind a launch flag. Remind the user that mixdog
+channels only come up when Claude Code is started with:
+
+```sh
+claude --dangerously-load-development-channels plugin:mixdog@trib-plugin
+```
+
+Without that flag the channel runtime stays disabled regardless of config.
+
+## NGROK_BIN auto-detection
+
+Only runs when the user wants ngrok-backed public webhook URLs and
+`process.env.NGROK_BIN` is unset or points at a missing file. The plugin's
+`resolveNgrokBin()` reads `NGROK_BIN` from the environment, and on Windows also
+from the `HKCU\Environment` registry — there is no PATH heuristic, so the
+assistant must locate the binary deterministically and persist the chosen path.
+
+1. Probe these candidate paths in order. Use the first that exists:
+   - Windows winget: `%LOCALAPPDATA%\Microsoft\WinGet\Packages\Ngrok.Ngrok_Microsoft.Winget.Source_8wekyb3d8bbwe\ngrok.exe`
+   - Windows scoop: `%USERPROFILE%\scoop\apps\ngrok\current\ngrok.exe`
+   - Windows chocolatey: `C:\ProgramData\chocolatey\bin\ngrok.exe`
+   - POSIX homebrew (Apple silicon): `/opt/homebrew/bin/ngrok`
+   - POSIX homebrew (Intel): `/usr/local/bin/ngrok`
+   - POSIX apt / generic: `/usr/bin/ngrok`
+2. If none match, ask the user for an absolute path or for an install command
+   (`winget install Ngrok.Ngrok`, `brew install ngrok/ngrok/ngrok`, etc.) —
+   never auto-install.
+3. Show the discovered path to the user verbatim and ask for explicit
+   confirmation before writing.
+4. Persist the chosen path:
+   - Windows: `setx NGROK_BIN "<path>"` (permanent, takes effect in new shells).
+   - POSIX: append `export NGROK_BIN="<path>"` to the user's shell rc
+     (`~/.bashrc` / `~/.zshrc`).
+5. After persist:
+   - **Windows**: `setx` writes `HKCU\Environment\NGROK_BIN`, which
+     `resolveNgrokBin()` reads at start time, so a webhook (re)start picks it up
+     without relaunching Claude Code.
+   - **POSIX**: the exported var only reaches a new shell, so the user must
+     relaunch Claude Code (with the channels flag) for it to take effect.
+
+## Common errors & symptoms
+
+| Symptom | Likely cause | Check / fix |
+|---|---|---|
+| Bot offline, no channels, total silence | launch flag missing | start with `--dangerously-load-development-channels plugin:mixdog@trib-plugin` |
+| Bot online but never replies in a channel | not invited, or `requireMention:true` with no mention | invite bot to server · `channels.access.channels.<id>.requireMention` |
+| DMs ignored | sender not in `channels.access.allowFrom` | add the user ID to `channels.access.allowFrom` |
+| Role still uses old model after edit | a worker spawned BEFORE the edit keeps its bound preset (a `send` reuses it); the Lead's injected `# Roles` list also lags to SessionStart | spawn a FRESH worker — a new dispatch re-reads `user-workflow.json` live; relaunch only refreshes the Lead's `# Roles` display |
+| Role falls back to default / "preset not found" | `roles[].preset` has no matching `agent.presets[].id` | reconcile ids across user-workflow.json ↔ mixdog-config.json |
+| `reload_config` ran but model/search unchanged | reload is **channels-only** | relaunch for agent / memory / search changes |
+| Webhook public URL dead / 404 | `NGROK_BIN` unset or `channels.webhook.ngrokDomain` mismatch | env / `HKCU\Environment` + `channels.webhook` |
+| Search fails or returns empty | `search.enabled:false`, missing provider key, or expired OAuth | `search.provider` + credentials / keychain |
+| "token missing" / secret not found | keychain empty or `MIXDOG_*` env unset | re-store the secret in the keychain |
+| Address form (title) unchanged | same session | wait for next SessionStart (rules re-inject — CLAUDE.md or hook mode) |
+| 401 / OAuth expired | login lapsed | re-login (Anthropic = Claude Code login · OpenAI = codex auth · grok) |
+| Config edits silently ignored | invalid JSON broke the parse | validate `mixdog-config.json` syntax |
+| Quiet at night | `channels.quiet.schedule` active | `channels.quiet` (`respectQuiet` per surface) |
+
+## Notes
+
+- One field per turn — do not batch unrelated prompts.
+- If a value looks malformed (wrong prefix, wrong length), say so and re-ask
+  instead of storing it.
+- For the Discord bot token: also remind the user to invite the bot to the
+  target server before testing.
+- Never overwrite an existing non-empty secret without explicit confirmation.
+- NGROK_BIN is skipped entirely when the user does not need public webhook URLs
+  (local-only routing works without ngrok).

package/skills/webhook-add/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: webhook-add
+description: Invoke when the user's intent is to register a new inbound webhook listener in mixdog so an external service can deliver events to a channel. Writes a new entry under `${CLAUDE_PLUGIN_DATA}/webhooks/<name>/`, generates a secret if not given, reloads config, and returns the inbound URL + secret to paste into the source service. Do not invoke for inspecting deliveries of an existing webhook.
+version: 0.3.0
+---
+
+# webhook-add
+
+Register a new webhook listener in mixdog.
+
+## When to invoke
+
+User intent: stand up a new inbound webhook endpoint so an external service (GitHub, generic HTTP source, etc.) can deliver events into mixdog. The trigger is the intent, not specific phrasing.
+
+Skip if the user is asking to *inspect* deliveries of an existing webhook (read `deliveries.jsonl` directly).
+
+## Routing model (channel presence — no `mode`)
+
+A webhook with **no `channel`** is injected into the current (Lead) session on delivery — the session handles it with full context. A webhook **with a `channel`** is dispatched to the hidden `webhook-handler` role, which reports the result to that Discord channel (so it needs a `model`). Channel presence is the only switch; there is no `mode` field.
+
+**Skip protocol (channel-direct only):** for a channel webhook, `instructions.md` can tell the handler to emit `[meta:silent]` as the FIRST line when a delivery has nothing worth reporting (dedup, docs-only, non-default branch, etc.) — that drops the notification entirely (no channel post). Use only for true skips, never to suppress an actionable finding.
+
+## Storage contract
+
+Writes to `${CLAUDE_PLUGIN_DATA}/webhooks/<name>/{config.json, instructions.md}`. `role` is always the hidden `webhook-handler` (the reader defaults it; setup-server also forces it) — do NOT write a `role` key.
+
+## Required fields
+
+Collect from the user message; ask only for the truly missing ones in plain text (no AskUserQuestion).
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `name` | yes | — | slug `[a-z0-9-]+`, becomes directory name |
+| `parser` | no | `github` | `github` (HMAC SHA256 + GitHub event headers) or `generic` (raw JSON body) |
+| `secret` | no | auto | hex string ≥ 32 bytes; auto-generate via `crypto.randomBytes(24).toString('hex')` if absent. Required in practice — an instructions.md endpoint with no secret is rejected (fail-closed). |
+| `channel` | no | — (inject to current session) | set to a Discord channel label to dispatch DIRECT to that channel instead of injecting |
+| `model` | conditional | — | REQUIRED when `channel` is set (direct dispatch runs the webhook-handler with this preset, e.g. `haiku`). Omit when injecting — the session handles it. |
+| `instructions` | yes | — | what should happen on inbound delivery (markdown body) |
+
+## Procedure
+
+1. Parse the user's request. Extract name, parser, channel, and instructions if stated. For missing required fields ask in one short message; do NOT proceed with partial data.
+2. Validate:
+   - `name` matches `^[a-z0-9][a-z0-9-]*$`, length ≤ 64
+   - `parser` ∈ {`github`, `generic`}
+   - if `channel` is set, `model` MUST also be set (direct dispatch has no preset fallback)
+   - target directory `${CLAUDE_PLUGIN_DATA}/webhooks/<name>/` does NOT already exist
+3. If `secret` not provided, generate a 48-char hex string via `bash` (`openssl rand -hex 24` or Node `crypto.randomBytes(24).toString('hex')`).
+4. Create directory + write two files atomically (tmp + rename):
+   - `config.json` — omit defaults; NEVER write `mode` or `role`:
+     ```json
+     // inject into current session (no channel)
+     { "secret": "<hex>", "parser": "github" }
+
+     // direct to a channel (channel + model required)
+     { "secret": "<hex>", "parser": "github", "channel": "main", "model": "haiku" }
+     ```
+   - `instructions.md`: the user-provided body.
+5. Call `mcp__plugin_mixdog_mixdog__reload_config` to register the new endpoint.
+6. Resolve the inbound URL: form `<base>/webhook/<name>` (singular `webhook`, NOT `webhooks`). The `<base>` is the webhook server's public domain (channels config `webhook.ngrokDomain`; legacy `webhook.domain` is a fallback only — e.g. an ngrok URL). If it cannot be resolved, return the relative `/webhook/<name>` path and tell the user to prepend their tunnel/public URL.
+7. Report back in the user's configured language with:
+   - inbound URL (to paste into the source service)
+   - secret (so the user can paste it into the source service's webhook secret field)
+   - parser, and where output goes (current session vs which channel)
+   - reminder: rotate the secret if it is ever shown in a shared channel
+   - for a GitHub source: in the repo's **Settings → Webhooks → Add webhook**, set Payload URL = the inbound URL, Content type = `application/json`, Secret = the generated secret, and "Which events" = **Just the push event** (matches the `github` parser default).
+
+## Failure handling
+
+- File write error → report path:error, do not retry blindly.
+- `reload_config` error → file is written but not live; tell user to restart Claude Code or rerun.
+- URL resolution miss → still return the secret + relative `/webhook/<name>` path; user can build the full URL.
+
+## Anti-patterns
+
+- Do not show the secret in tool args / external logs. Once the user has copied it, treat it as sensitive.
+- Do not auto-overwrite an existing webhook with the same name without explicit confirmation — losing the secret invalidates the source-side configuration.
+- Do not skip `reload_config`; without it the new endpoint will not respond.
+- Do not write a `mode` / `role` key. Routing is decided purely by `channel` presence; `role` is always the hidden `webhook-handler`.
+- Do not set `channel` without `model` — direct dispatch is rejected with no preset.
+- Do not use `/webhooks/<name>` (plural) for the inbound URL — the live route is `/webhook/<name>` (singular).