mixdog 0.7.18 → 0.8.0

package/skills/setup/SKILL.md

@@ -1,356 +0,0 @@
----
-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, the cross-verification workflow text & role roster (add/remove a role, tune the debugger/reviewer loop prose), 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", "remove the tester role", "tune the debugger loop", "edit the workflow prose", 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` |
-| Add/remove a role (e.g. drop `tester`), or tune the workflow loop prose (cross-verification / debugger fan-out) | `${DATA}/user-workflow.json` (`roles[]`) **and** `${DATA}/user-workflow.md` (loop text) | the `defaults/` + `cache/` copies — those are the shipped template, edited only to change fresh-install defaults |
-| 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). 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.
-
-### Workflow files — quick-edit map (NO exploration needed)
-
-Two sibling files under `${DATA}` (`~/.claude/plugins/data/mixdog-trib-plugin/`) define the active bridge workflow — edit them directly, do not go hunting:
-- **`${DATA}/user-workflow.json`** — `roles[] {name, preset, permission}`. The active role set IS exactly this list. Add or remove a role here (e.g. drop `tester`); removal takes effect on the next bridge spawn (live re-read). Keep each remaining role's `preset` untouched.
-- **`${DATA}/user-workflow.md`** — the role-assignment table + cross-verification loop prose, injected as the Lead's `# User Workflow` rule. Tune the debugger fan-out / reviewer pairing text here. The Lead's injected copy refreshes on the next SessionStart.
-- To change the **shipped fresh-install defaults** (not just this user), edit the repo's `defaults/user-workflow.{json,md}` to match. `cache/` copies are never the edit target.
-
-After editing `${DATA}` files, call `reload_config`; after editing repo `defaults/`, run dev-sync to propagate.
-
-## 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

@@ -1,81 +0,0 @@
----
-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).