@cerefox/memory 1.8.0 → 1.9.1

package/dist/server-assets/db/rpcs.sql

@@ -598,63 +598,18 @@ AS $$
     GROUP BY d.id, d.title, d.source, d.metadata;
 $$;
 
--- ── cerefox_save_note ─────────────────────────────────────────────────────────
--- Agent write tool: create a minimal document record for a short text note.
--- Embedding and chunking are NOT done server-side in V1 — the Python ingestion
--- pipeline should be used for full ingest.  This RPC is intended for quick
--- one-shot note capture from AI agents that want to store something immediately.
+-- ── retired V1 RPC (dropped in 0.14.0) ──────────────────────────────────────
+-- cerefox_save_note was a Python-era V1 tool with zero callers since the TS
+-- rewrite — nothing in the CLI, MCP tools, Edge Functions, web app, OR the
+-- SQL layer ever called it. The DROP stays here so re-applying rpcs.sql also
+-- cleans long-lived databases (migration 0028 carries the same).
 --
--- Parameters:
---   p_title       : Note title (required)
---   p_content     : Markdown content (required)
---   p_source      : Origin label, e.g. 'agent' (default: 'agent')
---   p_project_id  : Optional project UUID (assigns to a single project)
---   p_metadata    : Optional JSONB metadata (e.g. agent name, session id)
---
--- Returns: the created document row (id, title, created_at)
-
-CREATE OR REPLACE FUNCTION cerefox_save_note(
-    p_title       TEXT,
-    p_content     TEXT,
-    p_source      TEXT    DEFAULT 'agent',
-    p_project_id  UUID    DEFAULT NULL,
-    p_metadata    JSONB   DEFAULT '{}'::JSONB
-)
-RETURNS TABLE (
-    id          UUID,
-    title       TEXT,
-    created_at  TIMESTAMPTZ
-)
-LANGUAGE plpgsql
-SECURITY DEFINER
-SET search_path = public, pg_catalog
-AS $$
-DECLARE
-    v_hash TEXT;
-    v_doc_id UUID;
-    v_created_at TIMESTAMPTZ;
-BEGIN
-    -- Compute content hash to support deduplication on the caller side.
-    v_hash := encode(sha256(p_content::BYTEA), 'hex');
-
-    INSERT INTO cerefox_documents (
-        title, source, content_hash, metadata, chunk_count, total_chars
-    ) VALUES (
-        p_title, p_source, v_hash, p_metadata, 0, length(p_content)
-    )
-    RETURNING cerefox_documents.id, cerefox_documents.created_at
-    INTO v_doc_id, v_created_at;
-
-    -- Assign to project if provided (many-to-many junction).
-    IF p_project_id IS NOT NULL THEN
-        INSERT INTO cerefox_document_projects (document_id, project_id)
-        VALUES (v_doc_id, p_project_id)
-        ON CONFLICT DO NOTHING;
-    END IF;
-
-    RETURN QUERY SELECT v_doc_id, p_title, v_created_at;
-END;
-$$;
+-- cerefox_context_expand (below) looked like the same class but is NOT dead:
+-- cerefox_search_docs calls it for small-to-big retrieval. TS-side grep alone
+-- cannot establish an RPC is unused — SQL functions have SQL callers. It was
+-- briefly slated for removal in this release; the sandbox validation caught
+-- the breakage (42883 from search_docs) before anything shipped.
+DROP FUNCTION IF EXISTS cerefox_save_note(TEXT, TEXT, TEXT, UUID, JSONB);
 
 -- ── cerefox_context_expand ────────────────────────────────────────────────────
 -- Small-to-big retrieval: given a set of chunk IDs from a search result,
@@ -2020,6 +1975,216 @@ AS $$
     ORDER BY p.name;
 $$;
 
+-- ── Project write RPCs (0.14.0, #147/#219) ──────────────────────────────────
+-- Project writes carried no business logic until the audit trail arrived —
+-- then every caller (CLI, web, shared helpers, ingestion pipeline, the ingest
+-- EF) grew its own follow-up cerefox_create_audit_entry call: non-atomic,
+-- warn-on-failure, and empirically forgettable (review round 1 caught two
+-- unwired paths in the release that introduced the convention). Single
+-- Implementation Principle applies the moment a write has a side effect: the
+-- write AND its audit entry live here, in one transaction. Callers are thin.
+
+-- Return shape changed in review round 4 (full row: the web routes were
+-- re-reading the row the RPC had just written). A changed RETURNS TABLE
+-- cannot go through CREATE OR REPLACE — drop first (house pattern).
+DROP FUNCTION IF EXISTS cerefox_create_project(TEXT, TEXT, TEXT, TEXT, TEXT);
+
+CREATE FUNCTION cerefox_create_project(
+    p_name        TEXT,
+    p_description TEXT DEFAULT '',
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'user',
+    -- 'error'  → explicit creation (CLI/web): duplicate name raises.
+    -- 'return' → get-or-create (implicit creation during document
+    --            assignment): an existing project is returned untouched and
+    --            NOT audited — only an actual create writes an entry.
+    p_if_exists   TEXT DEFAULT 'error'
+)
+RETURNS TABLE (
+    project_id          UUID,
+    project_name        TEXT,
+    project_description TEXT,
+    created             BOOLEAN,
+    created_at          TIMESTAMPTZ,
+    updated_at          TIMESTAMPTZ
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_row cerefox_projects%ROWTYPE;
+BEGIN
+    IF NULLIF(BTRIM(p_name), '') IS NULL THEN
+        RAISE EXCEPTION 'Project name is required' USING ERRCODE = '22023';
+    END IF;
+    IF p_if_exists NOT IN ('error', 'return') THEN
+        RAISE EXCEPTION 'p_if_exists must be ''error'' or ''return''' USING ERRCODE = '22023';
+    END IF;
+
+    IF p_if_exists = 'return' THEN
+        -- Case-insensitive, matching the name resolution the assignment
+        -- paths have always used. (A case-colliding pair created directly is
+        -- pre-existing behavior: the unique constraint is exact-match; this
+        -- resolver returns the first match.)
+        SELECT p.* INTO v_row
+        FROM cerefox_projects p WHERE lower(p.name) = lower(BTRIM(p_name)) LIMIT 1;
+        IF v_row.id IS NOT NULL THEN
+            RETURN QUERY SELECT v_row.id, v_row.name, v_row.description, FALSE,
+                                v_row.created_at, v_row.updated_at;
+            RETURN;
+        END IF;
+    END IF;
+
+    BEGIN
+        INSERT INTO cerefox_projects (name, description)
+        VALUES (BTRIM(p_name), COALESCE(p_description, ''))
+        RETURNING * INTO v_row;
+    EXCEPTION WHEN unique_violation THEN
+        -- TOCTOU (round 4): a concurrent create won the race between the
+        -- resolve above and this insert. In 'return' mode that is exactly
+        -- the get-or-create contract — hand back the winner, no audit entry
+        -- (this call created nothing). In 'error' mode a duplicate is the
+        -- caller's error, exactly as if there had been no race.
+        IF p_if_exists = 'return' THEN
+            SELECT p.* INTO v_row
+            FROM cerefox_projects p WHERE lower(p.name) = lower(BTRIM(p_name)) LIMIT 1;
+            IF v_row.id IS NOT NULL THEN
+                RETURN QUERY SELECT v_row.id, v_row.name, v_row.description, FALSE,
+                                    v_row.created_at, v_row.updated_at;
+                RETURN;
+            END IF;
+        END IF;
+        RAISE;
+    END;
+
+    PERFORM cerefox_create_audit_entry(
+        p_operation   := 'project-create',
+        p_author      := p_author,
+        p_author_type := p_author_type,
+        p_description := 'Project ''' || v_row.name || ''' created'
+            || CASE WHEN p_if_exists = 'return'
+                    THEN ' implicitly (document assignment)' ELSE '' END
+    );
+    RETURN QUERY SELECT v_row.id, v_row.name, v_row.description, TRUE,
+                        v_row.created_at, v_row.updated_at;
+END;
+$$;
+
+DROP FUNCTION IF EXISTS cerefox_update_project(UUID, TEXT, TEXT, TEXT, TEXT);
+
+CREATE FUNCTION cerefox_update_project(
+    p_project_id  UUID,
+    -- NULL = keep the current value (the #191/#204 "NULL means not provided"
+    -- convention). An explicit empty name is rejected.
+    p_name        TEXT DEFAULT NULL,
+    p_description TEXT DEFAULT NULL,
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'user'
+)
+RETURNS TABLE (
+    project_id          UUID,
+    project_name        TEXT,
+    project_description TEXT,
+    created_at          TIMESTAMPTZ,
+    updated_at          TIMESTAMPTZ
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_old  cerefox_projects%ROWTYPE;
+    v_new  cerefox_projects%ROWTYPE;
+    v_changes TEXT[] := '{}';
+BEGIN
+    IF p_name IS NULL AND p_description IS NULL THEN
+        RAISE EXCEPTION 'Nothing to update: pass p_name and/or p_description' USING ERRCODE = '22023';
+    END IF;
+    IF p_name IS NOT NULL AND NULLIF(BTRIM(p_name), '') IS NULL THEN
+        RAISE EXCEPTION 'Project name cannot be empty' USING ERRCODE = '22023';
+    END IF;
+
+    SELECT p.* INTO v_old FROM cerefox_projects p WHERE p.id = p_project_id FOR UPDATE;
+    IF NOT FOUND THEN
+        RAISE EXCEPTION 'Project not found: %', p_project_id USING ERRCODE = '22023';
+    END IF;
+
+    UPDATE cerefox_projects SET
+        name        = COALESCE(BTRIM(p_name), name),
+        description = COALESCE(p_description, description),
+        updated_at  = NOW()
+    WHERE id = p_project_id
+    RETURNING * INTO v_new;
+
+    -- The trail records what actually changed, not which arguments arrived.
+    -- array_append, NOT `||`: with an untyped string literal on the right,
+    -- `TEXT[] || 'literal'` resolves to the array||array overload and dies
+    -- with `malformed array literal` — found LIVE on staging (v1.9.0; every
+    -- description-only edit failed; the rename branch only survived because
+    -- its parenthesized concatenation is typed TEXT).
+    IF v_new.name <> v_old.name THEN
+        v_changes := array_append(v_changes, 'renamed ''' || v_old.name || ''' → ''' || v_new.name || '''');
+    END IF;
+    IF COALESCE(v_new.description, '') <> COALESCE(v_old.description, '') THEN
+        v_changes := array_append(v_changes, 'description changed');
+    END IF;
+
+    PERFORM cerefox_create_audit_entry(
+        p_operation   := 'project-edit',
+        p_author      := p_author,
+        p_author_type := p_author_type,
+        p_description := 'Project ''' || v_new.name || ''' edited ('
+            || COALESCE(NULLIF(array_to_string(v_changes, '; '), ''), 'no-op') || ')'
+    );
+    RETURN QUERY SELECT v_new.id, v_new.name, v_new.description,
+                        v_new.created_at, v_new.updated_at;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION cerefox_delete_project(
+    p_project_id  UUID,
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'user'
+)
+RETURNS TABLE (deleted BOOLEAN, project_name TEXT)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_catalog
+AS $$
+DECLARE
+    v_name  TEXT;
+    v_links INT;
+BEGIN
+    -- Lock + read name and link count in one pass: the memberships CASCADE
+    -- with the row, so the count must be read pre-DELETE — but the zero-row
+    -- path (repeat delete) pays for nothing (round 4).
+    SELECT p.name, (SELECT COUNT(*) FROM cerefox_document_projects dp
+                    WHERE dp.project_id = p.id)
+    INTO v_name, v_links
+    FROM cerefox_projects p WHERE p.id = p_project_id FOR UPDATE;
+
+    IF v_name IS NULL THEN
+        -- Zero rows: nothing happened, so nothing is audited — the trail
+        -- must never assert an event that did not occur. Callers decide
+        -- whether "already gone" is an error (CLI) or a 404 (web).
+        RETURN QUERY SELECT FALSE, NULL::TEXT;
+        RETURN;
+    END IF;
+
+    DELETE FROM cerefox_projects WHERE id = p_project_id;
+
+    PERFORM cerefox_create_audit_entry(
+        p_operation   := 'project-delete',
+        p_author      := p_author,
+        p_author_type := p_author_type,
+        p_description := 'Project ''' || v_name || ''' deleted ('
+            || v_links || ' document link(s) removed)'
+    );
+    RETURN QUERY SELECT TRUE, v_name;
+END;
+$$;
+
 -- ── cerefox_metadata_search ──────────────────────────────────────────────────
 -- Query documents by metadata key-value criteria without a text search term.
 -- Uses JSONB containment (@>) which leverages the existing GIN index on
@@ -2442,7 +2607,23 @@ BEGIN
 END;
 $$;
 
-CREATE OR REPLACE FUNCTION cerefox_set_config(p_key TEXT, p_value TEXT)
+-- The 2-arg signature grew to 4 in 0.14.0 (audit trail). CREATE OR REPLACE
+-- never removes the old overload, and a surviving one makes named calls
+-- ambiguous under PostgREST (PGRST203) — the v1.7.0 purge/restore lesson.
+-- Both signatures dropped (house pattern, cf. delete_document): the old one
+-- so it cannot linger, the current one so re-applying this file stays
+-- idempotent after migration 0028 has already created it.
+DROP FUNCTION IF EXISTS cerefox_set_config(TEXT, TEXT);
+DROP FUNCTION IF EXISTS cerefox_set_config(TEXT, TEXT, TEXT, TEXT);
+
+CREATE FUNCTION cerefox_set_config(
+    p_key         TEXT,
+    p_value       TEXT,
+    -- 0.14.0: config changes are governance decisions ("who turned retention
+    -- off, and when?") and belong in the audit trail like any other write.
+    p_author      TEXT DEFAULT 'unknown',
+    p_author_type TEXT DEFAULT 'user'
+)
 RETURNS VOID
 LANGUAGE plpgsql
 SECURITY DEFINER
@@ -2467,14 +2648,30 @@ DECLARE
         -- point. A signal in the write's response, never a refusal.
         'document_size_warning_chars'
     ];
+    v_old TEXT;
 BEGIN
     IF NOT (p_key = ANY(v_allowed)) THEN
         RAISE EXCEPTION 'Unknown config key: %. Allowed keys: %', p_key, v_allowed;
     END IF;
 
+    SELECT value INTO v_old FROM cerefox_config WHERE key = p_key;
+
     INSERT INTO cerefox_config (key, value)
     VALUES (p_key, p_value)
     ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value;
+
+    -- Same-transaction audit entry (document_id NULL — a store-level write).
+    -- A no-op set (same value) is still recorded: "checked and confirmed" is
+    -- itself a governance action, and skipping it would make the trail lie by
+    -- omission when someone re-asserts a setting.
+    PERFORM cerefox_create_audit_entry(
+        p_operation   := 'config-change',
+        p_author      := p_author,
+        p_author_type := p_author_type,
+        p_description := 'config: ' || p_key || ': '
+            || COALESCE('''' || v_old || '''', '(unset)')
+            || ' → ''' || p_value || ''''
+    );
 END;
 $$;
 
@@ -2820,7 +3017,7 @@ AS $$
     -- 0.11.0 supersedes 0.10.6 (v1.2.1, #191): this branch carries that fix plus
     -- the partial-edit surface, and both migrations (0019, 0020) are in the
     -- sequence, so a store deploying this gets everything from both lines.
-    SELECT '0.13.0'::TEXT;
+    SELECT '0.14.1'::TEXT;
 $$;
 
 -- ── cerefox_find_dead_links ──────────────────────────────────────────────────

package/dist/server-assets/db/schema.sql

@@ -5,7 +5,7 @@
 -- Requires extensions: vector (pgvector), uuid-ossp
 -- These are enabled at the top of db_deploy.py before this file is applied.
 --
--- @version: 0.13.0
+-- @version: 0.14.1
 -- The `@version` marker above is read by the schema-version-mismatch banner
 -- (see /api/v1/schema-version). Bump it whenever schema.sql OR rpcs.sql
 -- changes in a way that requires `cerefox server deploy` to be re-run —
@@ -140,7 +140,13 @@ CREATE TABLE IF NOT EXISTS cerefox_audit_log (
                       'insert', 'replace-section', 'delete-section',
                       -- iteration 35 (#197): renaming a heading is neither a
                       -- rewrite nor a removal, and the trail should say so.
-                      'rename-section')
+                      'rename-section',
+                      -- 0.14.0 (iteration 38, #147): store-level writes join the
+                      -- trail. These entries carry document_id NULL — like the
+                      -- rows a purge cascade orphans, so every reader already
+                      -- tolerates them.
+                      'config-change', 'project-create', 'project-edit',
+                      'project-delete')
     ),
     CONSTRAINT cerefox_audit_log_author_type_check CHECK (author_type IN ('user', 'agent'))
 );

package/dist/server-assets/supabase/functions/cerefox-ingest/index.ts

@@ -3,6 +3,10 @@ import { createClient } from "jsr:@supabase/supabase-js@2";
 import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/index.ts";
 import { efAuthGate } from "../../../_shared/ef-auth/index.ts";
 import { capEmbeddingInput } from "../../../_shared/embeddings/index.ts";
+import {
+  ensureDocumentInProject,
+  setDocumentProjectsByName,
+} from "../../../_shared/mcp-tools/_projects.ts";
 import {
   chunkMarkdown,
   embeddingInputFor,
@@ -220,97 +224,10 @@ async function sha256hex(text: string): Promise<string> {
 //
 // Used by both update branches AND the create path so resolution is consistent.
 
-// deno-lint-ignore no-explicit-any
-async function ensureDocumentInProject(
-  // deno-lint-ignore no-explicit-any
-  supabase: any,
-  documentId: string,
-  projectName: string,
-): Promise<string | null> {
-  // Resolve project name → id (look up; create if absent).
-  let projectId: string | null = null;
-  const { data: proj } = await supabase
-    .from("cerefox_projects")
-    .select("id")
-    .ilike("name", projectName)
-    .limit(1);
-  if (proj?.length) {
-    projectId = proj[0].id;
-  } else {
-    const { data: newProj } = await supabase
-      .from("cerefox_projects")
-      .insert({ name: projectName })
-      .select("id");
-    projectId = newProj?.[0]?.id ?? null;
-  }
-  if (!projectId) return null;
-
-  // Check membership; INSERT only if missing. PRIMARY KEY (document_id, project_id)
-  // guarantees uniqueness, so this is safe under concurrent calls (worst case:
-  // one of two concurrent inserts fails with 23505 unique_violation — we log
-  // and treat as "already a member"; outcome is identical).
-  const { data: existing } = await supabase
-    .from("cerefox_document_projects")
-    .select("document_id")
-    .eq("document_id", documentId)
-    .eq("project_id", projectId)
-    .limit(1);
-  if (existing?.length) return projectId;  // Already a member — non-destructive
-
-  const { error: insertErr } = await supabase
-    .from("cerefox_document_projects")
-    .insert({ document_id: documentId, project_id: projectId });
-  if (insertErr && !String(insertErr.message ?? "").includes("duplicate key")) {
-    console.warn("ensureDocumentInProject: insert failed", insertErr);
-  }
-  return projectId;
-}
-
-// ── Destructive set-the-full-list helper (project_names list form) ─────────
-//
-// Resolves each name to a project_id (creating if absent), then REPLACES the
-// document's project memberships with exactly that set. Used by the
-// project_names: string[] form on cerefox_ingest (full-set semantics).
-//
-// Empty list = remove from all projects.
-
-// deno-lint-ignore no-explicit-any
-async function setDocumentProjectsByName(
-  // deno-lint-ignore no-explicit-any
-  supabase: any,
-  documentId: string,
-  projectNames: string[],
-): Promise<string[]> {
-  const projectIds: string[] = [];
-  for (const name of projectNames) {
-    if (!name) continue;
-    const { data: proj } = await supabase
-      .from("cerefox_projects")
-      .select("id")
-      .ilike("name", name)
-      .limit(1);
-    if (proj?.length) {
-      projectIds.push(proj[0].id);
-    } else {
-      const { data: newProj } = await supabase
-        .from("cerefox_projects")
-        .insert({ name })
-        .select("id");
-      if (newProj?.[0]?.id) projectIds.push(newProj[0].id);
-    }
-  }
-
-  // DELETE-then-INSERT replace (matches Python assign_document_projects).
-  await supabase
-    .from("cerefox_document_projects")
-    .delete()
-    .eq("document_id", documentId);
-  if (projectIds.length > 0) {
-    const rows = projectIds.map((pid) => ({ document_id: documentId, project_id: pid }));
-    await supabase.from("cerefox_document_projects").insert(rows);
-  }
-  return projectIds;
-}
+// Project resolution + membership helpers are the SHARED implementations
+// (_shared/mcp-tools/_projects.ts) — the EF carried textual clones until
+// v1.9.0, which is exactly how forks drift (round-3 review). Both route
+// project creation through cerefox_create_project (audits in-transaction).
 
 // ── Main handler ───────────────────────────────────────────────────────────
 
@@ -535,9 +452,9 @@ Deno.serve(async (req: Request) => {
     // - project_names (list) → destructive replace (full-set semantics)
     // - project_name (singular) → non-destructive add (only if project_names absent)
     if (project_names !== null) {
-      await setDocumentProjectsByName(supabase, existingDoc.id, project_names);
+      await setDocumentProjectsByName(supabase, existingDoc.id, project_names, { author, authorType: author_type });
     } else if (project_name) {
-      await ensureDocumentInProject(supabase, existingDoc.id, project_name);
+      await ensureDocumentInProject(supabase, existingDoc.id, project_name, { author, authorType: author_type });
     }
 
     const note = update_if_exists ? undefined : "update_if_exists flag was overridden by document_id";
@@ -658,9 +575,9 @@ Deno.serve(async (req: Request) => {
       // - project_names (list) → destructive replace (full-set semantics)
       // - project_name (singular) → non-destructive add (only if project_names absent)
       if (project_names !== null) {
-        await setDocumentProjectsByName(supabase, existingDoc.id, project_names);
+        await setDocumentProjectsByName(supabase, existingDoc.id, project_names, { author, authorType: author_type });
       } else if (project_name) {
-        await ensureDocumentInProject(supabase, existingDoc.id, project_name);
+        await ensureDocumentInProject(supabase, existingDoc.id, project_name, { author, authorType: author_type });
       }
 
       return new Response(
@@ -759,9 +676,9 @@ Deno.serve(async (req: Request) => {
   // - project_name (singular) → assign one via the non-destructive helper
   let projectId: string | null = null;
   if (project_names !== null && project_names.length > 0) {
-    await setDocumentProjectsByName(supabase, documentId, project_names);
+    await setDocumentProjectsByName(supabase, documentId, project_names, { author, authorType: author_type });
   } else if (project_name) {
-    projectId = await ensureDocumentInProject(supabase, documentId, project_name);
+    projectId = await ensureDocumentInProject(supabase, documentId, project_name, { author, authorType: author_type });
   }
 
   // Fire-and-forget usage logging for ingest

package/docs/guides/cli.md

@@ -453,6 +453,8 @@ cerefox project delete [OPTIONS] PROJECT
 | `--description TEXT` | str | _none_ | Project description (`create` / `edit`). |
 | `--name TEXT` | str | _unchanged_ | New name (`edit`). |
 | `-y, --yes` | flag | off | Skip confirmation (`delete`; required for non-interactive use). |
+| `-a, --author TEXT` | str | `CEREFOX_AUTHOR_NAME` or `unknown` | Identity recorded in the audit log (v1.9.0 — project writes are audited in-transaction by the server). |
+| `--author-type TEXT` | user\|agent | `user` | Recorded alongside the author. |
 
 **Examples**:
 ```bash
@@ -461,6 +463,10 @@ cerefox project edit research --name research-archive
 cerefox project delete research-archive --yes
 ```
 
+Since v1.9.0 every project mutation is recorded in the audit log by the
+server itself (`project-create` / `project-edit` / `project-delete`), with
+the audit entry written in the same transaction as the change.
+
 ---
 
 ### `cerefox metadata keys`
@@ -519,7 +525,7 @@ cerefox audit list [OPTIONS]
 |---|---|---|---|
 | `--document-id TEXT` | UUID | _none_ | Filter to a single document. |
 | `--author TEXT` | str | _none_ | Filter by author name (exact match). |
-| `--operation [create\|update-content\|update-metadata\|delete\|status-change\|archive\|unarchive\|restore]` | choice | _none_ | Filter by operation type. |
+| `--operation TEXT` | choice | _none_ | Filter by operation type: `create`, `update-content`, `update-metadata`, `insert`, `replace-section`, `delete-section`, `rename-section`, `delete`, `restore`, `status-change`, `archive`, `unarchive`, `config-change`, `project-create`, `project-edit`, `project-delete`. |
 | `--since TEXT` | ISO-8601 | _none_ | Lower bound on `created_at`. |
 | `--until TEXT` | ISO-8601 | _none_ | Upper bound on `created_at`. |
 | `--limit INTEGER` | int | `50` | Max rows. |
@@ -698,9 +704,14 @@ Agents see 15 tools with the flag off and 19 with it on. See
 ```
 cerefox config list           # all current key/value pairs
 cerefox config get KEY
-cerefox config set KEY VALUE
+cerefox config set KEY VALUE [--author NAME] [--author-type user|agent]
 ```
 
+Since v1.9.0 every `config set` is recorded in the audit log by the server
+itself (`config-change`, with the old → new value), in the same transaction
+as the write — pass `--author` (or set `CEREFOX_AUTHOR_NAME`) so the entry
+is attributed; it records `unknown` otherwise, with a warning.
+
 Used for toggling features at runtime without a redeploy — see the "Decision Log Q1 Part 2 — usage tracking opt-in" entry (stored in the Cerefox knowledge base).
 
 ---

package/docs/guides/connect-agents.md

@@ -638,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.2.0
+  version: 3.3.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -934,7 +934,9 @@ paths:
                   type: string
                   description: >
                     Filter by operation type: create, update-content, update-metadata,
-                    delete, status-change, archive, unarchive (optional)
+                    insert, replace-section, delete-section, rename-section, delete,
+                    restore, status-change, archive, unarchive, config-change,
+                    project-create, project-edit, project-delete (optional)
                 since:
                   type: string
                   description: ISO timestamp lower bound for temporal queries (optional)
@@ -1490,23 +1492,6 @@ neighbours** (±`p_window_size` chunks within the same document).
 Returns: `chunk_id`, `document_id`, `chunk_index`, `title`, `content`, `heading_path`,
 `heading_level`, `doc_title`, `is_seed` (TRUE for the original seed chunks)
 
-#### `cerefox_save_note`
-
-Create a document record directly. The note is stored but **not embedded** — use `cerefox-ingest`
-Edge Function instead for notes that need to be immediately searchable.
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `p_title` | TEXT | required | Note title |
-| `p_content` | TEXT | required | Markdown content |
-| `p_source` | TEXT | `'agent'` | Origin label |
-| `p_project_id` | UUID | null | Project to assign |
-| `p_metadata` | JSONB | `{}` | Metadata (agent name, tags, etc.) |
-
-Returns: `id`, `title`, `created_at`
-
----
-
 ### Metadata RPCs
 
 #### `cerefox_list_metadata_keys`

package/docs/guides/ops-scripts.md

@@ -80,9 +80,9 @@ bun scripts/db_status.ts          # human-readable report
 bun scripts/db_status.ts --json   # structured JSON output
 ```
 
-Reports:
-- Tables: `cerefox_documents`, `cerefox_chunks`, `cerefox_document_versions`, `cerefox_projects`, `cerefox_document_projects`, `cerefox_audit_log`, `cerefox_migrations`
-- RPC functions: hybrid_search, fts_search, semantic_search, reconstruct_doc, save_note, search_docs, context_expand, snapshot_version, get_document, list_document_versions, ingest_document, delete_document, create_audit_entry, list_audit_entries, list_metadata_keys, update_chunk_fts, **`cerefox_schema_version`** (new in v0.3.0), **`cerefox_pg_function_exists`** (new in v0.3.0)
+Reports (the expected lists live in `_shared/db-status/index.ts` — the single source of truth):
+- Tables: `cerefox_projects`, `cerefox_documents`, `cerefox_document_versions`, `cerefox_audit_log`, `cerefox_document_projects`, `cerefox_chunks`, `cerefox_migrations`, `cerefox_usage_log`, `cerefox_config`, `cerefox_document_relations`
+- RPC functions: set_updated_at, hybrid_search, fts_search, semantic_search, reconstruct_doc, list_projects, log_usage, list_metadata_keys, snapshot_version, get_document, list_document_versions, create_audit_entry, list_audit_entries, ingest_document, delete_document, restore_document, purge_document, set_config, create_project, update_project, delete_project, set_document_metadata, find_dead_links, metadata_health, metadata_search, update_chunk_fts, `cerefox_schema_version`, `cerefox_pg_function_exists`
 - Row counts per table
 - **Schema-version mismatch**: compares the `@version` marker in the bundled `schema.sql` against the deployed `cerefox_schema_version()` RPC. Non-zero exit if they differ (the same check powers the web UI's schema-mismatch banner).
 
@@ -114,7 +114,7 @@ bun scripts/db_migrate.ts [OPTIONS]
 
 On a freshly deployed database, `db_migrate.ts` is always a no-op — `db_deploy.ts` has already stamped all existing migrations.
 
-Migration files live in `src/cerefox/db/migrations/` and are applied in filename order (`0001_...`, `0002_...`). Each file is applied exactly once; applied filenames are recorded in the `cerefox_migrations` table.
+Migration files live in `src/cerefox/db/migrations/` and are applied in filename order (`0001_...`, `0002_...`). Each file is applied exactly once; applied filenames are recorded in the `cerefox_migrations` table. Recent migrations (0023–0027) include data migrations that print what they did (0027 reports reclaimed space); see [`docs/guides/upgrading.md`](upgrading.md).
 
 Always run a backup before migrating:
 

package/docs/guides/upgrading.md

@@ -136,7 +136,7 @@ a linked Supabase project.
 
 ## Notable cross-version transitions
 
-Most upgrades need nothing beyond the steps above. Two transitions are worth
+Most upgrades need nothing beyond the steps above. A few transitions are worth
 knowing about:
 
 - **v0.9 — CLI verbs moved to a resource-verb shape** (`cerefox document get`,
@@ -149,6 +149,10 @@ knowing about:
   `@cerefox/memory` npm package (CLI, MCP server, web server, ingestion). If
   you're coming from a pre-installer 0.1.x clone, see the "old pre-installer
   clone" note above: install the package and run `cerefox init`.
+- **v1.5.0 — heading-duplication refusal.** Documents with duplicate headings
+  that ingested fine before now need deduplication, or are refused on edit.
+- **v1.7.0 — trashed documents refuse content updates.** A soft-deleted
+  document must be restored before its content can be updated.
 
 ## Notable: v1.8.0 storage reclaim (migration 0027)