✨ feat(cli): add --command and --format filtering to list-command-examples

- Add --command flag to filter example catalog by command family
- Add --format flag to filter by text or json output format
- Support repeated flags and comma-separated values for both filters
- Validate filter values against known commands and formats
- Update operator docs with filtering examples

📝 docs(spec): add MCP tool surface documentation and example payloads

- Document current 11-tool MCP surface for maintainers
- Add example request/response payloads for resolve_scope, start_session,
  get_recent, get_note, and install_agents tools
- Add imported artifact onboarding flow section
- Document suppression behavior for replayed and privacy-blocked imports

Author: cocosip

README.md

@@ -85,7 +85,7 @@ They are not MCP tools and are not the normal end-user interaction path.
 - `codex-mem audit-follow-imports [--target-profile all|artifacts|state|retry|health] [...]`
   Reports the same hygiene targets without deleting them. `--target-profile` can enable common audit target sets before you add path, age, fail-if-matched, or `--summary-only` controls.
 - `codex-mem list-command-examples`
-  Prints the embedded import/follow example-manifest catalog shipped with the binary so operators and maintainers can discover the checked-in sample outputs without browsing the source tree. Add `--json` for a machine-readable catalog.
+  Prints the embedded import/follow example-manifest catalog shipped with the binary so operators and maintainers can discover the checked-in sample outputs without browsing the source tree. Add `--json` for a machine-readable catalog, `--command <name>` to filter to one command family, or `--format text|json` to keep only one example-output format.
 - `codex-mem migrate`
   Opens the configured SQLite database and applies embedded migrations.
 - `codex-mem serve`

docs/go/README.md

@@ -24,12 +24,14 @@ If you are deploying or operating the MCP server:
 
 - [Client Examples](./operator/client-examples.md)
 - [Import Ingestion](./operator/import-ingestion.md)
+  Batch import, long-lived follow mode, cleanup/audit hygiene commands, and packaged example-catalog lookup.
 - [Release Readiness](./operator/release-readiness.md)
 - [Troubleshooting](./operator/troubleshooting.md)
 
 If you are maintaining or testing the Go implementation:
 
 - [MCP Integration](./maintainer/mcp-integration.md)
+  Stdio/HTTP transport behavior, current 11-tool MCP surface, and source-tree smoke tests.
 - [Development Tracker](./maintainer/development-tracker.md)
 - [Development Kickoff](./maintainer/dev-kickoff.md)
 - [Implementation Plan](./maintainer/implementation-plan.md)

docs/go/maintainer/development-tracker.md

@@ -151,6 +151,20 @@ Immediate next tasks:
 
 ### 2026-03-18 Session Update
 
+- Completed: Added `--format` filtering to `list-command-examples`, including repeated and comma-separated format selectors. Text and JSON output now share the same embedded-manifest filtering path across command and format filters, runtime coverage verifies mixed command+format filtering plus argument rejection, and operator docs now show how to browse only text or JSON fixtures.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether operators now need richer catalog metadata such as fixture purpose/category tags, or whether command plus format filtering is enough.
+
+### 2026-03-18 Session Update
+
+- Completed: Added `--command` filtering to `list-command-examples`, including repeated and comma-separated command selectors. Text and JSON output now share the same parsed embedded manifest path, so filtered operator lookup stays consistent across both formats without introducing another source of truth.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether list-command-examples now has enough discovery power, or whether operators also need format-level filtering such as `--format json`.
+
+### 2026-03-18 Session Update
+
 - Completed: Extended `list-command-examples` with a `--json` mode that parses the embedded text manifest into a stable structured report. Runtime coverage now verifies both text and JSON output, so the packaged-binary example catalog can serve human lookup and simple automation without introducing a second checked-in source of truth.
 - In progress: none.
 - Blockers: none.

docs/go/maintainer/mcp-integration.md

@@ -85,6 +85,29 @@ Use this document when you need one of these:
 
 If you only want to register the packaged binary with Codex CLI, use [client-examples.md](../operator/client-examples.md).
 
+## Current Tool Surface
+
+`tools/list` should currently expose these 11 MCP tools:
+
+- `memory_bootstrap_session`
+- `memory_resolve_scope`
+- `memory_start_session`
+- `memory_save_note`
+- `memory_save_handoff`
+- `memory_save_import`
+- `memory_save_imported_note`
+- `memory_search`
+- `memory_get_recent`
+- `memory_get_note`
+- `memory_install_agents`
+
+For maintainers, the most important v1 extension additions beyond the continuity baseline are the import-audit and imported-note tools:
+
+- `memory_save_import` records durable provenance for imported watcher or relay artifacts, even when note materialization is suppressed.
+- `memory_save_imported_note` keeps imported-note materialization aligned with the same scope, privacy, and explicit-memory precedence rules as the operator-facing import commands.
+
+If a client caches tool metadata, refresh that cache after upgrades instead of assuming the older baseline surface.
+
 ## Fastest Source-Tree Smoke Test
 
 Run the checked-in smoke test:

docs/go/operator/README.md

@@ -7,7 +7,7 @@ Start here:
 - [Client Examples](./client-examples.md)
   Real MCP client registration examples for local stdio and remote HTTP.
 - [Import Ingestion](./import-ingestion.md)
-  JSONL batch ingestion through `ingest-imports` plus checkpointed follow-mode ingestion through `follow-imports`, including notify-vs-poll operator guidance.
+  JSONL batch ingestion through `ingest-imports`, checkpointed follow-mode ingestion through `follow-imports`, hygiene commands such as `cleanup-follow-imports` and `audit-follow-imports`, and `list-command-examples` discovery.
 - [Release Readiness](./release-readiness.md)
   Packaging, readiness, and release checklist.
 - [Troubleshooting](./troubleshooting.md)

docs/go/operator/import-ingestion.md

@@ -330,6 +330,18 @@ If automation needs a stable machine-readable catalog, use:
 codex-mem.exe list-command-examples --json
 ```
 
+If you only want one command family while browsing the catalog, filter it in place:
+
+```powershell
+codex-mem.exe list-command-examples --command follow-imports
+```
+
+If you only want one output format while browsing the catalog, filter it the same way:
+
+```powershell
+codex-mem.exe list-command-examples --format json
+```
+
 If a deliberate output change makes those fixtures drift, refresh the ingest fixtures from the repository root through the test-only maintainer helper:
 
 ```powershell

docs/spec/appendices/example-payloads.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This appendix provides language-neutral example request and response shapes for key `codex-mem` tools.
+This appendix provides language-neutral example request and response shapes for the current `codex-mem` v1 MCP tools.
 
 These examples illustrate intent and semantics. They are not tied to one implementation language.
 
@@ -133,6 +133,86 @@ These examples illustrate intent and semantics. They are not tied to one impleme
 }
 ```
 
+## `memory_resolve_scope`
+
+### Example request
+
+```json
+{
+  "cwd": "D:/Code/go/order-web",
+  "branch_name": "fix/order-validation",
+  "repo_remote": "git@github.com:example/order-web.git",
+  "project_name_hint": "order-web",
+  "system_name_hint": "order-platform"
+}
+```
+
+### Example response
+
+```json
+{
+  "ok": true,
+  "data": {
+    "scope": {
+      "system_id": "sys_order_platform",
+      "system_name": "order-platform",
+      "project_id": "proj_order_web",
+      "project_name": "order-web",
+      "workspace_id": "ws_order_web_main",
+      "workspace_root": "D:/Code/go/order-web",
+      "branch_name": "fix/order-validation",
+      "resolved_by": "repo_remote"
+    },
+    "resolved_by": "repo_remote"
+  },
+  "warnings": []
+}
+```
+
+## `memory_start_session`
+
+### Example request
+
+```json
+{
+  "scope": {
+    "system_id": "sys_order_platform",
+    "system_name": "order-platform",
+    "project_id": "proj_order_web",
+    "project_name": "order-web",
+    "workspace_id": "ws_order_web_main",
+    "workspace_root": "D:/Code/go/order-web",
+    "branch_name": "fix/order-validation",
+    "resolved_by": "repo_remote"
+  },
+  "task": "Continue fixing order submission validation",
+  "branch_name": "fix/order-validation"
+}
+```
+
+### Example response
+
+```json
+{
+  "ok": true,
+  "data": {
+    "session": {
+      "session_id": "sess_20260313_001",
+      "scope": {
+        "system_id": "sys_order_platform",
+        "project_id": "proj_order_web",
+        "workspace_id": "ws_order_web_main"
+      },
+      "status": "active",
+      "task": "Continue fixing order submission validation",
+      "branch_name": "fix/order-validation",
+      "started_at": "2026-03-13T10:30:00Z"
+    }
+  },
+  "warnings": []
+}
+```
+
 ## `memory_save_note`
 
 ### Example request
@@ -299,6 +379,8 @@ These examples illustrate intent and semantics. They are not tied to one impleme
 }
 ```
 
+Replay of the same imported artifact or a privacy-blocked import still returns `ok: true`, but the payload flips to `suppressed: true` and includes warning visibility instead of silently writing another durable record.
+
 ## `memory_save_imported_note`
 
 ### Example request
@@ -370,6 +452,8 @@ These examples illustrate intent and semantics. They are not tied to one impleme
 }
 ```
 
+When explicit project memory already covers the same artifact, or privacy rules exclude durable storage, the response still preserves the import audit while `materialized` becomes `false` and `suppressed` becomes `true`.
+
 ## `memory_search`
 
 ### Example request
@@ -431,3 +515,167 @@ These examples illustrate intent and semantics. They are not tied to one impleme
   "warnings": []
 }
 ```
+
+## `memory_get_recent`
+
+### Example request
+
+```json
+{
+  "scope": {
+    "system_id": "sys_order_platform",
+    "project_id": "proj_order_web",
+    "workspace_id": "ws_order_web_main"
+  },
+  "limit": 3,
+  "include_handoffs": true,
+  "include_notes": true,
+  "include_related_projects": false
+}
+```
+
+### Example response
+
+```json
+{
+  "ok": true,
+  "data": {
+    "handoffs": [
+      {
+        "handoff_id": "handoff_115",
+        "scope": {
+          "system_id": "sys_order_platform",
+          "project_id": "proj_order_web",
+          "workspace_id": "ws_order_web_main"
+        },
+        "session_id": "sess_20260313_001",
+        "kind": "final",
+        "task": "Fix order validation mismatch",
+        "summary": "Validation logic has been aligned, but draft checkout regression still needs confirmation.",
+        "next_steps": [
+          "Run regression test on saved draft checkout flow",
+          "Confirm no legacy alias references remain"
+        ],
+        "status": "open",
+        "created_at": "2026-03-13T11:10:00Z"
+      }
+    ],
+    "notes": [
+      {
+        "note_id": "note_488",
+        "scope": {
+          "system_id": "sys_order_platform",
+          "project_id": "proj_order_web",
+          "workspace_id": "ws_order_web_main"
+        },
+        "session_id": "sess_20260313_001",
+        "type": "discovery",
+        "title": "Watcher captured checkout retry regression",
+        "content": "A local watcher run showed the checkout retry button still posts a legacy payment alias after draft restore.",
+        "importance": 4,
+        "status": "active",
+        "source": "watcher_import",
+        "created_at": "2026-03-13T11:24:00Z"
+      },
+      {
+        "note_id": "note_402",
+        "scope": {
+          "system_id": "sys_order_platform",
+          "project_id": "proj_order_web",
+          "workspace_id": "ws_order_web_main"
+        },
+        "session_id": "sess_20260313_001",
+        "type": "bugfix",
+        "title": "Order validation now uses generated backend enum list",
+        "content": "Client-side validation now reads generated enum metadata instead of maintaining a stale manual list.",
+        "importance": 4,
+        "status": "active",
+        "source": "codex_explicit",
+        "created_at": "2026-03-13T10:52:00Z"
+      }
+    ]
+  },
+  "warnings": []
+}
+```
+
+## `memory_get_note`
+
+### Example request
+
+```json
+{
+  "id": "note_488",
+  "kind": "note"
+}
+```
+
+### Example response
+
+```json
+{
+  "ok": true,
+  "data": {
+    "record": {
+      "note_id": "note_488",
+      "scope": {
+        "system_id": "sys_order_platform",
+        "project_id": "proj_order_web",
+        "workspace_id": "ws_order_web_main"
+      },
+      "session_id": "sess_20260313_001",
+      "type": "discovery",
+      "title": "Watcher captured checkout retry regression",
+      "content": "A local watcher run showed the checkout retry button still posts a legacy payment alias after draft restore.",
+      "importance": 4,
+      "status": "active",
+      "source": "watcher_import",
+      "created_at": "2026-03-13T11:24:00Z"
+    }
+  },
+  "warnings": []
+}
+```
+
+## `memory_install_agents`
+
+### Example request
+
+```json
+{
+  "target": "project",
+  "mode": "safe",
+  "cwd": "D:/Code/go/order-web",
+  "project_name": "order-web",
+  "system_name": "order-platform",
+  "related_repositories": [
+    "order-api",
+    "order-worker"
+  ],
+  "preferred_tags": [
+    "spec",
+    "api",
+    "go"
+  ],
+  "allow_related_project_memory": true
+}
+```
+
+### Example response
+
+```json
+{
+  "ok": true,
+  "data": {
+    "written_files": [
+      {
+        "path": "D:/Code/go/order-web/AGENTS.md",
+        "target": "project",
+        "mode": "safe"
+      }
+    ],
+    "skipped_files": []
+  },
+  "warnings": []
+}
+```