Skip to content

docs: describe man1/ as the shell-command pages it actually ships #1591

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
FBISiri wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: describe man1/ as the shell-command pages it actually ships #1591

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions docs/manual-pages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,24 @@ documents the tools; the tools verify the manual.

## Where it lives

Section 3 — one page per MCP tool — is canonical **in the package**, at
`src/basic_memory/man/man3/`, so every install ships the same pages: local,
cloud, or offline. The MCP server serves them as resources (`memory://man`
is the index, `memory://man/search-notes(3)` a page) and `bm man <topic>`
prints one in a shell. The `manual` project in the Basic Memory team
workspace (cloud, shared) holds the full manual — sections 5 and 7 are
canonical there — and anyone can build their own: the schema ships as an
opt-in seed at `plugins/claude-code/schemas/manpage.md` — copy it into any
project's folder and start writing pages against it.
Sections 1 and 3 are canonical **in the package**: `src/basic_memory/man/man1/`
holds the shell commands (`ls(1)`, `grep(1)`, `find(1)`, `cat(1)`, `head(1)`,
`tail(1)`, `tree(1)`, `apropos(1)`) and `src/basic_memory/man/man3/` one page
per MCP tool, so every install ships the same pages: local, cloud, or offline.
The MCP server serves them as resources (`memory://man` is the index,
`memory://man/search-notes(3)` a page) and `bm man <topic>` prints one in a
shell. The `manual` project in the Basic Memory team workspace (cloud, shared)
holds the full manual — sections 5 and 7 are canonical there — and anyone can
build their own: the schema ships as an opt-in seed at
`plugins/claude-code/schemas/manpage.md` — copy it into any project's folder
and start writing pages against it.

Layout:

```
manual/
├── schemas/Manpage.md # the manpage schema (type: schema)
├── man1/ # CLI commands bm(1), bm-status(1), ...
├── man1/ # shell commands ls(1), grep(1), ...
├── man3/ # MCP tools write-note(3), search-notes(3), ...
├── man5/ # file formats bm-note(5), bm-observation(5), ...
├── man7/ # concepts basic-memory(7), semantic-memory(7), ...
Expand Down Expand Up @@ -55,7 +57,7 @@ two sections. `man 5 crontab` picks the section explicitly.
This manual copies that layout with the sections that have a Basic Memory
analog:

- **man1/** — `bm` CLI commands → `bm-status(1)`
- **man1/** — shell commands run against a project → `ls(1)`, `grep(1)`
- **man3/** — MCP tools, our equivalent of the "library API" section → `write-note(3)`
- **man5/** — file formats: note syntax, observations, relations, schemas → `bm-note(5)`
- **man7/** — concepts → `basic-memory(7)`, `semantic-memory(7)`
Expand Down
Loading