@cerefox/memory 1.12.1 → 1.13.0

package/docs/guides/configuration.md

@@ -378,9 +378,13 @@ enable it.
 ### How it works
 
 A `cerefox_config` table in Postgres stores runtime configuration as key-value
-pairs. The allow-list lives in the `cerefox_set_config` RPC; run `cerefox config
-list` (or open **Settings** in the web UI) for the current set — today that is
-usage tracking, the two requestor-identity keys, three retrieval tunables, and
+pairs. Every key is declared once in the shared catalog
+(`_shared/config-catalog/index.ts`: kind, default, group, description); the
+`cerefox_set_config` RPC's allow-list stays authoritative for writes and a unit
+test pins the two together. Run `cerefox config list` (or open **Settings** in
+the web UI) for the current set — today that is usage tracking, the two
+requestor-identity keys, three retrieval tunables, two version-retention keys,
+the document-size warning threshold, `review_workflow_enabled` and
 `relations_enabled`. Usage logging is the illustrative case below: every logging
 call goes through the
 `cerefox_log_usage` RPC, which checks this config value first:
@@ -414,15 +418,17 @@ cerefox config get usage_tracking_enabled
 
 **Via the web UI:** `cerefox web` → **Settings**. Every runtime key is listed
 with its description, current value and default, grouped into Retrieval,
-Governance and Features.
+Retention, Governance and Features.
 
 Two things the page does deliberately:
 
 - **Keys that change what agents see require confirmation.** Turning on
-  `relations_enabled` adds four tools to every connected agent's tool list, and
+  `relations_enabled` adds four tools to every connected agent's tool list,
   `require_requestor_identity` starts rejecting agents that don't identify
-  themselves. Neither is a bare toggle — you get a dialog naming the
-  consequence first.
+  themselves, `review_workflow_enabled` hides or reveals the review status on
+  every surface, and `version_cleanup_enabled` decides whether old versions are
+  pruned. None is a bare toggle — you get a dialog naming the consequence
+  first.
 - **Retired `.env` lines are flagged.** If a variable that used to control a
   setting is still present in the server's environment, the row says so — it no
   longer does anything, and the value shown is what actually runs. The page
@@ -539,9 +545,51 @@ This is the default state -- no configuration needed for backward compatibility.
 
 ---
 
+## Review Workflow
+
+Cerefox can queue agent-authored writes for a person to approve: with the
+workflow **on**, a document written with `author_type: agent` lands as
+`pending_review`, a human write lands as `approved`, and every surface shows the
+status (a pill on the document page, badges on the dashboard, a search filter,
+a `status` column in the CLI, the field in API and MCP output). Review status
+never gates retrieval — a pending document is exactly as searchable as an
+approved one — it is a governance signal, nothing more.
+
+Since v1.13.0 the workflow is a store-level switch, `review_workflow_enabled`,
+kept in `cerefox_config` like every other store setting so two clients on one
+database cannot disagree about whether it exists:
+
+| Situation | Value |
+|---|---|
+| Fresh install (v1.13.0+) | **`false`** — most single-operator stores never review anything |
+| Upgraded from an earlier version | **`true`** — an upgrade never changes what your store does |
+
+```bash
+cerefox config get review_workflow_enabled
+cerefox config set review_workflow_enabled true    # or false; also in Settings → Governance
+cerefox doctor                                      # prints "review workflow  ON …" / "OFF …"
+```
+
+**With the workflow off, the feature is absent, not dimmed.** Every write lands
+`approved` whoever wrote it — the decision is made once, inside the
+`cerefox_ingest_document` RPC, so every access path (CLI, local and remote MCP,
+Edge Functions, web) obeys the same setting, including older clients. No surface
+shows a `review_status`: the web pill, badges and search chip do not render;
+the CLI drops its `status` column; API, MCP and Edge Function rows carry no
+`review_status` key; `GET /api/v1/search?review_status=…` is a `400`; and
+`POST /api/v1/documents/{id}/review-status` is a `404`.
+
+**Toggling never touches stored data.** Flipping the flag off does not approve
+anything and flipping it on does not queue anything; documents that were
+`pending_review` are still pending, and are shown as such the moment the flag
+is on again. Attribution and the audit log are unaffected in both states — who
+wrote what is always recorded. Config changes are audited too.
+
+Design: [`docs/specs/review-workflow-toggle.md`](../specs/review-workflow-toggle.md).
+
 ## Checking Your Configuration
 
-Run the doctor to verify everything is connected (credentials, DB reachability, schema version):
+Run the doctor to verify everything is connected (credentials, DB reachability, schema version, review workflow on/off):
 
 ```bash
 cerefox doctor       # or: cerefox status

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.3.0
+  version: 3.4.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -798,8 +798,10 @@ paths:
                   default: agent
                   description: >
                     Whether this write is from a human user or an AI agent.
-                    Controls review_status auto-transition: agent writes set
-                    the document to pending_review, user writes set it to approved.
+                    Always recorded for attribution. While the store's review
+                    workflow is on (review_workflow_enabled), agent writes land
+                    pending_review and user writes approved; with it off every
+                    write lands approved.
       responses:
         '200':
           description: >
@@ -1033,9 +1035,11 @@ paths:
         '200':
           description: >
             Array of matching documents:
-            [{ document_id, title, doc_metadata, review_status, source, created_at,
+            [{ document_id, title, doc_metadata, source, created_at,
                updated_at, total_chars, chunk_count, project_ids, project_names,
-               version_count, content_hash, content }].
+               version_count, content_hash, content }], plus review_status
+            only while the store's review workflow is on (the key is absent
+            when it is off).
             content_hash is the concurrency token — pass it back as
             expected_content_hash when updating via ingestNote.
 ```

package/docs/guides/upgrading.md

@@ -11,7 +11,7 @@ cerefox guides ingest    # 3. the bundled guides, into your KB
 ```
 
 The order matters: a release may require its own schema (the version notes
-say so — v1.9.x is one), and until `server deploy` runs, the freshly updated
+say so — v1.9.x and v1.13.0 are two), and until `server deploy` runs, the freshly updated
 client is talking to the previous release's server. That is why
 `self-update` no longer runs the guides sync automatically — it used to fire
 at the one moment in the upgrade where it cannot succeed against a
@@ -60,6 +60,24 @@ schema-requiring release.
 
 ## End-user upgrade
 
+> ### Upgrading to v1.13.0 — `cerefox server deploy` is required
+>
+> v1.13.0 makes the review workflow optional and moves the "agent writes land
+> `pending_review`" decision out of the clients and into the
+> `cerefox_ingest_document` RPC (#241). A v1.13.0 client no longer decides
+> the status itself, so against an older server every agent write would
+> silently land `approved` — a behaviour change, not a missing feature — and
+> the new review-status search filter would fail outright. The **minimum
+> supported schema is therefore `0.16.0`**: until you run `cerefox server
+> deploy`, `cerefox web` refuses to start and `doctor` says exactly why.
+>
+> Migration 0031 seeds `review_workflow_enabled = true` on every existing
+> store, so **your store keeps behaving exactly as before**. The flag now
+> exists and `cerefox doctor` prints its state; flip it with
+> `cerefox config set review_workflow_enabled false` (or Settings → Governance)
+> if nobody reviews the queue. See
+> [configuration.md → Review Workflow](configuration.md#review-workflow).
+
 > ### Upgrading to v1.1.0 — `cerefox server deploy` is required
 >
 > Most releases let you postpone the server step. **This one does not.** Until
@@ -166,6 +184,8 @@ knowing about:
   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.
+- **v1.13.0 — the review workflow is a store setting.** Upgraded stores keep
+  it on; fresh installs start with it off. See the callout above.
 
 ## Notable: v1.8.0 storage reclaim (migration 0027)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerefox/memory",
-  "version": "1.12.1",
+  "version": "1.13.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",