docs: v0.9.1 — post-Perplexity-review fixes (Grep matcher, hook health-check, cost caveat)

[dfrostar]

Summary

Three small precision fixes flagged by a Perplexity Deep Research review of NeuralMind. Each was fact-checked against primary sources before landing. Single commit with Release-As: 0.9.1 footer so release-please proposes a clean v0.9.1 patch.

File	Fix
neuralmind/hooks.py	Comment block above the PostToolUse matchers documenting Claude Code v2.1.117+ behavior (Grep/Glob folded into Bash on native macOS/Linux). Our matcher list is robust: Grep stays for Windows + npm-install, Bash matcher catches rerouted searches on native builds.
docs/wiki/Troubleshooting.md	New "Hook Issues" section with two entries: (1) post-Claude-Code-update health check via neuralmind benchmark ., (2) explicit scope statement — what NeuralMind compresses (built-in Read/Bash/Grep) vs. what it doesn't (third-party MCP tools via mcp__<server>__<tool>).
USAGE.md	Inline caveat above the ROI Calculator dollar figures — best-case project-side projections, not independently audited; cross-link to HONEST-ASSESSMENT.md made prominent.

What was NOT changed, and why

• No version pinning of graphifyy>=0.5.2. Perplexity confused our graphifyy (two y's) with the unrelated safishamsi/graphify repo. Whatever "v0.5.2 hotfix" they cite isn't ours.
• No "MCP hooks don't work" warning. Current Claude Code hooks docs explicitly support MCP tool matchers via mcp__<server>__<tool>. Perplexity's architectural claim was wrong. Our hooks just don't subscribe to MCP tools (separate, intentional choice — now documented).
• No reference to "GitHub bug #34713" (false hook-error labels). Unverified; specific issue numbers are exactly what AI research tools confabulate.

Test plan

• python -m pytest tests/test_hooks.py tests/test_hooks_synapses.py — 26 of 26 passing
• ruff check neuralmind/hooks.py — clean
• black --check neuralmind/hooks.py — clean
• No production code changes (hooks.py change is comment-only); no test changes
• All claims verified against primary sources (Claude Code hooks reference, claude-agent-sdk-typescript#301)

Order of operations after this merges

1. release-please proposes v0.9.1 (the Release-As: 0.9.1 footer forces the patch bump even though the commit is docs(...))
2. Merge that release-please PR (squash) → cuts v0.9.1 tag
3. release.yml + docker-publish.yml + sbom.yml all fire on the tag (auto if RELEASE_PLEASE_TOKEN secret is set, else gh workflow run from your laptop)

https://claude.ai/code/session_01SH6iHNAqeMJHXdq7ubVcuJ

---

Generated by Claude Code

[github-actions]

NeuralMind self-benchmark

Status: PASS — floor 4×, measured 5.9×.

Phase 1 — Reduction on committed fixture

• Average reduction: 5.9×
• Top-k retrieval hit rate: 71.7%
• Naive baseline: 47,360 tokens (all fixture files concatenated)
• NeuralMind total: 8,149 tokens across 10 queries
• Estimated monthly savings @ 100 queries/day on Claude 3.5 Sonnet: ~$35.30

#	Query	Shape	Naive	NeuralMind	Ratio	Hit
1	auth-flow	cross-file	4,736	815	5.8×	33.3%
2	api-endpoints	focused	4,736	809	5.9×	100.0%
3	billing-flow	cross-file	4,736	846	5.6×	33.3%
4	user-storage	cross-file	4,736	672	7.0×	50.0%
5	jwt-verify	focused	4,736	681	7.0×	100.0%
6	stripe-webhook	focused	4,736	838	5.7×	100.0%
7	create-user	cross-file	4,736	794	6.0×	50.0%
8	refund	focused	4,736	827	5.7×	100.0%
9	db-choice	identity	4,736	899	5.3×	100.0%
10	invoice-send	cross-file	4,736	968	4.9×	50.0%

Phase 2 — Learning uplift

• Memory events logged: 20
• Learned patterns: 20
• Reduction ratio after neuralmind learn: 5.9× (Δ +0.00× vs. cold)
• Top-k hit rate after learning: 71.7% (Δ +0.0 points vs. cold)

Note: uplift numbers on a 500-line fixture are intentionally modest — the point is to
verify the learning mechanism persists and applies. On real production repos the lift
is larger; this test only catches regressions in persistence.

Assumptions

• Baseline: every .py file in tests/fixtures/sample_project/ concatenated.
• Tokenizer: tiktoken GPT-4o encoding (per-model breakdown in multi_model.json if generated).
• Pricing: Claude 3.5 Sonnet input @ $3.0/MTok.
• Regression floor: 4× — well below NeuralMind's typical 40–70× on real repos.

Per-model token reduction

Model	Tokenizer	Naive	NeuralMind	Ratio	Source
GPT-4o / GPT-4o-mini	tiktoken o200k_base	4,739	927	5.1×	measured
GPT-4 / GPT-3.5-turbo	tiktoken cl100k_base	4,710	918	5.1×	measured
Claude 3.5 Sonnet	estimated: GPT-4o × 1.08 — install anthropic for an exact count	5,118	1,001	5.1×	estimated
Llama 3 (70B)	estimated: GPT-4o × 1.22 — Llama tokenizer requires model weights; estimate based on published vocab ratios	5,781	1,130	5.1×	estimated

Rows marked measured use the provider's real tokenizer. Rows marked
estimated apply a published vocab-size correction to the GPT-4o count —
honest approximations, not hardcoded claims.

---

Automated by .github/workflows/ci-benchmark.yml — regenerate locally with python -m tests.benchmark.run.

[Copilot]

Pull request overview

This PR applies a small set of documentation/comment clarifications around Claude Code hook behavior, hook troubleshooting/diagnostics, and ROI calculator framing, targeting accuracy issues identified during an external review.

Changes:

• Add an ROI-calculator caveat in USAGE.md and link prominently to docs/HONEST-ASSESSMENT.md.
• Document Claude Code v2.1.117+ Grep/Glob → Bash behavior in neuralmind/hooks.py (comment-only).
• Add a new “Hook Issues (Claude Code)” troubleshooting section clarifying hook health checks and PostToolUse compression scope.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
USAGE.md	Adds a stronger caveat framing ROI dollar figures as best-case projections and links to Honest Assessment.
neuralmind/hooks.py	Adds a compatibility note about Claude Code tool-dispatch changes affecting hook matchers.
docs/wiki/Troubleshooting.md	Adds a new section on hook diagnostics and clarifies what NeuralMind does/doesn’t compress.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.