{"owner":"esengine","repo":"DeepSeek-Reasonix","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","internal/skill/builtincontent/reasonix-guide/SKILL.md"],"skills":{"CLAUDE.md":"# Reasonix\n\nThe project's standing instructions live in `REASONIX.md` — one file, read by\nboth Reasonix and Claude Code. Add rules there, never here.\n\n@REASONIX.md\n","internal/skill/builtincontent/reasonix-guide/SKILL.md":"---\nname: reasonix-guide\ndescription: \"Troubleshoot and configure Reasonix capabilities: Skills (project/custom/global/builtin priority, discovery dirs), Commands (override order, /dir:file naming), Hooks (11 events, automatic project loading, matchers, timeouts), MCP (reasonix.toml + .mcp.json + plugin packages, auto_start), plugin packages (native/Codex/Claude manifests), and AGENTS.md / instruction docs. Use when the user asks how to configure, debug missing skills/commands/hooks/MCP/plugins, or diagnose capability loading.\"\nrunAs: inline\n---\n\n# Reasonix self-diagnostics guide\n\nThis skill is **inlined**. Prefer evidence over guessing.\n\n## First action\n\n1. Run a **static** capability report (no network, no MCP subprocesses):\n\n```bash\nreasonix doctor capabilities --json\n```\n\n2. Only if the user **explicitly** allows starting third-party MCP servers (may network and pass configured env/headers), run live probe:\n\n```bash\nreasonix doctor capabilities --live --timeout 5s --json\n```\n\n3. On desktop, open **Settings → Diagnostics** for the same report model. The desktop \"include current session runtime\" toggle only **reads** the active tab Host (connected/failed/deferred/disabled); it does **not** start MCP.\n\nDo not invent auto-fixes. Surface stable issue codes, sources, and remediations from the report.\n\n---\n\n## Skills\n\n### Config sources and priority\n\nWinner per skill name (highest first):\n\n1. **project** — `<workspace>/{.reasonix,.agents,.agent,.claude}/skills/`\n2. **custom** — `[skills].paths` (and plugin package skill roots)\n3. **global** — `<Reasonix home>/skills` and home convention dirs\n4. **builtin** — shipped skills (including this guide)\n\nSame name: higher scope wins; lower scopes are **shadowed**. `[skills].disabled_skills` hides a name from List/Read entirely.\n\nDiscovery conventions: `.reasonix`, `.agents`, `.agent`, `.claude` (see `config.ConventionDirs`). Layouts: `<name>/SKILL.md` or flat `<name>.md` (Claude flat files need skill frontmatter).\n\n### Checks\n\n| Entry | How |\n| --- | --- |\n| CLI | `reasonix doctor capabilities` → Skills section |\n| Desktop | Settings → Skills; Settings → Diagnostics |\n| Agent | `/skill` list, `/reasonix-guide`, `run_skill` |\n\n### Symptom → cause → fix\n\n| Symptom | Likely cause | Fix |\n| --- | --- | --- |\n| Skill missing from index | Disabled, shadowed, missing description, wrong root | Check report codes `skill.shadowed`, `skill.missing_description`, disabled list, discovery roots |\n| Builtin overridden | Project/global same name | Rename or remove user skill; disable if intentional |\n| Flat Claude file ignored | No skill frontmatter under `.claude/skills` | Add `description:` / `runAs:` frontmatter or use `SKILL.md` folder |\n| Body never loads | Expected: bodies are on-demand | Invoke via `/name` or `run_skill` |\n\n### Ordered triage\n\n1. `reasonix doctor capabilities --json` → Skills\n2. Confirm name not in `disabled_skills`\n3. Confirm winner Path/Scope; if shadowed, inspect lower-priority roots\n4. Missing description: skill may load but index placeholder is weak — add `description:`\n5. Reopen session / Refresh Skills after config changes\n\n---\n\n## Commands (slash templates)\n\n### Priority\n\n`config.CommandDirsForRoot`: home convention commands → Reasonix home commands → project convention commands. **Later directory overrides earlier** on name clash (`command.Load`).\n\nName from path: `git/commit.md` → `/git:commit` (slashes → `:`).\n\n### Checks\n\nCLI/Desktop Diagnostics → Commands; invoke `/name` in chat.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Wrong body | Shadowed by later dir | Check `command.shadowed` winners |\n| Missing command | Wrong dir / extension | Place `*.md` under a scanned `commands/` root |\n| Parse fail | Unreadable file | Fix permissions / encoding (`command.read_failed`) |\n\n---\n\n## Hooks\n\n### Events (11)\n\n`PreToolUse`, `PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `PostLLMCall`, `SessionStart`, `SessionEnd`, `SubagentStop`, `Notification`, `PreCompact`.\n\n**Blocking** (exit 2 can gate the loop): `PreToolUse`, `UserPromptSubmit`. Others warn or contribute context only.\n\n### Sources\n\n- Project: `<workspace>/.reasonix/settings.json` — loaded automatically\n- Plugin packages: installed enabled packages\n- Global: `<Reasonix home>/settings.json` (always)\n\nMatch field is an **anchored** regex: `file` does **not** match `read_file`; use `.*file` or `*`. Timeout is **milliseconds** (defaults 5s gating / 30s other).\n\n### Checks\n\n`/hooks`, Settings → Hooks, Diagnostics → Hooks.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Project hooks silent | Wrong workspace / restart required | Confirm the project path and restart Reasonix after saving |\n| Matcher never fires | Non-anchored assumption / bad regex | Fix match (`hook.invalid_matcher`) |\n| Command missing | Empty command / missing context file | Fix settings entry |\n| Malformed JSON | Invalid settings.json | Repair JSON (file yields no hooks, no crash) |\n\n---\n\n## MCP servers\n\n### Merge order\n\n`config.LoadForRoot` merges:\n\n1. User/project TOML `[[plugins]]` (higher name wins vs later sources when already defined)\n2. Project `.mcp.json` servers not already in TOML\n3. Enabled **plugin packages** MCP (skipped if name already defined)\n\nTransports: `stdio` (default), `http` / streamable-http, `sse`. `auto_start=false` skips startup; nil/true = automatic. Tier `eager` blocks boot handshake; empty/background connects without blocking chat.\n\nEnv/header values may contain secrets — diagnostics list **keys only**.\n\n### Checks\n\n| Mode | Behavior |\n| --- | --- |\n| Static doctor | Config validity, command path / URL shape, start intent — **no** subprocess |\n| CLI `--live` | Isolated Host via `boot.PluginSpecsForRoot` + `plugin.Start`; auto-start only; concurrency 4; always Close |\n| Desktop runtime | Read active tab Host only |\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Not connected | `auto_start=false` or failed start | Enable / fix command/URL (`mcp.command_not_found`, `mcp.start_failed`) |\n| No tools | Connected but empty tools/list | Server config or permissions (`mcp.no_tools`) |\n| Wrong source | Shadowed by TOML vs `.mcp.json` vs package | Inspect report Source / package owner |\n| Invalid transport | Bad `type` | Use stdio/http/sse (`mcp.invalid_transport`) |\n\n---\n\n## Plugin packages\n\n### Manifests\n\n- Native: `reasonix-plugin.json`\n- Codex: `.codex-plugin/plugin.json`\n- Claude: `.claude-plugin/plugin.json` (+ limited Claude compatibility paths)\n\nState: `<Reasonix home>/plugin-packages.json`. Disabled packages do not contribute skills/hooks/MCP.\n\nUnmapped Claude-only features may appear as compatibility warnings — Reasonix does not invent support.\n\n### Checks\n\n`reasonix plugin doctor <name>`, Settings → Plugins, Diagnostics → Plugins.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Package missing | Bad root path | Reinstall / fix root (`plugin.missing_root`) |\n| Invalid manifest | Parse failure | Fix JSON/manifest (`plugin.invalid_manifest`) |\n| Skills missing | Disabled package | Enable package |\n\n---\n\n## Instructions (AGENTS.md / REASONIX.md)\n\n### Load order (ascending specificity)\n\nUser global docs → ancestor chain → project docs → project-local (`*.local.md`).\n\nRecognized names: `REASONIX.md`, `AGENTS.md`, `CLAUDE.md` (and `*.local.md` variants). Multiple files in one directory can load; symlink identity is deduped.\n\nInstructions fold into the system prompt at session boot (cache-stable prefix);\nHooks remain runtime event handlers loaded from their configured locations.\n\n### Checks\n\nDiagnostics → Instructions; memory Settings; read files on disk.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Guidance ignored | Wrong filename / empty file | Use recognized names under correct dir |\n| Wrong scope won | Local override | Check load order in report |\n\n---\n\n## Desktop Diagnostics page\n\n- Static report on open; Refresh re-runs static collect\n- Copy redacted JSON\n- Optional session runtime merge (read-only Host)\n- Jump to Settings for MCP / Skills / Plugins / Hooks when issue `settings_tab` is set\n- **Never** auto-edit config, execute hooks, or auto-reconnect from this page\n\n---\n\n## Safety\n\n- Prefer static diagnostics\n- Live MCP may run third-party code and network\n- Do not print tokens, header values, env values, URL query strings, usernames, or machine-absolute external paths\n- Report paths as `<workspace>/…`, `~/…`, or `<external>/…`\n"},"files":{"CLAUDE.md":"# Reasonix\n\nThe project's standing instructions live in `REASONIX.md` — one file, read by\nboth Reasonix and Claude Code. Add rules there, never here.\n\n@REASONIX.md\n","internal/skill/builtincontent/reasonix-guide/SKILL.md":"---\nname: reasonix-guide\ndescription: \"Troubleshoot and configure Reasonix capabilities: Skills (project/custom/global/builtin priority, discovery dirs), Commands (override order, /dir:file naming), Hooks (11 events, automatic project loading, matchers, timeouts), MCP (reasonix.toml + .mcp.json + plugin packages, auto_start), plugin packages (native/Codex/Claude manifests), and AGENTS.md / instruction docs. Use when the user asks how to configure, debug missing skills/commands/hooks/MCP/plugins, or diagnose capability loading.\"\nrunAs: inline\n---\n\n# Reasonix self-diagnostics guide\n\nThis skill is **inlined**. Prefer evidence over guessing.\n\n## First action\n\n1. Run a **static** capability report (no network, no MCP subprocesses):\n\n```bash\nreasonix doctor capabilities --json\n```\n\n2. Only if the user **explicitly** allows starting third-party MCP servers (may network and pass configured env/headers), run live probe:\n\n```bash\nreasonix doctor capabilities --live --timeout 5s --json\n```\n\n3. On desktop, open **Settings → Diagnostics** for the same report model. The desktop \"include current session runtime\" toggle only **reads** the active tab Host (connected/failed/deferred/disabled); it does **not** start MCP.\n\nDo not invent auto-fixes. Surface stable issue codes, sources, and remediations from the report.\n\n---\n\n## Skills\n\n### Config sources and priority\n\nWinner per skill name (highest first):\n\n1. **project** — `<workspace>/{.reasonix,.agents,.agent,.claude}/skills/`\n2. **custom** — `[skills].paths` (and plugin package skill roots)\n3. **global** — `<Reasonix home>/skills` and home convention dirs\n4. **builtin** — shipped skills (including this guide)\n\nSame name: higher scope wins; lower scopes are **shadowed**. `[skills].disabled_skills` hides a name from List/Read entirely.\n\nDiscovery conventions: `.reasonix`, `.agents`, `.agent`, `.claude` (see `config.ConventionDirs`). Layouts: `<name>/SKILL.md` or flat `<name>.md` (Claude flat files need skill frontmatter).\n\n### Checks\n\n| Entry | How |\n| --- | --- |\n| CLI | `reasonix doctor capabilities` → Skills section |\n| Desktop | Settings → Skills; Settings → Diagnostics |\n| Agent | `/skill` list, `/reasonix-guide`, `run_skill` |\n\n### Symptom → cause → fix\n\n| Symptom | Likely cause | Fix |\n| --- | --- | --- |\n| Skill missing from index | Disabled, shadowed, missing description, wrong root | Check report codes `skill.shadowed`, `skill.missing_description`, disabled list, discovery roots |\n| Builtin overridden | Project/global same name | Rename or remove user skill; disable if intentional |\n| Flat Claude file ignored | No skill frontmatter under `.claude/skills` | Add `description:` / `runAs:` frontmatter or use `SKILL.md` folder |\n| Body never loads | Expected: bodies are on-demand | Invoke via `/name` or `run_skill` |\n\n### Ordered triage\n\n1. `reasonix doctor capabilities --json` → Skills\n2. Confirm name not in `disabled_skills`\n3. Confirm winner Path/Scope; if shadowed, inspect lower-priority roots\n4. Missing description: skill may load but index placeholder is weak — add `description:`\n5. Reopen session / Refresh Skills after config changes\n\n---\n\n## Commands (slash templates)\n\n### Priority\n\n`config.CommandDirsForRoot`: home convention commands → Reasonix home commands → project convention commands. **Later directory overrides earlier** on name clash (`command.Load`).\n\nName from path: `git/commit.md` → `/git:commit` (slashes → `:`).\n\n### Checks\n\nCLI/Desktop Diagnostics → Commands; invoke `/name` in chat.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Wrong body | Shadowed by later dir | Check `command.shadowed` winners |\n| Missing command | Wrong dir / extension | Place `*.md` under a scanned `commands/` root |\n| Parse fail | Unreadable file | Fix permissions / encoding (`command.read_failed`) |\n\n---\n\n## Hooks\n\n### Events (11)\n\n`PreToolUse`, `PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `PostLLMCall`, `SessionStart`, `SessionEnd`, `SubagentStop`, `Notification`, `PreCompact`.\n\n**Blocking** (exit 2 can gate the loop): `PreToolUse`, `UserPromptSubmit`. Others warn or contribute context only.\n\n### Sources\n\n- Project: `<workspace>/.reasonix/settings.json` — loaded automatically\n- Plugin packages: installed enabled packages\n- Global: `<Reasonix home>/settings.json` (always)\n\nMatch field is an **anchored** regex: `file` does **not** match `read_file`; use `.*file` or `*`. Timeout is **milliseconds** (defaults 5s gating / 30s other).\n\n### Checks\n\n`/hooks`, Settings → Hooks, Diagnostics → Hooks.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Project hooks silent | Wrong workspace / restart required | Confirm the project path and restart Reasonix after saving |\n| Matcher never fires | Non-anchored assumption / bad regex | Fix match (`hook.invalid_matcher`) |\n| Command missing | Empty command / missing context file | Fix settings entry |\n| Malformed JSON | Invalid settings.json | Repair JSON (file yields no hooks, no crash) |\n\n---\n\n## MCP servers\n\n### Merge order\n\n`config.LoadForRoot` merges:\n\n1. User/project TOML `[[plugins]]` (higher name wins vs later sources when already defined)\n2. Project `.mcp.json` servers not already in TOML\n3. Enabled **plugin packages** MCP (skipped if name already defined)\n\nTransports: `stdio` (default), `http` / streamable-http, `sse`. `auto_start=false` skips startup; nil/true = automatic. Tier `eager` blocks boot handshake; empty/background connects without blocking chat.\n\nEnv/header values may contain secrets — diagnostics list **keys only**.\n\n### Checks\n\n| Mode | Behavior |\n| --- | --- |\n| Static doctor | Config validity, command path / URL shape, start intent — **no** subprocess |\n| CLI `--live` | Isolated Host via `boot.PluginSpecsForRoot` + `plugin.Start`; auto-start only; concurrency 4; always Close |\n| Desktop runtime | Read active tab Host only |\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Not connected | `auto_start=false` or failed start | Enable / fix command/URL (`mcp.command_not_found`, `mcp.start_failed`) |\n| No tools | Connected but empty tools/list | Server config or permissions (`mcp.no_tools`) |\n| Wrong source | Shadowed by TOML vs `.mcp.json` vs package | Inspect report Source / package owner |\n| Invalid transport | Bad `type` | Use stdio/http/sse (`mcp.invalid_transport`) |\n\n---\n\n## Plugin packages\n\n### Manifests\n\n- Native: `reasonix-plugin.json`\n- Codex: `.codex-plugin/plugin.json`\n- Claude: `.claude-plugin/plugin.json` (+ limited Claude compatibility paths)\n\nState: `<Reasonix home>/plugin-packages.json`. Disabled packages do not contribute skills/hooks/MCP.\n\nUnmapped Claude-only features may appear as compatibility warnings — Reasonix does not invent support.\n\n### Checks\n\n`reasonix plugin doctor <name>`, Settings → Plugins, Diagnostics → Plugins.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Package missing | Bad root path | Reinstall / fix root (`plugin.missing_root`) |\n| Invalid manifest | Parse failure | Fix JSON/manifest (`plugin.invalid_manifest`) |\n| Skills missing | Disabled package | Enable package |\n\n---\n\n## Instructions (AGENTS.md / REASONIX.md)\n\n### Load order (ascending specificity)\n\nUser global docs → ancestor chain → project docs → project-local (`*.local.md`).\n\nRecognized names: `REASONIX.md`, `AGENTS.md`, `CLAUDE.md` (and `*.local.md` variants). Multiple files in one directory can load; symlink identity is deduped.\n\nInstructions fold into the system prompt at session boot (cache-stable prefix);\nHooks remain runtime event handlers loaded from their configured locations.\n\n### Checks\n\nDiagnostics → Instructions; memory Settings; read files on disk.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Guidance ignored | Wrong filename / empty file | Use recognized names under correct dir |\n| Wrong scope won | Local override | Check load order in report |\n\n---\n\n## Desktop Diagnostics page\n\n- Static report on open; Refresh re-runs static collect\n- Copy redacted JSON\n- Optional session runtime merge (read-only Host)\n- Jump to Settings for MCP / Skills / Plugins / Hooks when issue `settings_tab` is set\n- **Never** auto-edit config, execute hooks, or auto-reconnect from this page\n\n---\n\n## Safety\n\n- Prefer static diagnostics\n- Live MCP may run third-party code and network\n- Do not print tokens, header values, env values, URL query strings, usernames, or machine-absolute external paths\n- Report paths as `<workspace>/…`, `~/…`, or `<external>/…`\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# Reasonix\n\nThe project's standing instructions live in `REASONIX.md` — one file, read by\nboth Reasonix and Claude Code. Add rules there, never here.\n\n@REASONIX.md\n","category":"root","tokens":41},{"name":"SKILL.md","path":"internal/skill/builtincontent/reasonix-guide/SKILL.md","title":"reasonix-guide Skill","content":"---\nname: reasonix-guide\ndescription: \"Troubleshoot and configure Reasonix capabilities: Skills (project/custom/global/builtin priority, discovery dirs), Commands (override order, /dir:file naming), Hooks (11 events, automatic project loading, matchers, timeouts), MCP (reasonix.toml + .mcp.json + plugin packages, auto_start), plugin packages (native/Codex/Claude manifests), and AGENTS.md / instruction docs. Use when the user asks how to configure, debug missing skills/commands/hooks/MCP/plugins, or diagnose capability loading.\"\nrunAs: inline\n---\n\n# Reasonix self-diagnostics guide\n\nThis skill is **inlined**. Prefer evidence over guessing.\n\n## First action\n\n1. Run a **static** capability report (no network, no MCP subprocesses):\n\n```bash\nreasonix doctor capabilities --json\n```\n\n2. Only if the user **explicitly** allows starting third-party MCP servers (may network and pass configured env/headers), run live probe:\n\n```bash\nreasonix doctor capabilities --live --timeout 5s --json\n```\n\n3. On desktop, open **Settings → Diagnostics** for the same report model. The desktop \"include current session runtime\" toggle only **reads** the active tab Host (connected/failed/deferred/disabled); it does **not** start MCP.\n\nDo not invent auto-fixes. Surface stable issue codes, sources, and remediations from the report.\n\n---\n\n## Skills\n\n### Config sources and priority\n\nWinner per skill name (highest first):\n\n1. **project** — `<workspace>/{.reasonix,.agents,.agent,.claude}/skills/`\n2. **custom** — `[skills].paths` (and plugin package skill roots)\n3. **global** — `<Reasonix home>/skills` and home convention dirs\n4. **builtin** — shipped skills (including this guide)\n\nSame name: higher scope wins; lower scopes are **shadowed**. `[skills].disabled_skills` hides a name from List/Read entirely.\n\nDiscovery conventions: `.reasonix`, `.agents`, `.agent`, `.claude` (see `config.ConventionDirs`). Layouts: `<name>/SKILL.md` or flat `<name>.md` (Claude flat files need skill frontmatter).\n\n### Checks\n\n| Entry | How |\n| --- | --- |\n| CLI | `reasonix doctor capabilities` → Skills section |\n| Desktop | Settings → Skills; Settings → Diagnostics |\n| Agent | `/skill` list, `/reasonix-guide`, `run_skill` |\n\n### Symptom → cause → fix\n\n| Symptom | Likely cause | Fix |\n| --- | --- | --- |\n| Skill missing from index | Disabled, shadowed, missing description, wrong root | Check report codes `skill.shadowed`, `skill.missing_description`, disabled list, discovery roots |\n| Builtin overridden | Project/global same name | Rename or remove user skill; disable if intentional |\n| Flat Claude file ignored | No skill frontmatter under `.claude/skills` | Add `description:` / `runAs:` frontmatter or use `SKILL.md` folder |\n| Body never loads | Expected: bodies are on-demand | Invoke via `/name` or `run_skill` |\n\n### Ordered triage\n\n1. `reasonix doctor capabilities --json` → Skills\n2. Confirm name not in `disabled_skills`\n3. Confirm winner Path/Scope; if shadowed, inspect lower-priority roots\n4. Missing description: skill may load but index placeholder is weak — add `description:`\n5. Reopen session / Refresh Skills after config changes\n\n---\n\n## Commands (slash templates)\n\n### Priority\n\n`config.CommandDirsForRoot`: home convention commands → Reasonix home commands → project convention commands. **Later directory overrides earlier** on name clash (`command.Load`).\n\nName from path: `git/commit.md` → `/git:commit` (slashes → `:`).\n\n### Checks\n\nCLI/Desktop Diagnostics → Commands; invoke `/name` in chat.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Wrong body | Shadowed by later dir | Check `command.shadowed` winners |\n| Missing command | Wrong dir / extension | Place `*.md` under a scanned `commands/` root |\n| Parse fail | Unreadable file | Fix permissions / encoding (`command.read_failed`) |\n\n---\n\n## Hooks\n\n### Events (11)\n\n`PreToolUse`, `PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `PostLLMCall`, `SessionStart`, `SessionEnd`, `SubagentStop`, `Notification`, `PreCompact`.\n\n**Blocking** (exit 2 can gate the loop): `PreToolUse`, `UserPromptSubmit`. Others warn or contribute context only.\n\n### Sources\n\n- Project: `<workspace>/.reasonix/settings.json` — loaded automatically\n- Plugin packages: installed enabled packages\n- Global: `<Reasonix home>/settings.json` (always)\n\nMatch field is an **anchored** regex: `file` does **not** match `read_file`; use `.*file` or `*`. Timeout is **milliseconds** (defaults 5s gating / 30s other).\n\n### Checks\n\n`/hooks`, Settings → Hooks, Diagnostics → Hooks.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Project hooks silent | Wrong workspace / restart required | Confirm the project path and restart Reasonix after saving |\n| Matcher never fires | Non-anchored assumption / bad regex | Fix match (`hook.invalid_matcher`) |\n| Command missing | Empty command / missing context file | Fix settings entry |\n| Malformed JSON | Invalid settings.json | Repair JSON (file yields no hooks, no crash) |\n\n---\n\n## MCP servers\n\n### Merge order\n\n`config.LoadForRoot` merges:\n\n1. User/project TOML `[[plugins]]` (higher name wins vs later sources when already defined)\n2. Project `.mcp.json` servers not already in TOML\n3. Enabled **plugin packages** MCP (skipped if name already defined)\n\nTransports: `stdio` (default), `http` / streamable-http, `sse`. `auto_start=false` skips startup; nil/true = automatic. Tier `eager` blocks boot handshake; empty/background connects without blocking chat.\n\nEnv/header values may contain secrets — diagnostics list **keys only**.\n\n### Checks\n\n| Mode | Behavior |\n| --- | --- |\n| Static doctor | Config validity, command path / URL shape, start intent — **no** subprocess |\n| CLI `--live` | Isolated Host via `boot.PluginSpecsForRoot` + `plugin.Start`; auto-start only; concurrency 4; always Close |\n| Desktop runtime | Read active tab Host only |\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Not connected | `auto_start=false` or failed start | Enable / fix command/URL (`mcp.command_not_found`, `mcp.start_failed`) |\n| No tools | Connected but empty tools/list | Server config or permissions (`mcp.no_tools`) |\n| Wrong source | Shadowed by TOML vs `.mcp.json` vs package | Inspect report Source / package owner |\n| Invalid transport | Bad `type` | Use stdio/http/sse (`mcp.invalid_transport`) |\n\n---\n\n## Plugin packages\n\n### Manifests\n\n- Native: `reasonix-plugin.json`\n- Codex: `.codex-plugin/plugin.json`\n- Claude: `.claude-plugin/plugin.json` (+ limited Claude compatibility paths)\n\nState: `<Reasonix home>/plugin-packages.json`. Disabled packages do not contribute skills/hooks/MCP.\n\nUnmapped Claude-only features may appear as compatibility warnings — Reasonix does not invent support.\n\n### Checks\n\n`reasonix plugin doctor <name>`, Settings → Plugins, Diagnostics → Plugins.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Package missing | Bad root path | Reinstall / fix root (`plugin.missing_root`) |\n| Invalid manifest | Parse failure | Fix JSON/manifest (`plugin.invalid_manifest`) |\n| Skills missing | Disabled package | Enable package |\n\n---\n\n## Instructions (AGENTS.md / REASONIX.md)\n\n### Load order (ascending specificity)\n\nUser global docs → ancestor chain → project docs → project-local (`*.local.md`).\n\nRecognized names: `REASONIX.md`, `AGENTS.md`, `CLAUDE.md` (and `*.local.md` variants). Multiple files in one directory can load; symlink identity is deduped.\n\nInstructions fold into the system prompt at session boot (cache-stable prefix);\nHooks remain runtime event handlers loaded from their configured locations.\n\n### Checks\n\nDiagnostics → Instructions; memory Settings; read files on disk.\n\n### Symptom → cause → fix\n\n| Symptom | Cause | Fix |\n| --- | --- | --- |\n| Guidance ignored | Wrong filename / empty file | Use recognized names under correct dir |\n| Wrong scope won | Local override | Check load order in report |\n\n---\n\n## Desktop Diagnostics page\n\n- Static report on open; Refresh re-runs static collect\n- Copy redacted JSON\n- Optional session runtime merge (read-only Host)\n- Jump to Settings for MCP / Skills / Plugins / Hooks when issue `settings_tab` is set\n- **Never** auto-edit config, execute hooks, or auto-reconnect from this page\n\n---\n\n## Safety\n\n- Prefer static diagnostics\n- Live MCP may run third-party code and network\n- Do not print tokens, header values, env values, URL query strings, usernames, or machine-absolute external paths\n- Report paths as `<workspace>/…`, `~/…`, or `<external>/…`\n","category":"internal","tokens":2138}]}