@cerefox/memory 1.3.0 → 1.5.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,7 +157,7 @@ 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. |
 
@@ -169,22 +169,25 @@ 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: **a heading's own text cannot be changed** —
-`replace_section` preserves it by design — so a stale date inside a heading needs
-a re-ingest too.
+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.
 
 ---
 
@@ -600,3 +603,82 @@ printf '...new content...' \
 cerefox audit list --json --limit 1000 --requestor "claude-code" \
   | jq 'select(.author_type == "agent")'
 ```
+
+## Timestamps are UTC
+
+Every timestamp Cerefox returns — `created_at` on audit entries, version
+history, document metadata — is **UTC**, and now carries its `Z` marker so it
+cannot be mistaken for local time.
+
+**When you write a date into a document's CONTENT, use your own clock, not a
+Cerefox timestamp.** These are different things: a timestamp records when the
+server stored something; a date in a log entry or a heading is authored content
+and belongs to your timezone. An agent working a Pacific afternoon read
+`2026-08-11` from version history, wrote "8/11" into its entries, and put a
+day's work in the future — the timestamp was correct, and copying it into
+content was not.
+
+Cerefox deliberately does not convert to local time on the API or MCP paths.
+"Local" has no server-side meaning: the remote MCP server runs in a cloud
+function whose local time *is* UTC, while a local MCP server runs in yours, so
+the same document would report two different times depending on transport. The
+web UI converts because a browser knows the viewer's timezone; nothing
+server-side does.
+
+## Mistakes that have actually happened
+
+Each of these comes from a real agent session, and each is easy to make.
+
+- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.
+  Before sending, check that the tool name matches the intent: if the intent is
+  "change one section", the call is `cerefox_edit` with `replace_section`. A
+  section-sized edit sent as a full ingest truncated a 13,000-character index to
+  a single word. It was recovered from version history within the minute, but
+  only because it was noticed immediately.
+
+- **Do not include the anchor's own heading in your text.** `replace_section`
+  keeps the heading and `insert` places your text inside the section, so
+  including it produces two. This is now refused rather than silently applied,
+  but the shape is worth knowing: it happened twice in one session, the second
+  time while trying to repair the first. A *deeper* sub-heading inside your text
+  is fine.
+
+- **Content between sections belongs to the section ABOVE it.** A section runs
+  to the next heading of the same or higher level, so a `---` rule, a note, or
+  any trailing text sitting just above the next heading is part of the section
+  before it — even when it visually reads as belonging below. Replacing that
+  section takes it too. An agent hit exactly this: a `---` that separated two
+  major sections disappeared when the section above it was replaced. The write
+  was correct by the addressing rules; the surprise is that "the end of this
+  section" is further down the page than it looks. Note the loss warning will
+  not catch it if your replacement text is longer than what it replaced, since
+  there is then no net loss to report.
+
+- **Never partial-edit to fix a partial edit.** If a write leaves unexpected
+  structure, stop. Use `cerefox_list_versions`, retrieve the last good version,
+  and re-ingest cleanly. Repairing edits with more edits compounds the damage.
+
+- **A rejected batch is safe.** Operations in one `cerefox_edit` are
+  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a
+  retry, not data — so prefer one call for changes that belong together, and do
+  not split a batch to "make it more likely to succeed".
+
+- **Read before replacing.** `cerefox_get_document(section: "## Heading")`
+  returns exactly what a `replace_section` on that anchor would overwrite. Use it
+  for any section you did not write in this session. The outline gives a
+  section's *size*, never its *text*.
+
+- **Verify after writing** — read the result back before reporting success, and
+  report what the read actually shows.
+
+- **Partial edits cannot change a document's stored TITLE.** `rename_section`
+  changes a heading inside the content; the title is a separate field and still
+  needs `cerefox_ingest`.
+
+- **If a capability seems missing from one server, suspect your client first.**
+  Local and remote run the same code. Call `cerefox_get_help(topic: "server")`:
+  it reports the server's own version and the operations it registers. If that
+  disagrees with your tool list, the client is holding a list it fetched before
+  an upgrade — clients cache it at connect time. Ask the user to restart the
+  client. Do not record a capability difference between servers as a fact; every
+  such report so far has been a stale client.

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.
 
@@ -128,3 +135,82 @@ Same operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/g
 - Reads: `--requestor "<your-name>"`
 
 Or have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.
+
+## Timestamps are UTC
+
+Every timestamp Cerefox returns — `created_at` on audit entries, version
+history, document metadata — is **UTC**, and now carries its `Z` marker so it
+cannot be mistaken for local time.
+
+**When you write a date into a document's CONTENT, use your own clock, not a
+Cerefox timestamp.** These are different things: a timestamp records when the
+server stored something; a date in a log entry or a heading is authored content
+and belongs to your timezone. An agent working a Pacific afternoon read
+`2026-08-11` from version history, wrote "8/11" into its entries, and put a
+day's work in the future — the timestamp was correct, and copying it into
+content was not.
+
+Cerefox deliberately does not convert to local time on the API or MCP paths.
+"Local" has no server-side meaning: the remote MCP server runs in a cloud
+function whose local time *is* UTC, while a local MCP server runs in yours, so
+the same document would report two different times depending on transport. The
+web UI converts because a browser knows the viewer's timezone; nothing
+server-side does.
+
+## Mistakes that have actually happened
+
+Each of these comes from a real agent session, and each is easy to make.
+
+- **`cerefox_ingest` always replaces the ENTIRE document.** Never a section.
+  Before sending, check that the tool name matches the intent: if the intent is
+  "change one section", the call is `cerefox_edit` with `replace_section`. A
+  section-sized edit sent as a full ingest truncated a 13,000-character index to
+  a single word. It was recovered from version history within the minute, but
+  only because it was noticed immediately.
+
+- **Do not include the anchor's own heading in your text.** `replace_section`
+  keeps the heading and `insert` places your text inside the section, so
+  including it produces two. This is now refused rather than silently applied,
+  but the shape is worth knowing: it happened twice in one session, the second
+  time while trying to repair the first. A *deeper* sub-heading inside your text
+  is fine.
+
+- **Content between sections belongs to the section ABOVE it.** A section runs
+  to the next heading of the same or higher level, so a `---` rule, a note, or
+  any trailing text sitting just above the next heading is part of the section
+  before it — even when it visually reads as belonging below. Replacing that
+  section takes it too. An agent hit exactly this: a `---` that separated two
+  major sections disappeared when the section above it was replaced. The write
+  was correct by the addressing rules; the surprise is that "the end of this
+  section" is further down the page than it looks. Note the loss warning will
+  not catch it if your replacement text is longer than what it replaced, since
+  there is then no net loss to report.
+
+- **Never partial-edit to fix a partial edit.** If a write leaves unexpected
+  structure, stop. Use `cerefox_list_versions`, retrieve the last good version,
+  and re-ingest cleanly. Repairing edits with more edits compounds the damage.
+
+- **A rejected batch is safe.** Operations in one `cerefox_edit` are
+  all-or-nothing: if any is invalid, nothing is written. A refusal costs you a
+  retry, not data — so prefer one call for changes that belong together, and do
+  not split a batch to "make it more likely to succeed".
+
+- **Read before replacing.** `cerefox_get_document(section: "## Heading")`
+  returns exactly what a `replace_section` on that anchor would overwrite. Use it
+  for any section you did not write in this session. The outline gives a
+  section's *size*, never its *text*.
+
+- **Verify after writing** — read the result back before reporting success, and
+  report what the read actually shows.
+
+- **Partial edits cannot change a document's stored TITLE.** `rename_section`
+  changes a heading inside the content; the title is a separate field and still
+  needs `cerefox_ingest`.
+
+- **If a capability seems missing from one server, suspect your client first.**
+  Local and remote run the same code. Call `cerefox_get_help(topic: "server")`:
+  it reports the server's own version and the operations it registers. If that
+  disagrees with your tool list, the client is holding a list it fetched before
+  an upgrade — clients cache it at connect time. Ask the user to restart the
+  client. Do not record a capability difference between servers as a fact; every
+  such report so far has been a stale client.