doctor · diff

git:20260812.b2d5f10 to git:20260815.8b97701

49 added, 69 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: doctor
- description: Diagnose a Cortadel plugin install end to end — config resolution, server health, auth, and a live read. Use when memory doesn't seem to be working (no recall injected, add_memories/search_memory erroring), or right after installing or reconfiguring the plugin. Reports every check rather than stopping at the first failure.
+ description: Diagnose a Cortadel plugin install end to end — config resolution, server health, auth, a live read, and what the hooks themselves last reported. Use when memory doesn't seem to be working (no recall injected, add_memories/search_memory erroring), or right after installing or reconfiguring the plugin. Reports every check rather than stopping at the first failure.
---
# Cortadel Doctor
- End-to-end install diagnosis. Run every check below and report all of them — do not stop at the
- first failure. **Never use `cortadel-plugin/scripts/lib.mjs`'s `api()` helper for any of this**: it
- swallows every failure (non-2xx, timeout, network error) into `null`, which is exactly wrong for a
- diagnostic whose entire job is telling a 401 apart from zero results. Use raw `curl` (or the MCP
- tools directly) so real status codes and error bodies stay visible.
-
- ## Execution
-
- ### Check 1 — Config resolution
-
- Resolve the same required values the plugin's own hooks resolve (`base_url`, `user_id`,
- `api_key`), `CLAUDE_PLUGIN_OPTION_<KEY>` tier first, `CORTADEL_*` env var tier second — this
- mirrors `cortadel-plugin/scripts/lib.mjs`'s `cfg()`/`readOption()` precedence:
+ End-to-end install diagnosis. The checks live in a script rather than in this file:
```bash
- for pair in "CLAUDE_PLUGIN_OPTION_BASE_URL:CORTADEL_URL" \
- "CLAUDE_PLUGIN_OPTION_USER_ID:CORTADEL_USER_ID" \
- "CLAUDE_PLUGIN_OPTION_API_KEY:CORTADEL_API_KEY"; do
- opt="${pair%%:*}"; fallback="${pair##*:}"
- val="${!opt:-${!fallback:-}}"
- if [ -n "$val" ]; then echo "$fallback: resolved"; else echo "$fallback: NOT SET"; fi
- done
+ node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor.mjs"
```
- PASS if all three resolve to a non-empty value; FAIL — and report the rest of the checks as
- "skipped, no config" — if any is empty. Never print the API key's actual value, only whether it
- resolved.
+ Run it, then relay its table to the user and interpret any non-PASS row using the
+ guidance below. It exits 0 when everything passes and 1 otherwise, and it prints no
+ secret values — only whether each one resolved, and from which source.
- **Caveat, stated plainly to the user if relevant**: `CLAUDE_PLUGIN_OPTION_*` is documented as
- being injected into hook *subprocesses* specifically. Whether it is also visible inside a skill's
- own shell execution is not confirmed by anything in this repo — check both tiers and report which
- one actually resolved each value, rather than assuming the marketplace tier is reachable here.
+ **Do not hand-roll these checks with `curl` and `$CORTADEL_*` instead.** That is what
+ this skill used to do, and it reported healthy installs as broken: the hooks receive
+ their configuration as `CLAUDE_PLUGIN_OPTION_*` variables injected into the hook
+ *subprocess*, which are **not** visible in a skill's own shell. A marketplace install
+ therefore resolves nothing from the environment. `doctor.mjs` checks the environment
+ tiers *and* the config Claude Code persisted on disk (`pluginConfigs` in
+ `~/.claude/settings.json`, `pluginSecrets` in `~/.claude/.credentials.json`), and
+ reports which tier each value came from.
- ### Check 2 — Server health (unauthenticated)
+ ## What each check means
- `GET /api/health` needs no credentials at all — it's the right first network probe, independent of
- whether your own API key is valid:
+ | Check | PASS means | On failure |
+ | --- | --- | --- |
+ | Config resolution | `base_url`, `user_id`, and `api_key` all resolved | The plugin is unconfigured and **all three hooks are silent no-ops**. Re-run `/plugin` to set the missing values, or set the `CORTADEL_*` variables for a `--plugin-dir` dev run. |
+ | Server health | `GET /api/health` returned `status=ok` | `WARN status=degraded` names the failing subsystem (`memgraph`, `embeddings`, `indexes`) — that subsystem, not the plugin, is the problem. A `FAIL` means the URL is wrong or the server is down. |
+ | Auth | `GET /api/v1/memories` returned 200 | `401` → the API key is missing or invalid. `403` → the key is valid but was minted for a different user than `user_id`. |
+ | Live read | The list endpoint returned a `total` | This is the only aggregate the server exposes; there is no stats endpoint. |
+ | Hook outcomes | The opt-in hook log exists and was tallied | `SKIP` just means `CORTADEL_HOOKS_LOG` is unset — see below. |
- ```bash
- curl -s "$CORTADEL_URL/api/health"
- ```
+ ## When every check passes but memory still "isn't working"
- Report the top-level `status` (`ok` or `degraded`) and, if present, the `checks` map (e.g.
- `checks.memgraph.ok`, `checks.embeddings.ok`). A `degraded`/503 response is a normal,
- non-exceptional outcome to report — not a reason to stop running the remaining checks.
+ This is the common case, and it is why the hook-outcome log exists. All three hooks
+ fail open by design: they exit 0 with no output on every failure path, so "the server
+ said 401", "the extractor found no facts", and "3 facts were stored" are all equally
+ silent. A green doctor run plus no visible memories usually means the Stop hook is
+ working exactly as designed and the **extractor is correctly finding no durable facts**
+ — meta-conversation about tooling, debugging sessions, and content already in the store
+ all legitimately extract nothing.
- ### Check 3 — Auth
+ To see which it is, turn on the outcome log and reproduce:
```bash
- curl -s -o /tmp/cortadel-doctor-auth.json -w "HTTP %{http_code}\n" \
- -H "Authorization: Bearer $CORTADEL_API_KEY" \
- "$CORTADEL_URL/api/v1/memories?user_id=$CORTADEL_USER_ID&size=1"
+ # any path you can read; the hooks append one JSON line per invocation
+ export CORTADEL_HOOKS_LOG=~/.cortadel-hooks.jsonl
```
- - `200` → PASS.
- - `401` → FAIL — missing or invalid API key.
- - `403` → FAIL — the key is valid but doesn't match `user_id`.
- - anything else → FAIL — report the status code and response body.
-
- ### Check 4 — Live read
-
- If Check 3 returned `200`, read back `/tmp/cortadel-doctor-auth.json`: confirm it parses as JSON
- and has an `items` array and a `total` count (`MemoryListPagedResponse`'s shape). Report `total` as
- the install's memory count — this is the only aggregate figure the server exposes; there is no
- separate stats endpoint, so this is the full extent of "stats" available anywhere.
-
- If the `cortadel` MCP server is also connected in this session, additionally call
- `mcp__cortadel__search_memory({ topK: 1 })` (no `query` — browse mode) as a second, independent
- live-read path through the MCP surface rather than REST. Report it separately: a REST pass with an
- MCP failure (or the reverse) narrows down which half of the install is actually broken. Skip this
- sub-check — don't fail it — if the MCP tool isn't available in the current session.
+ Then re-run this skill — the "Hook outcomes" row tallies the last 40 entries, e.g.
+ `Stop:no-facts×4 UserPromptSubmit:injected×6`. Read them as:
- ### Display
+ - `stored` — facts were written; the count is in the entry.
+ - `no-facts` — the server accepted the exchange and extracted nothing. **Healthy.**
+ - `error` — carries `status` (401/403/5xx) or `error` (`network`, `abort`, `parse`).
+ - `skip` — the hook bailed before any request; `reason` says which guard fired
+ (`no-config`, `hooks-disabled`, `recursion-guard`, `trivial-exchange`,
+ `prompt-too-short`, `command-prompt`, `no-assistant-text`, `transcript-unreadable`, …).
- Report all four checks together, PASS/FAIL/WARN per check, e.g.:
+ The log records outcomes and counts only — never prompt text, memory content, or the
+ API key.
- ```
- Config resolution PASS base_url, user_id, api_key all resolved (CORTADEL_* tier)
- Server health PASS status=ok
- Auth PASS HTTP 200
- Live read PASS total=142 memories; MCP search_memory: PASS
- ```
+ ## Second opinion via MCP
- If any check fails, add concrete next steps mirroring `docs/plugin.md`'s Troubleshooting section:
- 401 → check `CORTADEL_API_KEY`; 403 → check `CORTADEL_USER_ID` matches the key's user; degraded
- health → point at whichever `checks.*` entry failed.
+ If the `cortadel` MCP server is connected in this session, also call
+ `search_memory({ topK: 1 })` with no query (browse mode) as an independent live-read
+ path. Report it separately: REST passing while MCP fails (or the reverse) narrows the
+ fault to one half of the install. Skip this — don't fail it — when the tool isn't
+ available.