chore(mcp): audit model-facing prompts, tool descriptions, and skills

[phernandez]

Summary

This PR audits the text that reaches the model: MCP tool descriptions, server instructions, prompts, skills, plugin skills, and agent rule files. It fixes dated prompting patterns and contract errors, targeting current Claude models (Opus 5.5 / Fable 5.1 / Opus 5) while staying compatible with other MCP clients.

Most fixes are contract errors. There was little dated-idiom cruft.

Wrong calls and wrong facts in model-facing text

• delete_note error guidance suggested positional calls such as delete_note("{project}", ...). That argument order would delete a note named after the project. All suggested calls now use keyword arguments.
• Skills used edit_note(operation="append", section=...), but append ignores section and writes at end of file. These are now insert_after_section / insert_before_section.
• Skills used noteType= 16 times; the parameter is note_type. create_memory_project(name=, path=) is now project_name= / project_path=.
• bm cloud set-key no longer exists. The two places that still suggested it now say bm cloud api-key save.
• memory-literary-analysis told agents to work around five bugs that are already fixed (find --meta results display a note_type value that matches nothing #1428, Search results truncate note content at 4000 characters with no indicator #1455-A note named after its project cannot be read by bare identifier (cat refuses it as the project) #1458).
• The recent_activity prompt example passed project="default".
• memory-schema described validate/diff output that the code does not produce.

Under-described tools (Group 3: add contract detail)

Tools with an explicit description= never send their docstring to clients. search_notes sent 13 words. This PR adds full contract text to:

• search_notes, including its entity_types / note_types / categories arguments
• grep, which is not a regex search and defaults to hybrid semantic plus full-text matching
• edit_note, covering all six operations and the expected_replacements default
• move_note, covering the same-project rule, extension matching, and permalink behavior
• view_note, read_content, the schema_* tools, and the OpenAI-only search / fetch adapters
• delete_note, write_note, read_note

Behavior steering removed

• Removed the note-capture pressure that contradicted the server's "do not create notes unprompted" rule. It was in continue_conversation, the .hbs templates, and read_note not-found output. The text now offers to save a note instead of pushing the model to write one.
• Removed scripted "Ask user: ..." / "Session reminder" lines from the recent_activity and list_memory_projects output.
• Server instructions now say to check notes when the request may draw on them, instead of calling recent_activity at every session start. Man pages are read when a question is open, not before each tool's first use.
• Removed migration-relative wording ("existing behavior", "All existing tools remain available").
• Deleted dead mcp/prompts/utils.py and its tests.

Rule files and runbooks

• AGENTS.md:
  • The MCP Registry step now dispatches the workflow instead of running mcp-publisher locally.
  • Removed CLI commands that no longer exist, and replaced the stale 17-tool list with a pointer to the registry.
  • Removed the narrative sections.
• .claude/commands: release.md, spec.md, and test-live.md are updated for the current repo. sync_status is gone, and the v0.13 pins are removed.
• Hermes and OpenClaw: tool descriptions are filled in, and the prompt text no longer uses caps pressure. The OpenClaw dev-file agent guide moved to docs/agent-guide.md.
• --prerelease=allow stays in install docs because PyPI 0.23.2 still pins a FastMCP beta. Only the stated reason changed. It can be dropped after the next release.

Deliberately kept

• Save-claim guards (Agents report saving to Basic Memory when no write happened (OpenClaw and Hermes) #1341/fix(integrations): make the memory write path insistent and its result citable #1367) and the Hermes CLI-avoidance steer: they guard demonstrated failures.
• The Consistency Model section, the release scripts, and the DCO / PR-title rules.
• The "read the full file before edits" rule: flagged in the audit, left as house policy.

Test plan

• just man-regen (10 pages updated)
• just package-check-skills, just package-check-hermes, just package-check-claude-code (including claude plugin validate --strict), and OpenClaw tests / biome / tsc
• uv run pytest tests/mcp tests/test_man_pages.py tests/api/v2/test_prompt_router.py tests/cli test-int/mcp
• ruff check / format on the changed files. The only ty errors are unresolved pymilvus imports (the milvus extra was not installed); none come from this diff.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YTL4S8SSKFZ8UvQc7AdAwc

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-24T02:38:12.207462Z	b27411b	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b27411bd70

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve routing for cross-project write permalinks

When Hermes calls bm_write(project="other-local-project", ...), write_note returns an unqualified permalink such as folder/note because local responses have no workspace context. A subsequent bm_read that follows this new guidance and supplies only that permalink causes _translate_args to inject Hermes's configured default project, so it can return a same-named note from the wrong project or report the new note missing. Either instruct callers to retain the write's project/project_id, or return a genuinely project-qualified identifier for every cross-project write.

AGENTS.md reference: AGENTS.md:L338-L343

Useful? React with 👍 / 👎.