@cerefox/memory 0.9.0 → 0.9.1

package/AGENT_GUIDE.md

@@ -15,8 +15,8 @@ It is not a message bus -- it is curated, versioned, searchable memory backed by
 
 You'll be using **one** of these — whichever your user (or the harness) has configured:
 
-1. **MCP tools (default)** — ten named tools (`cerefox_search`, `cerefox_ingest`, …, `cerefox_get_help`) exposed by either a local MCP server (`@cerefox/memory` via npm, or `cerefox mcp` as a soft wrapper) or the remote `cerefox-mcp` Edge Function. Tool names and parameters are documented in **The 10 Tools** below. This is the recommended path for purpose-built agent clients.
-2. **Shell CLI (Bash tool)** — the same operations exposed as a local `uv run cerefox …` command, invoked via your Bash tool. Used when your user prefers not to install/configure an MCP server. The semantics are identical; only the surface differs. See **Using Cerefox via the CLI** near the bottom of this guide for the MCP-tool → CLI-command mapping and the small list of behavioural differences.
+1. **MCP tools (default)** — ten named tools (`cerefox_search`, `cerefox_ingest`, …, `cerefox_get_help`) exposed by either a local MCP server (`@cerefox/memory` via npm, run as `cerefox mcp`) or the remote `cerefox-mcp` Edge Function. Tool names and parameters are documented in **The 10 Tools** below. This is the recommended path for purpose-built agent clients. (A frozen Python MCP server still exists as a standalone fallback, invoked explicitly with `uv run cerefox mcp` from a repo clone.)
+2. **Shell CLI (Bash tool)** — the same operations exposed as a local `cerefox …` command (the TypeScript CLI from `@cerefox/memory`, resource-verb shape — e.g. `cerefox document get`, `cerefox project list`), invoked via your Bash tool. Used when your user prefers not to install/configure an MCP server. The semantics are identical; only the surface differs. See **Using Cerefox via the CLI** near the bottom of this guide for the MCP-tool → CLI-command mapping and the small list of behavioural differences.
 
 If you're not sure which mode you're in: check whether `cerefox_search` shows up in your tool list. If yes, use MCP. If no, ask your user where the Cerefox checkout lives — they'll have told you, typically in `CLAUDE.md`, `AGENTS.md`, or an equivalent project memory file.
 
@@ -359,7 +359,7 @@ If you're using Cerefox via the local CLI (Path C from `connect-agents.md`), the
 ## Governance
 
 - **Review status**: agent writes set `pending_review`; human edits set `approved`. Both are searchable.
-- **Soft delete**: deleted documents go to trash (recoverable). They are excluded from search. You can soft-delete via MCP (`cerefox_delete_document` if your client exposes it) or CLI (`cerefox delete-doc --yes --author <you> --author-type agent`).
+- **Soft delete**: deleted documents go to trash (recoverable). They are excluded from search. You can soft-delete via MCP (`cerefox_delete_document` if your client exposes it) or CLI (`cerefox document delete --yes --author <you> --author-type agent`).
 - **Permanent purge and restore-from-trash are web-UI-only**, by design. If you decide to delete something, **tell the user explicitly** that you soft-deleted it and that they can review or restore it via the Cerefox web UI. You cannot un-do your own soft-delete from agent code; only the human can. See [`docs/guides/access-paths.md` → Destructive operations and the trust model](docs/guides/access-paths.md#destructive-operations-and-the-trust-model).
 - **Versioning**: every update via `update_if_exists` creates an archived version. Old content is always recoverable.
 - **Audit log**: all write operations are recorded with author, timestamp, and size changes.
@@ -374,9 +374,9 @@ Read this section only if you do **not** have MCP tools available (no `cerefox_s
 
 ### Setup
 
-Your user will have told you where their Cerefox checkout lives (commonly `/Users/<name>/src/cerefox`, but check `CLAUDE.md` / `AGENTS.md` / project memory for the exact path). Run every command from that directory, or use `cd /path/to/cerefox && uv run cerefox …` in your Bash tool call.
+The Cerefox CLI is the TypeScript binary from `@cerefox/memory` (`npm install -g @cerefox/memory`), invoked as plain `cerefox <subcommand>` on your `PATH` — no repo checkout or `uv` required. It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, `cerefox metadata search`, …). Credentials come from a `.env` file resolved from the working directory, or from environment variables.
 
-If a command fails with `command not found: cerefox`, run it as `uv run cerefox <subcommand>` (the project's `uv` environment provides the binary).
+The legacy Python `uv run cerefox` is a frozen husk as of v0.9 — only `uv run cerefox mcp` (the standalone Python MCP fallback) still works; every other verb has moved to the TypeScript `cerefox` binary.
 
 > Full per-flag reference lives in [`docs/guides/cli.md`](docs/guides/cli.md). The mapping table below is the agent-facing summary. **CLI flag names match MCP parameter names exactly** (kebab-case); short forms like `--project`, `--filter`, `--count`, `--update`, `--version` are accepted as aliases.
 
@@ -384,28 +384,30 @@ If a command fails with `command not found: cerefox`, run it as `uv run cerefox
 
 | MCP tool | CLI command |
 |---|---|
-| `cerefox_search(query, match_count, project_name, metadata_filter, requestor)` | `uv run cerefox search "<query>" --match-count N --project-name <n> --metadata-filter '<json>' --requestor <name>` (also `--mode`, `--alpha`, `--min-score` — CLI-only) |
-| `cerefox_ingest(title, content, project_name, metadata, update_if_exists, document_id, source, author, author_type)` (file) | `uv run cerefox ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --source <s> --author <a> --author-type user\|agent` |
-| `cerefox_ingest(...)` (paste) | `printf '%s' "<content>" \| uv run cerefox ingest --paste --title "<title>"` (same flags) |
-| `cerefox_get_document(document_id, version_id, requestor)` | `uv run cerefox get-doc <document-id> --version-id <vid> --requestor <name>` |
-| `cerefox_list_versions(document_id, requestor)` | `uv run cerefox list-versions <document-id> --requestor <name>` |
-| `cerefox_list_projects(requestor)` | `uv run cerefox list-projects --requestor <name>` |
-| `cerefox_list_metadata_keys()` | `uv run cerefox list-metadata-keys` |
-| `cerefox_metadata_search(metadata_filter, project_name, updated_since, created_since, limit, include_content, requestor)` | `uv run cerefox metadata-search --metadata-filter '<json>' --project-name <n> --updated-since <iso> --created-since <iso> --limit N --include-content --requestor <name>` |
-| `cerefox_get_audit_log(document_id, author, operation, since, until, limit, requestor)` | `uv run cerefox get-audit-log --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --json --requestor <name>` |
+| `cerefox_search(query, match_count, project_name, metadata_filter, requestor)` | `cerefox search "<query>" --match-count N --project-name <n> --metadata-filter '<json>' --requestor <name>` (also `--mode`, `--alpha`, `--min-score`, `--only-metadata` — CLI-only) |
+| `cerefox_ingest(title, content, project_name, metadata, update_if_exists, document_id, source, author, author_type)` (file) | `cerefox document ingest <path> --title <t> --project-name <n> --metadata '<json>' --update-if-exists\|--document-id <uuid> --source <s> --author <a> --author-type user\|agent` |
+| `cerefox_ingest(...)` (paste) | `printf '%s' "<content>" \| cerefox document ingest --paste --title "<title>"` (same flags) |
+| `cerefox_get_document(document_id, version_id, requestor)` | `cerefox document get <document-id> --version-id <vid> --requestor <name>` |
+| `cerefox_list_versions(document_id, requestor)` | `cerefox document version list <document-id> --requestor <name>` |
+| `cerefox_list_projects(requestor)` | `cerefox project list --requestor <name>` |
+| `cerefox_list_metadata_keys()` | `cerefox metadata keys` |
+| `cerefox_metadata_search(metadata_filter, project_name, updated_since, created_since, limit, include_content, requestor)` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --updated-since <iso> --created-since <iso> --limit N --include-content --requestor <name>` |
+| `cerefox_get_audit_log(document_id, author, operation, since, until, limit, requestor)` | `cerefox audit list --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --json --requestor <name>` |
+
+> Other CLI verbs with no MCP equivalent: `cerefox document edit` (title/metadata patch), `cerefox document delete` / `cerefox document restore`, `cerefox project create` / `cerefox project edit`, `cerefox config list/get/set`, `cerefox server reindex`, `cerefox guides list/show`.
 
 ### Caller-identity flags (set these the same way you would on MCP)
 
 You **MUST** identify yourself on every CLI invocation, exactly as you do via MCP:
 
-- **Writes** (`ingest`, `ingest-dir`): set `--author "<your-agent-name>" --author-type "agent"`. The `author_type=agent` value auto-routes the write to `pending_review` (governance signal), matching the MCP path.
-- **Reads** (`search`, `get-doc`, `list-versions`, `list-projects`, `metadata-search`, `get-audit-log`): set `--requestor "<your-agent-name>"`.
+- **Writes** (`document ingest`, `document ingest-dir`): set `--author "<your-agent-name>" --author-type "agent"`. The `author_type=agent` value auto-routes the write to `pending_review` (governance signal), matching the MCP path.
+- **Reads** (`search`, `document get`, `document version list`, `project list`, `metadata search`, `audit list`): set `--requestor "<your-agent-name>"`.
 
 Alternative: have your user set `CEREFOX_AUTHOR_NAME`, `CEREFOX_AUTHOR_TYPE`, `CEREFOX_REQUESTOR_NAME` in their `.env` once. The CLI picks them up automatically — see [`docs/guides/cli.md`](docs/guides/cli.md) for the precedence rules.
 
 ### Behavioural differences worth knowing
 
-1. **CLI output is human-formatted by default.** `cerefox search` returns a numbered, indented text block with title, score, and a 300-char preview per result. To extract document IDs reliably, parse the `Doc: <title>  (<source>)` lines or fall back to `cerefox list-docs` for a clean tabular listing. `cerefox get-doc <id>` prints raw Markdown to stdout. **For scripted access to audit data**, use `cerefox get-audit-log --json` — one JSON object per line, ideal for piping to `jq`.
+1. **CLI output is human-formatted by default.** `cerefox search` returns a numbered, indented text block with title, score, and a 300-char preview per result. To extract document IDs reliably, parse the `Doc: <title>  (<source>)` lines or fall back to `cerefox document list` for a clean tabular listing. `cerefox document get <id>` prints raw Markdown to stdout. **For scripted access to audit data**, use `cerefox audit list --json` — one JSON object per line, ideal for piping to `jq`.
 
 2. **Every invocation is independent.** With MCP, your tool framework can pass `requestor` once per session. With the CLI, every command is a separate process — pass `--requestor` / `--author` / `--author-type` on every relevant invocation, or set the env-var defaults once at the start.
 
@@ -415,20 +417,20 @@ Alternative: have your user set `CEREFOX_AUTHOR_NAME`, `CEREFOX_AUTHOR_TYPE`, `C
 
 **Search before answering:**
 ```bash
-uv run cerefox search "OAuth design notes" --match-count 5 --requestor "claude-code"
+cerefox search "OAuth design notes" --match-count 5 --requestor "claude-code"
 ```
 
 **Search then read full content of a hit:**
 ```bash
-uv run cerefox search "OAuth design" --match-count 3 --requestor "claude-code"
-# Note the [n] entries. Pick one and grab the doc id from `list-docs` or the result preview.
-uv run cerefox get-doc <document-id> --requestor "claude-code"
+cerefox search "OAuth design" --match-count 3 --requestor "claude-code"
+# Note the [n] entries. Pick one and grab the doc id from `cerefox document list` or the result preview.
+cerefox document get <document-id> --requestor "claude-code"
 ```
 
 **Ingest a note (agent identity):**
 ```bash
 printf '# Title\n\nBody markdown with H2s for chunking.\n' \
-  | uv run cerefox ingest --paste \
+  | cerefox document ingest --paste \
       --title "Stable Title" \
       --project-name "Cerefox" \
       --metadata '{"type":"decision-log","status":"active"}' \
@@ -438,11 +440,11 @@ printf '# Title\n\nBody markdown with H2s for chunking.\n' \
 **ID-based update (preferred — deterministic):**
 ```bash
 # Step 1: search and note the [id: abc12345-...] in the result
-uv run cerefox search "the exact doc" --match-count 1 --requestor "claude-code"
+cerefox search "the exact doc" --match-count 1 --requestor "claude-code"
 
 # Step 2: update by ID
 printf '...new content...' \
-  | uv run cerefox ingest --paste \
+  | cerefox document ingest --paste \
       --title "Exact Same Title" \
       --document-id "abc12345-..." \
       --author "claude-code" --author-type "agent"
@@ -451,12 +453,12 @@ printf '...new content...' \
 **Title-based update (fallback when ID isn't available):**
 ```bash
 printf '...new content...' \
-  | uv run cerefox ingest --paste --title "Exact Same Title" --update-if-exists \
+  | cerefox document ingest --paste --title "Exact Same Title" --update-if-exists \
       --author "claude-code" --author-type "agent"
 ```
 
 **Audit-log access (scripted, JSON):**
 ```bash
-uv run cerefox get-audit-log --json --limit 1000 --requestor "claude-code" \
+cerefox audit list --json --limit 1000 --requestor "claude-code" \
   | jq 'select(.author_type == "agent")'
 ```

package/AGENT_QUICK_REFERENCE.md

@@ -51,26 +51,26 @@ metadata_search(metadata_filter={"type": "decision-log"}, updated_since="2026-03
 
 ## CLI fallback (when MCP is unavailable)
 
-If `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. From v0.5+ the canonical invocation is plain **`cerefox <subcommand>`** (installed via `npm install -g @cerefox/memory`). The legacy `uv run cerefox <subcommand>` (Python CLI in a Cerefox checkout) still works through v0.7 but emits a deprecation banner.
+If `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. The canonical invocation is plain **`cerefox <subcommand>`** (the TypeScript CLI, installed via `npm install -g @cerefox/memory`). It uses a resource-verb shape (`cerefox document get`, `cerefox project list`, …). The legacy Python `uv run cerefox` is now a frozen husk as of v0.9 — only `uv run cerefox mcp` still works.
 
 Same operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); short forms (`--filter`, `--project`, `--count`, `--update`, `--version`) work as aliases.
 
-| MCP tool | CLI (v0.5+ canonical) |
+| MCP tool | CLI |
 |---|---|
 | `cerefox_search` | `cerefox search "<q>" --requestor "<your-name>"` |
-| `cerefox_ingest` (paste) | `printf '...' \| cerefox ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |
-| `cerefox_ingest` (update by ID) | `printf '...' \| cerefox ingest --paste --title "<t>" --document-id "<uuid>" --author "<your-name>" --author-type agent` |
-| `cerefox_get_document` | `cerefox get-doc <id> --version-id <vid> --requestor "<your-name>"` |
-| `cerefox_list_versions` | `cerefox list-versions <id> --requestor "<your-name>"` |
-| `cerefox_list_projects` | `cerefox list-projects --requestor "<your-name>"` |
-| `cerefox_list_metadata_keys` | `cerefox list-metadata-keys` |
-| `cerefox_metadata_search` | `cerefox metadata-search --metadata-filter '<json>' --requestor "<your-name>"` |
+| `cerefox_ingest` (paste) | `printf '...' \| cerefox document ingest --paste --title "<t>" --author "<your-name>" --author-type agent` |
+| `cerefox_ingest` (update by ID) | `printf '...' \| cerefox document ingest --paste --title "<t>" --document-id "<uuid>" --author "<your-name>" --author-type agent` |
+| `cerefox_get_document` | `cerefox document get <id> --version-id <vid> --requestor "<your-name>"` |
+| `cerefox_list_versions` | `cerefox document version list <id> --requestor "<your-name>"` |
+| `cerefox_list_projects` | `cerefox project list --requestor "<your-name>"` |
+| `cerefox_list_metadata_keys` | `cerefox metadata keys` |
+| `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --requestor "<your-name>"` |
 | `cerefox_set_document_projects` | _MCP-only; a CLI command will be added in a future release. Until then, run via MCP if available._ |
-| `cerefox_get_audit_log` | `cerefox get-audit-log --requestor "<your-name>"` (add `--json` for scripted access) |
-| `cerefox_get_help` | `cerefox docs agent-quick-reference --print` (or `cerefox docs --list` for the full bundled-docs index) |
+| `cerefox_get_audit_log` | `cerefox audit list --requestor "<your-name>"` (add `--json` for scripted access) |
+| `cerefox_get_help` | `cerefox guides show agent-quick-reference` (or `cerefox guides list` for the full bundled-docs index) |
 
 **Set identity on every call**, exactly as you would on MCP:
-- Writes (`ingest`, `ingest-dir`): `--author "<your-name>" --author-type agent`
+- Writes (`document ingest`, `document ingest-dir`): `--author "<your-name>" --author-type agent`
 - Reads: `--requestor "<your-name>"`
 
 Or have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.