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.