Repository navigation
Docs: surface the reranker + close v2.7.0 doc gaps (tags, MCP tool list/resources/prompts) + guardrail test #51
Description
Summary
Close the documentation gaps that accumulated across the v2.7.0 features — starting with the reranker (built but never surfaced in the user-facing setup) — and add a test-style guardrail so the MCP doc surface can't silently drift again.
Context
Several features shipped with code + tests + green CI but incomplete docs (see the new docs/LEARNINGS.md entry "Feature PRs ship code + tests but skip the doc surface"). A sweep of README / docs/*.md / book/src/ found:
- Reranker (Improve LLM-as-reranker quality (prompt + score-parsing robustness) #21 / Improve LLM-as-reranker quality (prompt + score-parsing robustness) #36) — not surfaced for users. It's in the reference docs (
CONFIGURATION.md,INTEGRATIONS.md,DECISIONS.md) andbook/src/configuration.md, but absent frombook/src/local-only.md(the "going fully local" chapter) — the natural place to tell a local user the reranker is an optional local quality boost (qwen3:4b) and how to turn it on. README only says "optional LLM reranking" with no setup or model recommendation. journal tags(journal tags: list, count, and rename tags for corpus hygiene #33) — undocumented anywhere (README,docs/,book/src/all zero).- MCP tool list is stale. The server now exposes 13 tools (
search recent decisions threads show capture meetings todos done stats today ask synth), but the README integrations line still says "search/recent/decisions/meetings" andbook/src/integrations/claude-desktop.md(and the Claude Code chapter) list only ~6 — missingshow,capture,done,stats,today,ask,synth. - MCP resources (MCP: expose journal content as resources (today, recent, project indexes) #37) — undocumented (
journal://today|recent|projects/{slug}/indexappears in no user doc). - MCP prompts (MCP: expose pre-built prompts (weekly reflection, decisions review, project status) #44) — not in the user-facing MCP/integration docs.
(Note: #46 did document the MCP synth tool in docs/SYNTHESIS.md — that one followed through and is the model to copy.)
Acceptance Criteria
- Reranker is surfaced in
book/src/local-only.md(optional local quality boost;reranker: qwen3:4b; the extra model/RAM cost) and in the README's local-setup guidance — not just the reference docs. -
journal tagsis documented:book/src/(a tags/hygiene section),docs/USAGE.md, and a README mention. - MCP tool list refreshed everywhere to the full current set: README integrations line,
book/src/integrations/claude-desktop.md+claude-code.mdtables, anddocs/INTEGRATIONS.md. - MCP resources (MCP: expose journal content as resources (today, recent, project indexes) #37) and prompts (MCP: expose pre-built prompts (weekly reflection, decisions review, project status) #44) documented in the integration chapters.
- Guardrail test: a unit test asserts every tool/resource/prompt registered in
cmd/mcp.goappears in the README tool list and the integration chapter — so this drift fails CI next time. -
mdbook buildclean (no broken links); existing tests pass; lint passes; review approved.
Scope
In scope: README.md, docs/USAGE.md, docs/INTEGRATIONS.md, book/src/local-only.md, book/src/integrations/*.md, a new tags doc section, and the guardrail test (cmd/mcp_test.go or a small docs-coverage test).
Out of scope: new features or behavior; restructuring the book; the reference docs/*.md that are already accurate.
Technical Notes
Key files:
- book/src/local-only.md (add the reranker)
- book/src/integrations/claude-desktop.md, claude-code.md (refresh tool tables; add resources + prompts)
- README.md ("exposes search/recent/decisions/meetings" → full list; reranker setup)
- docs/USAGE.md, docs/INTEGRATIONS.md (journal tags; MCP tool enumeration)
- cmd/mcp.go (source of truth for tool/resource/prompt names)
- cmd/mcp_test.go (add the coverage assertion)
Patterns to follow:
- Copy the approach
#46used for thesynthtool indocs/SYNTHESIS.md(it documented the new MCP surface properly). - The guardrail test reads the registered names from
cmd/mcp.go(or a shared list) and greps the doc files — keep it pure-Go, no network, CI-safe under-p 1.
Complexity
-
complexity:medium— several files + one new test; no architectural decisions.
Agent Readiness
- bounded · [x] measurable (each surface named) · [x] context (the audit) · [x] patterns linked (
#46as the model) · [x] no external blockers
Activity
github-actions commentedon Jun 19, 2026
✅ This issue looks agent-ready (all required sections present). Apply the
agent-readylabel to start the agent.