@cerefox/memory 1.3.0-beta.4 → 1.4.0

package/AGENT_GUIDE.md

@@ -124,7 +124,7 @@ Retrieve the complete text of a document by its UUID.
 | `outline` | No | `true` returns the document's **structure instead of its content**: heading paths, levels, per-section sizes, plus `content_hash` and total size. Much cheaper than a full read. The paths are exactly what the edit tools take as `anchor_heading`. |
 | `requestor` | No | Your agent name. |
 
-Use this when search returns partial results, or to read a previous version before restoring it. The response header includes the document's current `content_hash` — pass it back as `expected_content_hash` when updating via `cerefox_ingest` or editing via `cerefox_insert` / `cerefox_edit`.
+Use this when search returns partial results, or to read a previous version before restoring it. Pass `outline: true` for the heading structure without the body, or `section: "## Heading"` for one section's text — which is exactly what a `replace_section` on that anchor would overwrite, so read it before replacing a section you did not write yourself. The response header includes the document's current `content_hash` — pass it back as `expected_content_hash` when updating via `cerefox_ingest` or editing via `cerefox_insert` / `cerefox_edit`.
 
 **Before editing a document you have not read this session, call it with `outline: true` first.** It answers the three questions an edit needs — what are the anchors, how big is each section, what is the current hash — without pulling the body into your context.
 
@@ -157,24 +157,37 @@ Change parts of a document: **one to many operations applied atomically in a sin
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `document_id` | Yes | UUID of the document. |
-| `operations` | Yes | Array of operations, applied **in order, all-or-nothing**. Each is `{op, ...}` with `op` one of `insert` (same fields as `cerefox_insert`), `replace_section` (`anchor_heading`, `text`; swaps the body, keeps the heading), `delete_section` (`anchor_heading`, optional `scope`: `body_only` default keeps the heading, `heading_and_body` removes it too). |
+| `operations` | Yes | Array of operations, applied **in order, all-or-nothing**. Each is `{op, ...}` with `op` one of `insert` (same fields as `cerefox_insert`), `replace_section` (`anchor_heading`, `text`; swaps the body, keeps the heading), `delete_section` (`anchor_heading`, optional `scope`: `body_only` default keeps the heading, `heading_and_body` removes it too), `rename_section` (`anchor_heading`, `new_heading`; changes the heading TEXT only — body and position untouched, and the level must stay the same, since changing it would re-parent everything nested underneath). |
 | `expected_content_hash` | **Yes** | One token for the whole call. No `last_write_wins`. |
 | `requestor` | No | Your agent name. |
 
 **Put changes that belong together in ONE call.** Operations apply in order against the evolving document (op 2 sees op 1's result), and a half-applied state is impossible — so a table row and the running total it feeds cannot end up disagreeing. If any operation fails (bad anchor, ambiguity), nothing at all is written and the error names the failing operation.
 
+**When NOT to use partial edits.** They are for localized changes. If what you
+are changing recurs across the document — a "last updated" date in the header, a
+heading, and the footer — that is a whole-document change wearing a local
+disguise, and `cerefox_ingest` is the right tool. Section-scoped edits would take
+several calls, each individually valid, with the document briefly inconsistent
+between them. An agent hit exactly this and correctly stopped rather than
+contorting the tools. (Related, and **fixed in v1.4.0**: a heading's own text
+used to be unchangeable, because `replace_section` preserves it by design, so a
+stale date inside a heading forced a re-ingest. `rename_section` now changes the
+heading and nothing else.)
+
 **One sharp edge worth knowing.** A section runs to the next heading of the same
 or higher level — **or to the end of the document**. So the last section owns
 everything appended after it: an `end_of_document` insert becomes part of that
 section's body, and a later `replace_section` or `delete_section` on that heading
 removes it along with the rest. This is correct addressing, not a bug, but it is
-silent. If a write reports a large shrink, that is the warning; the previous
-content is in `cerefox_list_versions`. To append somewhere a later section edit
+silent. Since v1.4.0 any edit that removes content says so with the amount, and
+a replace or delete on the LAST section gets the full explanation whatever the
+size — the loss that matters here is *small* precisely because it was just
+added. The previous content is in `cerefox_list_versions`. To append somewhere a later section edit
 cannot swallow, give the appended material its own heading.
 
 **To change a single line**, `replace_section` on its smallest enclosing heading and resend just that section. That is the intended granularity — line-level anchors were deliberately excluded because they silently edit the wrong place.
 
-The audit trail records each operation distinctly (`insert` / `replace-section` / `delete-section`), so *added to*, *rewrote* and *removed* stay distinguishable from a full rewrite.
+The audit trail records each operation distinctly (`insert` / `replace-section` / `delete-section` / `rename-section`), so *added to*, *rewrote* and *removed* stay distinguishable from a full rewrite.
 
 ---
 

package/AGENT_QUICK_REFERENCE.md

@@ -9,8 +9,8 @@ Cerefox is a persistent, shared knowledge base. You have **16 MCP tools** (15 of
 | `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |
 | `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `expected_content_hash` (**required on content updates** — see rule 9), `last_write_wins`, `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata` (omit on update to keep existing tags; `{}` clears), `author` |
 | `cerefox_insert` | **Add** to a document without resending it. Cannot destroy content. | `document_id`, `text`, `position` (`end_of_document`/`end_of_section`/`after_heading`/`before_heading`), `expected_content_hash` (required), `anchor_heading` (unless `end_of_document`), `section_part` |
-| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`), `expected_content_hash` (required) |
-| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash | `document_id` (required), `outline` |
+| `cerefox_edit` | **Change** parts of a document: 1..n operations applied atomically | `document_id`, `operations` (`insert`/`replace_section`/`delete_section`/`rename_section`), `expected_content_hash` (required) |
+| `cerefox_get_document` | Get full document by ID (header includes `content_hash` — the update token), or with `outline: true` just its heading paths, sizes and hash, or with `section: "## Heading"` one section's text | `document_id` (required), `outline`, `section`, `section_part` |
 | `cerefox_list_versions` | Version history of a document | `document_id` (required) |
 | `cerefox_set_relation` ⚑ | Link two documents (`source --rel_type--> target`) | `source_id`, `target_id`, `rel_type` (required), `metadata`, `author` |
 | `cerefox_delete_relation` ⚑ | Remove a relation | `source_id`, `target_id`, `rel_type` |
@@ -41,12 +41,19 @@ diff. Use the partial-edit tools instead:
 2. **Add** → `cerefox_insert`. `end_of_document` is a plain append;
    `end_of_section` adds inside a named section. It is structurally incapable of
    removing anything, so "I meant to append" cannot become "I replaced the file".
-3. **Change or remove** → `cerefox_edit`. Put changes that belong together in
+3. **Look before you overwrite** — `cerefox_get_document(document_id,
+   section: "## Heading")` returns exactly the text a `replace_section` on that
+   anchor would destroy. The outline gives you a section's *size*, never its
+   *text*, so on a document you did not write yourself this is the difference
+   between a replace and a blind overwrite.
+4. **Change or remove** → `cerefox_edit`. Put changes that belong together in
    ONE call: they apply atomically, so a table row and the total it feeds cannot
    end up disagreeing. To change a single line, `replace_section` on its
    smallest enclosing heading — that is the intended granularity, not a
-   workaround.
-4. Both require `expected_content_hash` and **have no last-write-wins**. A
+   workaround. To fix a stale heading (`## OPEN TODOs (as of ...)`), use
+   `rename_section`: it changes the heading text and leaves the body and
+   position alone.
+5. All of them require `expected_content_hash` and **have no last-write-wins**. A
    conflict means someone else changed the document; re-read and decide, do not
    force it.