@cerefox/memory 1.6.1 → 1.7.1

package/docs/guides/cli.md

@@ -226,6 +226,12 @@ cerefox document list [OPTIONS]
 
 **Purpose**: update a document's title and/or metadata in place, without re-ingesting content.
 
+> **v1.7.1 (#212)**: a title-only edit no longer writes `metadata` at all, and
+> the command refuses to patch a document whose stored metadata is not a JSON
+> object (a legacy state older writes could create) instead of destroying it —
+> repair such a row with `cerefox document set-metadata <id> --replace --json
+> '<object>'`. `cerefox doctor` lists any rows in that state.
+
 **Synopsis**:
 ```
 cerefox document edit [OPTIONS] DOCUMENT_ID
@@ -341,6 +347,20 @@ cerefox document set-projects <doc-id> --clear
 
 ---
 
+### `cerefox document dead-links`
+
+**Purpose**: whole-KB sweep for `[Text](uuid)` links whose target document no longer exists (phase 2 of link integrity, #214; v1.7.1, needs schema 0.12.2).
+
+**Synopsis**: `cerefox document dead-links [--json]`
+
+The write-time guard (v1.7.0) validates only links a write *introduces* — deliberately, so a target purged after linking cannot make its linkers unwritable. This command finds those legacy dead links on demand. A trashed target still exists and is **not** reported; trashed **linker** documents are also excluded (inert until restored — a restore re-enters them into the next sweep). Full chunk scan server-side (one RPC call); run on demand, not part of `doctor`.
+
+**Fix each hit** by editing the linking document: correct the id, remove the link, or backtick it as an example. Full linking overview: [`linking.md`](linking.md).
+
+**MCP equivalent**: none (maintenance verb).
+
+---
+
 ### `cerefox document restore`
 
 **Purpose**: restore a soft-deleted (trashed) document back to active.
@@ -351,10 +371,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 +544,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 +553,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 +567,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 +687,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 +805,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 +826,9 @@ 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 dead-links` | — | 🔒 intentional: a maintenance sweep for the operator (v1.7.1, #214 phase 2); agents encounter dead links through the write-time guard instead |
+| `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.1",
   "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",