@cerefox/memory 1.6.1 → 1.7.0

package/docs/guides/access-paths.md

@@ -250,30 +250,37 @@ client-facing configuration or committed to the repository.
 Cerefox classifies write operations into three tiers based on how irreversible they are.
 The access surface for each tier is **not** the same — this asymmetry is a deliberate
 architectural property, not an oversight. Future contributors should read this section
-before "completing" the parity table by adding purge or restore to agent-facing access
-paths.
+before "completing" the parity table by adding purge to agent-facing access paths.
+
+> **History**: until v1.7.0 restore sat in tier 3 with purge, on the theory that an
+> agent must not be able to silently undo its own delete. The maintainer reversed
+> that in #210 (2026-08-13): every delete and restore is audited with author
+> attribution, restore cannot destroy content, and the CLI had `document restore`
+> all along — the boundary the docs described had already outgrown the code. The
+> guarded property is now exactly one thing: **no agent path to permanent purge.**
 
 ### The three tiers
 
 | Tier | Operations | Reversible? | Where exposed |
 |---|---|---|---|
 | 1. Reads + soft mutations | search, get, list-*, ingest (create/update), metadata-search, get-audit-log | n/a (reads) / yes (versioned) | All paths — MCP, Edge Functions, CLI, web UI |
-| 2. Soft-destructive | `delete_document` (soft delete to trash), `set_review_status` | yes — restorable via web UI | All paths (CLI: `cerefox document delete`; web UI; **not** MCP or Edge Functions today) |
-| 3. **Hard-destructive** | `purge_document` (permanent), `restore_document` (un-trash), `set_version_archived` (toggle version retention) | no (purge) / yes (restore, but recovers from a destructive action) | **Web UI only** |
+| 2. Soft-destructive + recovery | `delete_document` (soft delete to trash), `restore_document` (un-trash), `set_review_status` | yes — delete is restorable; restore recovers | CLI (`cerefox document delete` / `restore`), web UI, and — since v1.7.0 (#208, #210) — MCP (`cerefox_delete_document`, which requires the caller's read-hash, and `cerefox_restore_document`). **Not** the primitive GPT-Actions Edge Functions (deliberately deferred). |
+| 3. **Hard-destructive** | `purge_document` (permanent), `set_version_archived` (toggle version retention) | no (purge) | **Web UI only** |
 
-### Why purge / restore are web-UI-only
+### Why purge is web-UI-only
 
 The recovery story behind Cerefox depends on a **human-in-the-loop confirmation step
-before irreversible action.** Soft-delete on its own is not enough — an agent that
-mistakenly soft-deletes a document needs to be unable to silently restore the same
-document later (covering its tracks), and certainly unable to escalate from soft-delete
-to permanent purge.
+before irreversible action.** Everything an agent can do — write, soft-delete,
+restore — is reversible and audited; the one action that destroys data outright is
+reserved for a human who has just looked at what they are about to destroy.
 
 So the access model is:
 
-1. **An agent (via MCP, Edge Function, or CLI) can write or soft-delete freely.** Every
-   such operation is recorded in `cerefox_audit_log` with `author`, `author_type`, and
-   `created_at`. Soft-deleted documents land in trash and are excluded from search.
+1. **An agent (via MCP, Edge Function, or CLI) can write, soft-delete, and restore
+   freely.** Every such operation is recorded in `cerefox_audit_log` with `author`,
+   `author_type`, and `created_at`. Soft-deleted documents land in trash and are
+   excluded from search; a restore puts them back and is itself an audit event, so
+   a delete-then-restore leaves a visible trail rather than silence.
 2. **A human reviews the trash through the Cerefox web UI.** They see the audit history
    for each document, decide whether the agent's action was correct, and either restore
    the document or — only after seeing what they're about to destroy — purge it.
@@ -296,9 +303,11 @@ If you're building tooling that uses the CLI (Path C) or any MCP/Edge Function p
 - **Surface the soft-delete to the user.** When your agent decides to delete something,
   tell the user explicitly: "I soft-deleted X (recoverable from the Cerefox trash in
   the web UI)." This gives them the visibility to review and either restore or commit.
-- **Do not attempt to purge or restore from agent code.** There is intentionally no
-  programmatic path. If your workflow needs purge / restore, that workflow needs human
-  intervention — the design is correct, not incomplete.
+- **Do not attempt to purge from agent code.** There is intentionally no programmatic
+  path to permanent deletion — if your workflow needs purge, that workflow needs human
+  intervention. Restore, by contrast, is freely available since v1.7.0
+  (`cerefox_restore_document` over MCP, `cerefox document restore` on the CLI), audited
+  like every other write.
 
 ### CLI delete-doc — interactive vs scripted
 

package/docs/guides/cli.md

@@ -351,10 +351,13 @@ cerefox document set-projects <doc-id> --clear
 
 | Flag | Type | Default | Description |
 |---|---|---|---|
+| `--reason <text>` | str | _none_ | Optional reason recorded on the restore audit entry (v1.7.0; needs schema 0.12.0). |
 | `--author TEXT` | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Identity recorded in the audit log. |
 | `--author-type [user\|agent]` | choice | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type. |
 
-Clears `deleted_at`, returning the document to search and `cerefox document list`, and writes a `restore` audit entry.
+Clears `deleted_at`, returning the document to search and `cerefox document list`, and writes a `restore` audit entry. Restoring a document that is not deleted (or was already restored by a concurrent writer) is a reported no-op.
+
+**MCP equivalent**: `cerefox_restore_document` (v1.7.0).
 
 ---
 
@@ -521,7 +524,7 @@ cerefox audit list --json --limit 1000 | jq 'select(.author_type == "agent")'
 
 ### `cerefox document delete`
 
-**Purpose**: **soft-delete** a document — moves it to trash, recoverable. The CLI cannot permanently delete or restore; see [Destructive operations and the trust model](access-paths.md#destructive-operations-and-the-trust-model) for the rationale.
+**Purpose**: **soft-delete** a document — moves it to trash, recoverable with `cerefox document restore`. The CLI cannot permanently purge; see [Destructive operations and the trust model](access-paths.md#destructive-operations-and-the-trust-model) for the rationale.
 
 **Synopsis**: `cerefox document delete [OPTIONS] DOCUMENT_ID`
 
@@ -530,7 +533,7 @@ cerefox audit list --json --limit 1000 | jq 'select(.author_type == "agent")'
 | Flag | Type | Default | Description |
 |---|---|---|---|
 | `--yes` | flag | off | Skip confirmation prompt. Required for non-interactive use (agents, scripts). |
-| `--reason <text>` | str | _none_ | Optional reason recorded on the delete audit entry. |
+| `--reason <text>` | str | _none_ | Optional reason recorded on the delete audit entry (v1.7.0; needs schema 0.12.0). |
 | `--author <name>` (`-a`) | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Identity recorded in the audit log. |
 | `--author-type <type>` | `user`\|`agent` | `CEREFOX_AUTHOR_TYPE` or `user` | Caller type, recorded in the audit log. |
 
@@ -544,7 +547,7 @@ cerefox audit list --json --limit 1000 | jq 'select(.author_type == "agent")'
 - Does NOT free database storage.
 - Versions, chunks, and audit entries remain intact under the trash.
 
-**Recovery**: a soft-deleted document can be restored OR permanently purged **only from the Cerefox web UI** (Trash view). These destructive / restorative actions are intentionally web-UI-only to require human-in-the-loop confirmation. See [`access-paths.md` → Destructive operations and the trust model](access-paths.md#destructive-operations-and-the-trust-model).
+**Recovery**: restore with `cerefox document restore`, the web UI Trash view, or `cerefox_restore_document` over MCP (v1.7.0). Permanent purge is **web-UI-only** — the one action requiring human-in-the-loop confirmation. A trashed document also refuses content updates (restore first). See [`access-paths.md` → Destructive operations and the trust model](access-paths.md#destructive-operations-and-the-trust-model).
 
 **Agent usage**:
 ```bash
@@ -664,7 +667,7 @@ cerefox config set relations_enabled true    # tools appear in every agent's lis
 cerefox config set relations_enabled false   # hidden again; no data removed
 ```
 
-Agents see 13 tools with the flag off and 16 with it on. See
+Agents see 15 tools with the flag off and 19 with it on. See
 [`configuration.md`](configuration.md) for the full runtime-config surface.
 
 ### `cerefox config list` / `cerefox config get` / `cerefox config set`
@@ -782,6 +785,9 @@ Every MCP parameter has an exact-name CLI flag (kebab-cased). Short forms exist
 | `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 --requestor <name>` |
+| `cerefox_set_document_metadata(document_id, metadata, replace, author)` | `cerefox document set-metadata <id> --set key=value` (also `--remove key`, `--json '<json>'`, `--replace`) |
+| `cerefox_delete_document(document_id, expected_content_hash, reason, author, requestor)` | `cerefox document delete <id> --reason <text> --author <a> --author-type <t> --yes` (confirms interactively instead of requiring the hash) |
+| `cerefox_restore_document(document_id, reason, author, requestor)` | `cerefox document restore <id> --reason <text> --author <a> --author-type <t>` |
 
 ## CLI ↔ MCP parity matrix
 
@@ -800,8 +806,8 @@ surface).
 | `document get` | `cerefox_get_document` | ✅ |
 | `document list` | `cerefox_metadata_search` (scope by `project_name` / metadata / time) | ✅ as of this change. Unscoped whole-KB listing has no MCP path by design (scope it) |
 | `document edit` (title / metadata in place) | — | 🔒 intentional: a human/web-parity convenience. Agents update title+metadata deterministically via `cerefox_ingest` (with `document_id`); a metadata-only edit isn't a needed agent primitive |
-| `document delete` (soft-delete) | — | 🔒 destructive; trust model keeps delete/restore on CLI + web only |
-| `document restore` | — | 🔒 trust model (CLI + web only) |
+| `document delete` (soft-delete) | `cerefox_delete_document` | ✅ v1.7.0 (#208). MCP requires the caller's read-hash; the CLI confirms interactively instead |
+| `document restore` | `cerefox_restore_document` | ✅ v1.7.0 (#210). Permanent purge remains web-UI-only |
 | `document version list` | `cerefox_list_versions` | ✅ |
 | `document version archive` / `unarchive` | — | 🔒 intentional: version-retention protection is exposed only to CLI + web (a maintenance concern, not an agent primitive) |
 | `document set-projects` | `cerefox_set_document_projects` | ✅ full-set replace of a document's project memberships (shared core; `--clear` to remove all) |

package/docs/guides/connect-agents.md

@@ -72,7 +72,7 @@ in the container.
 - **Easiest:** `cerefox-local configure-agent` wires it up (registers an MCP server named
   `cerefox-local` with Claude Code if the `claude` CLI is present, else prints the snippet).
 - **Manual:** point the client at `command: cerefox-local, args: ["mcp"]` (stdio). That proxies
-  to `cerefox mcp` in the container; the same 13 core tools, identical behavior to every other path.
+  to `cerefox mcp` in the container; the same 15 core tools, identical behavior to every other path.
 - The cloud paths above (remote Edge Function, GPT Actions) **do not apply** to a local-only
   install — there are no Edge Functions.
 
@@ -131,7 +131,7 @@ in the container.
 
 ### What it is
 
-The local Cerefox MCP server runs on your machine and exposes the same 13 core tools as the remote
+The local Cerefox MCP server runs on your machine and exposes the same 15 core tools as the remote
 Edge Function, communicating with clients over stdio.
 
 The local server ships as an npm package — **[`@cerefox/memory`](https://www.npmjs.com/package/@cerefox/memory)** — built with the official `@modelcontextprotocol/sdk`.
@@ -190,6 +190,10 @@ Once configured, every Path A client has these tools:
 |------|-------------|
 | `cerefox_search` | Hybrid (FTS + semantic) document-level search. Filter by `project_name` or `metadata_filter`. |
 | `cerefox_ingest` | Save a note or document to the knowledge base. Pass `document_id` to update by ID (deterministic); or `update_if_exists: true` to update by title match. Accepts optional `author` and `project_name`. |
+| `cerefox_insert` | Add text to a document without resending it (additive only — structurally cannot remove content) |
+| `cerefox_edit` | Change parts of a document: 1..n operations (`insert`/`replace_section`/`delete_section`/`rename_section`) applied atomically |
+| `cerefox_delete_document` | Soft-delete a document to the trash (requires the caller's read-hash; permanent purge is web-UI-only) |
+| `cerefox_restore_document` | Restore a soft-deleted document from the trash (audited inverse of delete) |
 | `cerefox_list_metadata_keys` | List all metadata keys in use across documents |
 | `cerefox_get_document` | Retrieve the full content of a document (current or archived version) |
 | `cerefox_list_versions` | List all archived versions of a document |
@@ -200,9 +204,13 @@ Once configured, every Path A client has these tools:
 | `cerefox_set_document_projects` | Set a document's project memberships to exactly the given list (destructive replace; metadata-only, no content change). Use `cerefox_ingest` with singular `project_name` for non-destructive "add". |
 | `cerefox_get_help` | Retrieve Cerefox conventions (the same content as `AGENT_QUICK_REFERENCE.md`) over MCP. Optional `topic` parameter does a case-insensitive H2 substring match. Call this whenever you are uncertain. |
 
-> All 13 core tools are available on both Path A (local and remote MCP) and Path B (GPT Actions
-> via dedicated Edge Functions, except `cerefox_get_help` which is MCP-only). MCP tools use
-> `project_name` (human-readable); primitive Edge Functions (Path B) use `project_id` (UUID).
+> All 15 core tools are available on Path A (local and remote MCP). Path B (GPT Actions via
+> dedicated Edge Functions) exposes the 8 primitive operations: search, ingest, metadata keys,
+> get-document, list-versions, audit log, metadata-search, and list-projects. The rest are
+> MCP-only: the partial-edit tools (`cerefox_insert`/`cerefox_edit`),
+> `cerefox_delete_document`/`cerefox_restore_document`, the metadata/project setters, and
+> `cerefox_get_help`. MCP tools use `project_name` (human-readable); primitive Edge
+> Functions (Path B) use `project_id` (UUID).
 
 ### Path A system prompt
 
@@ -226,7 +234,8 @@ For the full tool reference, search Cerefox for "How AI Agents Use Cerefox".
 After setup, ask your client:
 
 > "What tools do you have available?"
-> Expected: 13 tools listed (`cerefox_search`, `cerefox_ingest`, `cerefox_insert`, `cerefox_edit`, `cerefox_get_document`,
+> Expected: 15 tools listed (`cerefox_search`, `cerefox_ingest`, `cerefox_insert`, `cerefox_edit`,
+> `cerefox_delete_document`, `cerefox_restore_document`, `cerefox_get_document`,
 > `cerefox_list_versions`, `cerefox_list_projects`, `cerefox_list_metadata_keys`,
 > `cerefox_metadata_search`, `cerefox_set_document_projects`,
 > `cerefox_set_document_metadata`, `cerefox_get_audit_log`,
@@ -321,7 +330,7 @@ pick it up automatically.
 to primitive Edge Functions. This means each MCP tool call costs a single Edge Function
 invocation.
 
-A single HTTPS URL gives any remote-capable MCP client all 13 core tools with full hybrid
+A single HTTPS URL gives any remote-capable MCP client all 15 core tools with full hybrid
 search -- no Python, no `uv`, no local repository clone needed.
 
 **URL format:**
@@ -502,7 +511,7 @@ Replace `<your-project-ref>` with your Supabase project ref.
 **Step 3 — Verify:**
 
 Launch Codex and use the `/mcp` slash command to confirm the `cerefox` server is connected
-and all 13 tools are listed.
+and all 15 tools are listed.
 
 **Notes:**
 - `bearer_token_env_var` is the **name** of the env var (e.g. `"CEREFOX_ACCESS_TOKEN"`), not the
@@ -588,7 +597,11 @@ When UPDATING an existing document, first call getDocument and note its
 content_hash, then pass it as expected_content_hash on ingestNote. If you get a
 409 conflict, the document changed underneath you: call getDocument again, merge
 your changes into the latest content, and retry with the new hash — never
-overwrite blindly.
+overwrite blindly. A 409 with error "document_deleted" means the target is in
+the trash: it must be restored by the user before updating. A 422 with error
+"unresolved_links" means the content links document id(s) that do not exist —
+you mangled a UUID; re-check each [Text](uuid) link against its source and
+resend, or wrap example ids in backticks. Do not retry either unchanged.
 ```
 
 ### Path B verification
@@ -625,7 +638,7 @@ In the action editor, paste this schema (replace `<your-project-ref>`):
 openapi: 3.1.0
 info:
   title: Cerefox Knowledge Base
-  version: 3.1.0
+  version: 3.2.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -807,9 +820,20 @@ paths:
             with its content_hash.
         '409':
           description: >
-            Conflict — the document changed since it was read. Call getDocument
-            for the latest content + content_hash, merge your changes, and
-            retry with the new hash. Do not overwrite blindly.
+            Conflict. Either the document changed since it was read (call
+            getDocument for the latest content + content_hash, merge your
+            changes, and retry with the new hash — do not overwrite blindly),
+            or the target document is soft-deleted (error
+            "document_deleted") — restore it first, then retry, or create a
+            new document.
+        '422':
+          description: >
+            Unresolved document links (error "unresolved_links") — the content
+            contains [Text](uuid) links to document ids that do not exist,
+            almost always mangled UUIDs. Re-read the source each link was
+            copied from, correct the id(s), and resend; do not retry
+            unchanged. Deliberate example ids belong in code formatting
+            (backticks), which is not validated.
   /cerefox-metadata:
     post:
       operationId: listMetadataKeys
@@ -1151,7 +1175,7 @@ user + `CEREFOX_OAUTH_OWNER_ID` pin, and register the Claude OAuth App
    Client Secret from the pre-registered OAuth App (setup-supabase Step 7d).
 5. Save. Claude runs the OAuth flow → redirects you to the **Cerefox consent page** (sign
    in with the owner email/password from Step 7c, then **Allow**) → returns to Claude. The
-   connector shows as connected with **13 tools** (16 if you have enabled document relations). (If you've approved before, Supabase
+   connector shows as connected with **15 tools** (19 if you have enabled document relations). (If you've approved before, Supabase
    auto-consents and the page just flashes through — that's expected.)
 6. **Mobile**: connectors are account-level, so `CerefoxMCP` appears in the Claude mobile
    app automatically — run one search from your phone to confirm.
@@ -1253,7 +1277,7 @@ The agent docs are written around MCP tool names. **CLI flag names match MCP par
 | `cerefox_metadata_search` | `cerefox metadata search --metadata-filter '<json>' --project-name <n> --requestor <name>` |
 | `cerefox_get_audit_log` | `cerefox audit list --document-id <id> --author <a> --operation <op> --since <iso> --until <iso> --limit N --json --requestor <name>` |
 
-> CLI verbs with no MCP equivalent: `cerefox document edit`, `cerefox document restore`, `cerefox project create` / `cerefox project edit`, `cerefox config list`.
+> CLI verbs with no MCP equivalent: `cerefox document edit`, `cerefox project create` / `cerefox project edit`, `cerefox config list`.
 
 ### Path C verification prompts
 
@@ -1272,8 +1296,8 @@ After pointing your agent at the repo, ask it:
 
 - **Privilege level**: the CLI uses the **service-role key** (`CEREFOX_SUPABASE_KEY`), which bypasses Row Level Security. An agent with Bash access has the same full read/write power you do. Only enable Path C for agents you trust to act on your behalf — the same trust level you'd grant Cursor/Claude Code for editing your source code.
 - **Audit attribution**: Path C records `access_path = "cli"` in usage logs, distinct from `"local-mcp"` / `"remote-mcp"`. **Agents must set `--author <name> --author-type agent` on writes and `--requestor <name>` on reads** (or rely on `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` env vars). Without these flags, writes attribute to `"unknown"` / `"user"`, which under-reports agent activity. See the 2026-05-18 Decision Log Q2 entry for the design rationale (`author_type` is caller-declared on ambiguous channels — CLI and Edge Functions — but `access_path` is always derived from the code layer).
-- **Soft-delete is reachable; purge and restore are not** — by design. `cerefox document delete` is exposed on the CLI and sends documents to trash with an audit entry. **Permanent purge** (irreversible) and **restore from trash** (un-doing a destructive action) are intentionally web-UI-only and require human-in-the-loop confirmation. If an agent on Path C decides to delete content, it should surface that to the user explicitly so they can review and either restore or commit. See [`access-paths.md` → Destructive operations and the trust model](access-paths.md#destructive-operations-and-the-trust-model) for the full rationale and contributor guidance.
-- **Cross-doc links in content you ingest** become clickable when the user views them in the Cerefox web UI. Author them as `[Text](uuid)` (most stable), `[Text](docs/path.md)` (repo files), or `[Text](<Title With Spaces>)` (angle-bracket form — bare spaces break markdown). See [`AGENT_GUIDE.md` → "Writing linkable content"](../../AGENT_GUIDE.md#writing-linkable-content) for the full set of rules.
+- **Soft-delete and restore are reachable; permanent purge is not** — by design. `cerefox document delete` / `cerefox document restore` on the CLI, `cerefox_delete_document` / `cerefox_restore_document` over MCP (v1.7.0, #208/#210): both audited with author attribution. **Permanent purge** (irreversible) stays web-UI-only with human-in-the-loop confirmation. If an agent deletes or restores content, it should surface that to the user explicitly so they can follow it in the audit trail. See [`access-paths.md` → Destructive operations and the trust model](access-paths.md#destructive-operations-and-the-trust-model) for the full rationale and contributor guidance.
+- **Cross-doc links in content you ingest** become clickable when the user views them in the Cerefox web UI. **Always author them as `[Text](uuid)`** — the server validates these on every write (v1.7.0) and rejects links to nonexistent ids, which catches mangled UUIDs at write time. `[Text](docs/path.md)` exists for repo-ingested files; do not write title-based links (fragile, and `AGENT_GUIDE.md` says never in agent-authored content). See [`AGENT_GUIDE.md` → "Writing linkable content"](../../AGENT_GUIDE.md#writing-linkable-content) for the full set of rules.
 - **CLI install per machine**: the agent needs the `cerefox` binary installed (`npm install -g @cerefox/memory`) with a resolvable `.env`. If you skip the local install entirely, Path A-Remote or Path B is the only option.
 - **No sandboxing beyond the agent's existing Bash sandbox**: the CLI is just shell. If your agent's tool framework restricts which commands run, allowlist `cerefox …` explicitly.
 

package/docs/guides/operational-cost.md

@@ -74,7 +74,7 @@ paths go through **Edge Functions**, which the free tier caps at 500,000/month:
 500K/month is generous for a single human-driven agent. But **automated or
 high-frequency agents on the remote path** can approach it. The lever: point those
 agents at the **local stdio MCP server** (`cerefox mcp`) instead of the remote Edge
-Function — it exposes the identical 13 core tools (plus the 4 relation tools when enabled), talks to the Data API directly, and
+Function — it exposes the identical 15 core tools (plus the 4 relation tools when enabled), talks to the Data API directly, and
 costs **zero** Edge Function invocations (bonus: lower latency, and it works offline
 against a reachable database). If you do exceed the free EF quota, Supabase's Pro
 plan ($25/mo, 2M invocations included) is the next step.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Cerefox — user-owned shared memory for AI agents. CLI + stdio MCP server + web UI + ingestion for a knowledge base on your own Supabase project (or fully self-hosted with Cerefox Local).",
   "license": "Apache-2.0",
   "homepage": "https://github.com/fstamatelopoulos/cerefox",