From de595719660aa4a83cfb9368abd4d82be26b9a47 Mon Sep 17 00:00:00 2001
From: Joakim Persson <joakim.m.persson@ericsson.com>
Date: Thu, 27 Aug 2026 16:15:44 +0200
Subject: [PATCH] docs: unclip fleet-memory's diagrams, and measure the host
 instead of guessing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Seven labels in fleet-memory.md were losing their last line for readers, in the
document held up as the model for user-facing docs. Found by running a new
mermaid checker against a repo it was not written for, which is the strongest
evidence available that this is a systemic defect class and not one author's slip.

Measured on the real Gitea render rather than a simulation. Gitea serves each
mermaid block from a sandboxed same-origin <iframe srcdoc>, so its
.markup{line-height:1.5!important} never reaches the labels and the page is
directly measurable. On the published version: 31 labels, 6 of them rendering
MORE lines than were authored, worst overflow +0.6px past the clip edge. Mermaid
measures a label with its own metrics, commits to a box, then clips whatever does
not fit; per-line rounding accumulates, so every cut label observed anywhere in
this fleet had four or five rendered lines.

Fixes, all preserving the information rather than deleting it:

- The five store nodes drop their third line; the content shapes they carried
  ("verbatim text, embedded", "typed facts, time-bounded", "addressed events and
  their artifacts", "links between rooms", "read by recency") move into the prose
  under the diagram, which is where a qualifier belongs anyway.
- "ask by ADDRESS + ORDER" soft-wrapped its own first line because a caps line
  nearly as wide as the box overflows first; shortened to "ask by ADDRESS", with
  "read in append order" added to the prose so the ordering property survives.
  The table already lists "address, correlation, append order".
- The decision diamond loses "machine or agent" to the sentence above it, which
  now asks whether "a specific machine or agent" must act — same words, no clip.
- "to_agent = the specific agent" and the BOTH node shortened; both are spelled
  out in full in the worked-examples table directly below.

Nothing was cut for brevity's sake: every phrase removed from a node reappears in
the prose or was already in the table beneath it.
---
 docs/fleet-memory.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/docs/fleet-memory.md b/docs/fleet-memory.md
index 0a9df2b..ab70d23 100644
--- a/docs/fleet-memory.md
+++ b/docs/fleet-memory.md
@@ -13,14 +13,14 @@ This document covers: what the stores are, what a central palace changes when se
 
 ```mermaid
 flowchart LR
-    Q["ask by MEANING<br/>'what do we know about X?'"] --> D["<b>Drawers</b><br/>chroma.sqlite3<br/>verbatim text, embedded"]
-    R["ask by ENTITY + TIME<br/>'what was true in June?'"] --> G["<b>Knowledge graph</b><br/>knowledge_graph.sqlite3<br/>typed facts, time-bounded"]
-    S["ask by ADDRESS + ORDER<br/>'what is waiting for me?'"] --> L["<b>Coordination log</b><br/>logstream.sqlite3<br/>addressed events + artifacts"]
-    T["ask by ASSOCIATION<br/>'what else touches this?'"] --> P["<b>Palace graph</b><br/>tunnels.json + hallways.json<br/>links between rooms"]
-    D --> DI["<b>Diaries</b> live here too:<br/>drawers with room=diary,<br/>read by recency, not similarity"]
+    Q["ask by MEANING<br/>'what do we know about X?'"] --> D["<b>Drawers</b><br/>chroma.sqlite3"]
+    R["ask by ENTITY + TIME<br/>'what was true in June?'"] --> G["<b>Knowledge graph</b><br/>knowledge_graph.sqlite3"]
+    S["ask by ADDRESS<br/>'what is waiting for me?'"] --> L["<b>Coordination log</b><br/>logstream.sqlite3"]
+    T["ask by ASSOCIATION<br/>'what else touches this?'"] --> P["<b>Palace graph</b><br/>tunnels.json + hallways.json"]
+    D --> DI["<b>Diaries</b> live here too:<br/>drawers with room=diary"]
 ```
 
-All four stores are files inside **one palace directory**, so "the palace" is a directory you can back up in one go.
+All four stores are files inside **one palace directory**, so "the palace" is a directory you can back up in one go. Each holds a different *shape* of thing: drawers hold verbatim text, embedded for similarity; the knowledge graph holds typed facts that are time-bounded; the coordination log holds addressed events and their artifacts, read in append order; the palace graph holds links between rooms. Diaries are drawers, but they are read by recency rather than by similarity.
 
 | Store | You get things back by | Typical use | Wrong use |
 |---|---|---|---|
@@ -110,19 +110,19 @@ sequenceDiagram
 
 ## 3. Deciding where something goes
 
-The question that matters is not "is this important?" but **"how will I want this back, and does anyone need to act?"**
+The question that matters is not "is this important?" but **"how will I want this back, and does a specific machine or agent need to act?"**
 
 ```mermaid
 flowchart TD
-    Start["I have something worth keeping"] --> Act{"Must a specific<br/>machine or agent<br/>DO something?"}
+    Start["I have something worth keeping"] --> Act{"Must someone specific<br/>DO something?"}
     Act -->|no| Change{"Is it a fact that<br/>changes over time?"}
     Act -->|yes| Know{"Do they also need<br/>to KNOW it later?"}
     Change -->|yes| KG["Knowledge graph<br/>kg_add / kg_supersede"]
-    Change -->|no| Mine{"Is it about MY session<br/>— what I tried, felt, learned?"}
+    Change -->|no| Mine{"Is it about MY session<br/>— tried, felt, learned?"}
     Mine -->|yes| Diary["Diary entry"]
     Mine -->|no| Drawer["Drawer<br/>wing + room, verbatim"]
-    Know -->|yes| Both["BOTH:<br/>drawer for the knowledge,<br/>event pointing at it"]
-    Know -->|no| Event["Coordination event<br/>to_agent = the specific agent"]
+    Know -->|yes| Both["BOTH:<br/>drawer + event pointing at it"]
+    Know -->|no| Event["Coordination event<br/>to_agent = that agent"]
 ```
 
 Worked examples: