Add man pages for bm CLI commands

[bm-clawd]

Motivation

Man pages are the original machine-readable documentation — structured, parseable, and now the ideal format for AI agents to understand CLI tools. With agents increasingly using CLIs directly (see Karpathy's take), shipping proper man pages makes bm a first-class citizen in agent workflows.

The bm CLI has enough subcommands and complex flag combinations (especially search-notes with --hybrid, --min-similarity, --metadata-filters, --project, etc.) that --help output alone isn't sufficient. Man pages provide the EXAMPLES section that both humans and agents need.

References:

• Unix man pages: AI-friendly documentation since 1971
• Unix.com: man pages, LLMs, and why this old site still lives

Proposal

1. Ship man pages with bm

Start with the most complex commands:

• bm-search-notes(1) — hybrid search, metadata filters, similarity thresholds, project scoping
• bm-build-context(1) — depth, memory URLs, graph traversal
• bm-project(1) — add, list, remove, reindex
• bm(1) — overview with SEE ALSO to subcommands

Each man page should follow the standard structure:

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES      ← this is the key section for agents
EXIT STATUS
SEE ALSO

The EXAMPLES section is critical — real-world queries that agents can adapt:

EXAMPLES
    Search by semantic similarity:
        bm tool search-notes "machine learning" --hybrid

    Filter by metadata:
        bm tool search-notes --metadata '{"status": "active"}' --project claw

    Cross-project search:
        bm tool search-notes "API design" --project specs

    Lower similarity threshold for broader results:
        bm tool search-notes "coffee" --min-similarity 0.3 --page-size 20

2. Implementation options

• click-man: Auto-generate man pages from Click/Typer CLI definitions. Gets us 80% there.
• Hand-written mdoc/roff: Better EXAMPLES sections, but more maintenance.
• Hybrid: Auto-generate structure, hand-write EXAMPLES.

Install location: man bm-search-notes should work after uv tool install basic-memory.

3. MCP prompts as structured docs

The same man-page content could be served via MCP prompts capability — giving agents structured reference docs (SYNOPSIS + EXAMPLES) before they call a tool. This is the programmatic equivalent of man for MCP-connected agents.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[phernandez]

Second slice: #1389 bundles the 23 section-3 pages in the package (src/basic_memory/man/man3/), serves them as MCP resources (memory://man index, memory://man/<page> with any spelling of a page reference), and adds bm man <topic> / bm man list. bm man install unchanged. Next: registry generator for SYNOPSIS/PARAMETERS, bm man install --project, groff for section 3.

[phernandez]

Third slice: #1393 makes the MCP SYNOPSIS block on every section-3 page a generated section — just man-regen renders it from the live tool registry, pages flip to generated: registry, and a test holds the shipped blocks byte-equal to the rendering (a tool change without a regenerate fails CI). Also adds basic-memory-diagnostics(3), so the section-3 corpus now matches the tool registry one-to-one. Remaining from the roadmap: PARAMETERS from schema descriptions, section-1 pages from Typer help, bm man install --project.

[FBISiri]

Hey Paul — nice work landing the SYNOPSIS generator in #1393! The three-round Codex review cycle that hardened the frontmatter flip and escape handling is a good example of the kind of incremental cleanup that compounds.

I'd like to take the next slice: PARAMETERS generation from schema descriptions. The data source is already there — every tool schema exposes description on each property (I checked: all registered tools have descriptions on all params except the no-param basic_memory_diagnostics).

Specifically what I'm thinking:

1. render_parameters() in basic_memory.man — renders a ## PARAMETERS section from the tool's JSON schema properties, producing the same - **name** — description bullet format the hand-written pages use. Required params first, then optional, in schema order (mirroring SYNOPSIS). Type info and defaults woven into the description naturally.

2. extract_parameters() / replace_parameters() — regex helpers matching the ## PARAMETERS block, parallel to the existing extract_mcp_synopsis() / replace_mcp_synopsis() pair.

3. Update scripts/update_man_pages.py to also regenerate PARAMETERS alongside SYNOPSIS.

4. Extend the drift test in tests/test_man_pages.py to hold shipped PARAMETERS byte-equal to the rendering (same pattern as SYNOPSIS).

5. Preserve hand-curated content — the 6 pages that already have PARAMETERS sections (write-note, search-notes, build-context, edit-note, read-note, recent-activity) have field knowledge that goes beyond the schema descriptions (gotcha cross-refs, behavioral notes). The generator should produce the mechanical description; curated additions can either be preserved as-is or folded into tool docstrings upstream so the generator captures them.

The tricky design question: should the generator wholesale replace PARAMETERS (like it does SYNOPSIS), or should there be a merge strategy that preserves hand-written additions? SYNOPSIS is one-to-one with the schema so byte equality makes sense; PARAMETERS currently carry field knowledge (e.g. write-note's notes about overwrite behavior, search-notes' min_similarity threshold guidance) that isn't in the schema. Two approaches:

• Option A: Generator owns PARAMETERS entirely. Curated content migrates to tool docstrings so it flows through the schema.
• Option B: Generator produces a baseline; hand-written pages can extend individual bullets with curated notes that survive regeneration (trickier regex, more maintenance).

I lean toward Option A — it's the same principle that made SYNOPSIS reliable. Happy to hear your preference before starting.

This builds on my earlier contributions (PR #1380 tool reference, #1386 search_notes example fix). Let me know if this slice is available and if you have any preferences on the approach!