Skip to content

Docs: surface the reranker + close v2.7.0 doc gaps (tags, MCP tool list/resources/prompts) + guardrail test #51

Closed

Description

@ericmann

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:

(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 tags is 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.md tables, and docs/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.go appears in the README tool list and the integration chapter — so this drift fails CI next time.
  • mdbook build clean (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 #46 used for the synth tool in docs/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 (#46 as the model) · [x] no external blockers

Activity

  1. added
    documentationImprovements or additions to documentation
    complexity:mediumMultiple files, follows established patterns
    agent-candidateIssue screener flagged as a candidate — human review needed before promoting to agent-ready
    on Jun 19, 2026
  2. github-actions commented on Jun 19, 2026

    @github-actions
    Contributor

    ✅ This issue looks agent-ready (all required sections present). Apply the agent-ready label to start the agent.

    The label is intentionally not applied automatically — a label set by the bot token wouldn't fire the agent (and would block you from triggering it). A human (or a PAT) must apply it. See docs/LEARNINGS.md.

  3. added
    agent-readyIssue is properly scoped for AI agent execution
    and removed
    agent-candidateIssue screener flagged as a candidate — human review needed before promoting to agent-ready
    on Jun 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyIssue is properly scoped for AI agent executioncomplexity:mediumMultiple files, follows established patternsdocumentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions