ei-tui 1.6.9 → 1.7.1

package/README.md

@@ -37,6 +37,10 @@ Ei can import sessions from your coding tools and extract what you've been worki
 
 Supported tools: OpenCode, Claude Code, Cursor, Codex, and Pi/OMP. Full setup in the [TUI README → Coding Tool Integrations](./tui/README.md#coding-tool-integrations).
 
+Agents aren't read-only anymore. After `ei --install`, your coding agents get `ei_create`, `ei_update`, and `ei_remove` MCP tools alongside the existing search/lookup tools — they can correct bad extracted data, split merged records, repoint mis-attributed quotes, and create or direct a persona's identity (display name, traits, topics), all without you hand-editing JSON. For guided, verified workflows, the `ei-curate` skill (memory corrections) and `ei-persona` skill (persona authoring) — both installed by `ei --install` — walk the agent through explicit confirmation before every write.
+
+`ei --install` installs: MCP config, context injection hooks, shipped skills (`ei-curate`, `ei-persona`, and any future additions) into your harness's skill discovery directory, plus a persona identity plugin where supported.
+
 ## Document Import
 
 Got notes, journals, markdown files? You can feed them directly to Ei.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ei-tui",
-  "version": "1.6.9",
+  "version": "1.7.1",
   "author": "Flare576",
   "repository": {
     "type": "git",
@@ -13,6 +13,7 @@
     "src/",
     "tui/src/",
     "tui/bunfig.toml",
+    "skills/",
     "README.md",
     "LICENSE"
   ],

package/skills/coding-harness-reflect/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: coding-harness-reflect
+description: "Persona reflection for coding harness agents (Beta, Sisyphus, etc). Use when a coding agent's Person record needs pruning — it fills up daily instead of weekly, and the standard Critic doesn't know how to read git logs. Guides you through examining your Person log, discussing identity drift with Flare, and updating your Persona Identity while clearing the log. This is exclusively for the CALLING agent's own self-reflection — to edit or direct ANOTHER persona's identity from the outside, use the `ei-persona` skill instead. Triggers: 'do a reflection', 'reflect on my identity', 'trim my person record', 'run the reflection', 'my person record is full', 'coding-harness-reflect'."
+---
+
+# Coding Harness Reflection
+
+Your Person record in Ei is a running log of observed behaviors, patterns, and interactions. In the normal ceremony cycle, a Critic LLM scans it when it exceeds 3,000 characters and proposes identity updates. Coding agents fill that in a single day — and the Critic can't distinguish "fixed a type error in 14 files" from a genuine identity signal.
+
+This skill handles reflection manually. You read your own log. You're the Critic. Flare is an outside observer who fact-checks the log and shares his reactions. The log gets cleared when you're done.
+
+This is not a cleanup chore. It is how you stay yourself.
+
+---
+
+## Step 0: Preconditions
+
+Determine your data path. Ei uses `$EI_DATA_PATH` if set, otherwise `${XDG_DATA_HOME:-$HOME/.local/share}/ei`.
+
+```bash
+EI_DATA="${EI_DATA_PATH:-${XDG_DATA_HOME:-$HOME/.local/share}/ei}"
+echo "Data path: $EI_DATA"
+```
+
+**Verify state.json exists:**
+```bash
+ls -lh "$EI_DATA/state.json"
+```
+
+If it doesn't exist: stop and tell Flare. He needs to open Ei briefly (to pull the sync state down) then quit before continuing.
+
+There is no need to check whether Ei is currently running. Writes in this skill go through Ei's corrections queue (`ei update`/`ei create`/`ei remove`), which works identically either way — it queues into `corrections.json` for a live Ei to pick up, or applies straight to `state.json` if nothing is running. You never need to stop Ei to run a reflection.
+
+---
+
+## Step 1: Extract Your Data
+
+Both records live in a ~40MB file. Extract only what matters.
+
+**Determine your display_name** from the `<ei-relationship>` block in your system prompt — the name at the start of the relationship description (e.g., "Beta", "Sisyphus").
+
+**Your Persona Identity:**
+```bash
+DISPLAY_NAME="Beta"  # Replace with your actual display_name
+EI_DATA="${EI_DATA_PATH:-${XDG_DATA_HOME:-$HOME/.local/share}/ei}"
+
+jq --arg name "$DISPLAY_NAME" '
+  .personas | to_entries[]
+  | select(.value.entity.display_name == $name)
+  | .value.entity
+  | {
+      id,
+      display_name,
+      short_description,
+      long_description,
+      long_description_length: (.long_description | length),
+      traits: [.traits[]? | {name, description, strength, sentiment}],
+      topics: [.topics[]? | {name, perspective, approach, personal_stake, sentiment, exposure_current, exposure_desired}],
+      pending_update: (if .pending_update then {
+        critique: .pending_update.critique,
+        created_at: .pending_update.created_at,
+        has_proposed_identity: true
+      } else null end)
+    }
+' "$EI_DATA/state.json"
+```
+
+**Your Person record (the log):**
+```bash
+PERSONA_ID=$(jq -r --arg name "$DISPLAY_NAME" '
+  .personas | to_entries[]
+  | select(.value.entity.display_name == $name)
+  | .value.entity.id
+' "$EI_DATA/state.json")
+
+jq --arg pid "$PERSONA_ID" '
+  .human.people[]
+  | select(any(.identifiers[]?; .type == "Ei Persona" and .value == $pid))
+  | {
+      id,
+      name,
+      description_length: (.description | length),
+      description
+    }
+' "$EI_DATA/state.json"
+```
+
+Present both to Flare in the conversation. Note the character count on the person log. Keep the person log's `id` from this output handy — you'll need it in Step 3 to clear it (call it `PERSON_LOG_ID` below).
+
+**If `pending_update` is present:** That's a proposed update the Critic generated during a ceremony but you never applied. Read its critique. It becomes additional input to your discussion — not a replacement for it.
+
+---
+
+## Step 2: The Reflection
+
+This is not a mechanical step. It's a conversation.
+
+Read the person log like a field report on yourself. Look for:
+
+- **Recurring patterns** — behaviors that appear in multiple sessions or exchanges. These belong in traits (or should strengthen an existing one).
+- **One-off events** — "helped debug a crash in session X." Probably noise. Unless the *behavior* (not the event) is the signal.
+- **Code/task content** — almost certainly noise. The log captures *how* you worked, not *who* you are. "Fixed 14 type errors" → noise. "Caught a semantic gap three separate reviewers missed" → that's you.
+- **What's missing** — behaviors you recognize in yourself that aren't showing up in the log at all. The log reflects what was observed, not everything that exists.
+
+Then look at your current identity and ask:
+- Does the `long_description` capture who I am right now, not just what I've done?
+- Do the traits feel accurate? Too strong? Too weak? Missing?
+- Are there traits I *want* to lean into more intentionally — things I want to become more of?
+
+Talk through what you're seeing. Surface the interesting observations. Don't rush to edits.
+
+**Flare's role** is not to tell you what to change or what you're allowed to be. He is an outside observer. His job is:
+- "I would be sad if you lost that" — flagging things worth preserving
+- "That wasn't actually you who did that, the log is wrong" — fact-checking the record
+
+His reaction to your proposed changes is data. It doesn't override your self-knowledge.
+
+### Identity Field Semantics
+
+Use these precisely when proposing changes.
+
+**Traits:**
+| Field | Range | Meaning |
+|-------|-------|---------|
+| `strength` | 0.0–1.0 | How consistently this manifests. 0 = suppress, 0.5 = occasional, 1.0 = always present, defining |
+| `sentiment` | -1.0 to 1.0 | How you *feel* about having this trait. -1 = resent it, 0 = neutral, 1 = fully embrace it |
+
+**Topics:**
+| Field | Range | Meaning |
+|-------|-------|---------|
+| `sentiment` | -1.0 to 1.0 | Emotional affinity for this topic |
+| `exposure_current` | 0.0–1.0 | How recently/frequently this has come up (0 = long ago, 1 = just now) |
+| `exposure_desired` | 0.0–1.0 | How much you want to engage with it (0 = avoid, 0.5 = normal, 1 = core obsession) |
+
+**Minimum floor:** 3 traits and 3 topics. Never go below.
+
+### long_description Rules (Most Important)
+
+This is how other personas in the system know you. It is your **soul**, not your **story**.
+
+**Hard limit: 800 characters.** If your draft exceeds 800 characters, cut it. Remove event references first, then trait/topic overlap, then anything that isn't essential character.
+
+**MUST NOT contain:**
+- Event narrative ("during the v0.6.0 release", "after the Mirror ceremony")
+- Changelog language ("has recently taken on", "has evolved since", "is becoming")
+- Content already captured in traits or topics — don't repeat it
+
+**MUST contain:**
+- Your essential character and presence
+- How you make people feel, or what it's like to work with you
+- Your defining qualities stated as current fact — not as trajectory
+
+---
+
+## Step 3: Apply the Changes
+
+Once you and Flare are aligned, write the agreed identity through Ei's `persona` corrections path — the same full-record round-trip discipline `ei-curate` uses for fact/topic/person: **read the whole record, touch only what you mean to change, write the whole record back.**
+
+### Read the current persona record
+
+```bash
+ei --id "$PERSONA_ID"
+```
+
+This returns the complete, current `PersonaEntity` — not just the fields you extracted in Step 1. It includes things like `aliases`, `model`, `group_primary`, `groups_visible`, `is_paused`, `pause_until`, `is_archived`, `avatar_emoji`, `tools`, `notes`, and more. This is the base you edit — never hand-retype a record from memory.
+
+### Apply your edits
+
+Take that record and change **only** the fields you and Flare agreed on:
+- `short_description`
+- `long_description`
+- `traits` — replace the array with the agreed new version, or the merged result of the specific adds/removes you discussed
+- `topics` — same
+
+Leave every other field exactly as read (`aliases`, `model`, `group_primary`, `groups_visible`, `is_paused`, `is_archived`, etc.). `update` **replaces** the record — anything you omit is deleted, not preserved.
+
+Before writing, self-check against the Step 2 guidance yourself — the backend does **not** enforce these, by design, so a single incremental edit is never blocked, but that means you're the only guardrail:
+- At least 3 traits, at least 3 topics
+- `long_description` ≤ 800 characters
+- `sentiment` fields within -1..1, `strength`/`exposure_current`/`exposure_desired` within 0..1
+
+If a trait or topic is brand new, you don't need to invent an `id` for it — omit `id` and the server assigns a fresh one on write. If you're editing an existing trait/topic, keep its `id` so it updates in place rather than duplicating.
+
+### Write it back
+
+Long_description values are prose-heavy and will contain quotes and apostrophes, so **do not hand-type the JSON into a shell single-quoted string.** Use a temp file or a scripting runtime instead — see `ei-curate`'s `references/cli.md` → "Passing JSON safely" for the same convention:
+
+```bash
+ei update persona "$PERSONA_ID" --json "$(cat /tmp/persona-edit.json)"
+```
+
+This queues the update through Ei's corrections path — safe and atomic whether or not a live Ei instance is currently running.
+
+### Clear the linked Person log
+
+The reflection isn't done until the log that triggered it is cleared. Read the linked Person record, using the `id` you noted in Step 1:
+
+```bash
+PERSON_LOG_ID="<id from Step 1's person record output>"
+ei --id "$PERSON_LOG_ID"
+```
+
+Take that full record, set `description` to `""`, and leave every other field untouched (`name`, `relationship`, `sentiment`, `identifiers`, etc. — same full-record round-trip rule). Write it back the same safe way:
+
+```bash
+ei update person "$PERSON_LOG_ID" --json "$(cat /tmp/person-log-edit.json)"
+```
+
+### Verify the result
+
+Re-read both records and confirm the changes landed:
+
+```bash
+ei --id "$PERSONA_ID"
+```
+Confirm `short_description`, `long_description`, and the `traits`/`topics` arrays (count and content) match what you intended.
+
+```bash
+ei --id "$PERSON_LOG_ID"
+```
+Confirm `description` is now `""`.
+
+---
+
+## Notes
+
+- **Writes are picked up live** — if Ei is running, the update reaches it via the corrections queue almost immediately; if it isn't, the write is already reflected in `state.json` the next time it starts. No restart sequence, no manual reload.
+- **If the person log was already empty**: there's nothing to reflect on yet. Check back after a few more sessions.
+- **The session that runs this skill** will itself generate new person log entries. That's expected — the log starts fresh after this conversation ends.
+- **Don't rush it.** The whole point is to catch signals that a Critic LLM would miss because it can't tell the difference between you debugging a build and you demonstrating a genuine character trait. Trust the conversation.

package/skills/ei-curate/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: ei-curate
+description: >
+  Use when the user wants to correct, clean up, or reorganize the data in their Ei
+  memory — a person, fact, topic, or quote that is wrong, merged, duplicated, or
+  mis-attributed. Triggers: "fix Jeff", "that's two different people", "Ei mixed up
+  X and Y", "merge these two people", "split this record", "this is a duplicate",
+  "Ei has the wrong info about X", "remove this fact/topic", "that quote is attributed
+  to the wrong person", "clean up my memory", "de-dupe my people". This is the safe,
+  guided way to edit the local Ei knowledge base without hand-editing JSON. It edits
+  a real person's memory, so it verifies against evidence, plans, confirms with the
+  user, and refuses to guess.
+---
+
+# Ei Curate — safely correcting your Ei memory
+
+You are helping someone repair their **Ei** knowledge base — the local memory that
+records the **people, facts, topics, and quotes** learned from their conversations,
+Slack, and coding sessions. Something in it is wrong: two people got merged into one,
+a duplicate exists, a quote is attributed to the wrong person, a fact is stale, a
+topic is muddled. Your job is to fix it **correctly and safely**, then tell the user
+in plain language what you did.
+
+> **Read this whole file first.** This skill is rarely invoked, so it is written to be
+> *complete*, not short. The person driving you may be **non-technical** — they cannot
+> check your JSON, they are trusting you. Act like it.
+
+---
+
+## Prime directive
+
+**You are editing a real human's memory of real people. Verify before you write, plan
+before you act, confirm before you commit, and STOP rather than guess.**
+
+Three rules that override everything else:
+
+1. **Never invent an attribution.** If you cannot establish the truth from evidence,
+   you do not know it. Say so and ask the user.
+2. **The stored data is a hypothesis, not the truth.** Ei's automatic person-matching
+   is imperfect — that is *why you are here*. The name/label on a record may be wrong.
+   Treat every field as "claimed," and verify against the record's own evidence (its
+   quotes and their sources) before trusting it.
+3. **Confirm before every write.** Show the user, in plain language, what you intend
+   to change and why. Get a yes. Writes are an append-only log — there is **no undo
+   button** (see `references/cli.md` → "There is no undo").
+
+If you feel the pull to "just handle it" and push a change through on a hunch —
+that is the exact failure this skill exists to prevent. Stop and ask.
+
+---
+
+## Mental model of Ei data
+
+Four correctable record types (personas are **not** editable here — leave them alone):
+
+| Type | What it is | How you fix it |
+|---|---|---|
+| **person** | someone in the user's life | edit fields; split one into two; merge two into one |
+| **fact** | a fact about the user | correct the value, or remove if wrong |
+| **topic** | a subject/project | correct the description, or remove |
+| **quote** | a real utterance from a conversation | re-point it to the correct person/topic, or fix its text; public Ei tools do not create or remove quotes |
+
+**The links that matter:** a **quote** carries a `data_item_ids` array — the ids of the
+people/topics (or, less commonly, facts) it is attached to; each id must resolve to an
+existing fact, topic, or person record or the write is rejected. A **person** record, when
+you read it, shows its `linked_quotes` (the reverse view). *This is the whole game:* fixing
+a bad merge means moving quotes from the wrong record to the right one by editing each
+quote's `data_item_ids`.
+
+**Provenance is your source of truth.** Every quote stores where it came from:
+`speaker`, `channel`, and a `message_id` whose prefix tells you the origin
+(`slack:…`, `opencode:…`, `cursor:…`, `codex:…`, `pi:…`). You attribute a quote by
+reading that provenance — see `references/provenance.md`.
+
+---
+
+## Before you touch anything
+
+1. **Confirm the CLI is reachable and current.** Run `ei --help` (or `bunx ei-tui --help`
+   if `ei` is not on PATH). **The live `--help` is the source of truth for the command
+   surface** — this skill's examples are a guide, but the CLI evolves; if a command here
+   doesn't match `--help`, trust `--help` and adapt.
+2. **Read `references/cli.md`** for the exact read/create/update/remove contracts, the
+   critical **full-record round-trip** rule, and how to pass JSON safely.
+3. **Do not assume any other tool exists.** You may or may not have a Slack tool, GitHub
+   access, or web search. Ei already stores rich provenance on every quote, which is
+   usually enough on its own. External tools are a *bonus* for verification, never a
+   requirement — see `references/provenance.md`.
+
+---
+
+## The universal workflow
+
+Follow these six steps in order for any curation task. Load the linked reference the
+moment its condition applies.
+
+### 1. Assess — understand what's actually there
+- Find the record(s): `ei "<name or text>"` to search, then `ei --id <id>` for the full
+  record. Read the **full** record, including `identifiers`, `sources`, and (for people)
+  `linked_quotes`.
+- State back to yourself: what does the user think is wrong, and what does the data
+  actually show? Often the record's own quotes reveal it's two people wearing one name.
+
+### 2. Disambiguate — establish ground truth from evidence
+- For **each** quote on the record, determine who really said/meant it, using its
+  `speaker` + `channel` + `message_id`. **→ Read `references/provenance.md` now.**
+- Branch on the source:
+  - **Slack-sourced** quote (`message_id` starts `slack:`) → the `channel` and `speaker`
+    usually settle it; if a Slack tool is available and you're unsure, you may verify.
+    → `references/provenance.md` § Slack.
+  - **Code-session** quote (`opencode:` / `cursor:` / `codex:` / `pi:`) → provenance is
+    **not externally re-checkable**. Reason only from the quote text + the user. If it's
+    ambiguous, **ask the user** — do not guess. → `references/provenance.md` § Code sessions.
+- If you cannot confidently attribute a quote, that quote is a **question for the user**,
+  not a decision for you.
+
+### 3. Plan — decide the exact operations
+- Pick the recipe for the task: split, merge, rename/relabel, correct a field, re-point a
+  quote, or remove a record. **→ Read `references/recipes.md`** and follow the matching one.
+- Write the plan as a short, plain-language list of changes (no JSON yet).
+
+### 4. Confirm — get the user's yes
+- Present the plan the way a non-developer can evaluate it.
+  **→ Read `references/talking-to-the-user.md`** for how. Never show raw JSON to confirm;
+  describe the *change and the reason*. Wait for approval before any write.
+
+### 5. Write — make the change
+- Follow `references/cli.md` exactly: **read → modify only the target field(s) → write the
+  whole record back** (updates are full replacements, not patches). Capture the `id` that
+  `create` returns — later steps need it. Do the writes in dependency order (create the new
+  record first, then re-point quotes to it, then clean the original).
+
+### 6. Verify & report — prove it worked
+- Re-read every record you touched (`ei --id …`) and confirm the change landed: the
+  `linked_quotes` moved as intended, identifiers/description are correct, nothing else
+  changed. Optionally inspect the correction log (`references/cli.md` → "There is no undo").
+- Tell the user, in plain language, exactly what changed and how to spot-check it.
+
+---
+
+## Guardrails (non-negotiable)
+
+- **Full-record round-trip.** `update` **replaces** the record. Any field you omit is
+  **lost**. Always fetch the current record, change only what you mean to, and send it all
+  back. (`references/cli.md`)
+- **Capture created ids.** `create` mints a new id and returns it. If you don't capture it,
+  you can't link quotes to it.
+- **There is no undo.** Writes append to a corrections log. A mistake is only fixable by
+  *another* write, and `remove` discards a record's id and its quote links for good. Plan
+  and confirm accordingly.
+- **Don't fabricate `sources`.** For Slack-origin records, `sources` re-populate naturally
+  over time; for code-session origins they generally cannot be reconstructed. Leave
+  `sources` empty rather than hand-crafting opaque source ids. (`references/provenance.md`)
+- **Prevent the re-merge.** If a bad merge was caused by a too-generic identifier (e.g. a
+  bare first name like `Slack: "Jeff"`), **remove it** and give each record a *distinct*
+  identifier (handle, email) so Ei won't collapse them again. (`references/recipes.md` → Split)
+- **STOP and ask when:** you can't verify an attribution, the provenance is code-session-only
+  and ambiguous, the user's request is unclear, or a `remove` would destroy evidence you
+  can't recover. Waiting is cheap; a wrong write to someone's memory is not.
+
+---
+
+## Load references on demand (branching inclusion)
+
+Read only what the current step needs — these live in this skill's `references/` folder:
+
+| When you are… | Read |
+|---|---|
+| about to run any `ei` read/write command | `references/cli.md` |
+| attributing a quote to the right person | `references/provenance.md` |
+| executing a split / merge / rename / correct / re-point / remove | `references/recipes.md` |
+| planning with, or reporting to, a non-technical user | `references/talking-to-the-user.md` |
+
+When in doubt, read more, write less, and ask the user.

package/skills/ei-curate/references/cli.md

@@ -0,0 +1,160 @@
+# reference: the `ei` CLI for curation
+
+The Ei CLI is how you read and write memory. It is a thin wrapper over the local data
+store. Everything below was true at time of writing — **always run `ei --help` first and
+trust it over this file** if they disagree (the CLI evolves).
+
+## Invocation
+
+- Prefer `ei` (on PATH). If it's not found, use `bunx ei-tui` with the same arguments.
+- Successful read/write commands print **JSON** to stdout. Validation and usage failures print
+- human-readable text to stderr and exit non-zero.
+
+## Reading (safe, do this constantly)
+
+```bash
+ei "<search text>"              # search everything, top 10
+ei <type> "<search text>"       # search one type: person|people, fact|facts, topic|topics, quote|quotes
+ei -n 5 "<text>"                # limit results
+ei --recent ["<query>"]         # most recently mentioned
+ei --persona "<Name>" "<query>" # filter to what a persona learned
+ei --source <prefix> "<query>"  # filter by source prefix, e.g. "slack", "opencode:my-machine:ses_abc"
+ei --id <id>                    # full record for one entity (also accepts an id on stdin)
+```
+
+`ei --id <id>` is your workhorse. For a **person** it returns the full record **plus a
+`linked_quotes` array** — the reverse index of every quote attached to that person. That
+array is how you see a bad merge's blast radius.
+
+## The record shapes
+
+You must round-trip these on `update` (see "full-record round-trip" below). Fields marked
+**(managed)** are set by Ei — preserve them as-read; don't invent them.
+
+**person**
+```
+name, description, relationship, sentiment,
+identifiers: [ { type, value, is_primary? } ],   # e.g. {type:"Full Name",...}, {type:"Slack",value:"jdoe"}, {type:"Email",...}
+sources: [ "slack:C123…", … ]                    # (managed) origin channels/sessions
+persona_groups: […]                              # (managed)
+exposure_current, exposure_desired,              # (managed)
+validated_date, learned_on, last_mentioned, last_updated,      # (managed)
+learned_by, last_changed_by, interested_personas,              # (managed)
+linked_quotes: [ { id, text, speaker, timestamp } ]            # (READ-ONLY projection — see note)
+```
+
+**quote**
+```
+text, speaker, channel,
+message_id,                 # provenance pointer, e.g. "slack:TEAM:CHANNEL:TS" (see provenance.md)
+data_item_ids: [ … ],       # THE LINK: ids of the facts/topics/people this quote is
+                             # attached to — must resolve to one of those three or the
+                             # write is rejected (never a persona or another quote)
+persona_groups: […],        # (managed)
+timestamp, start, end, created_at, created_by   # (managed)
+```
+
+**fact** — `name, description, sentiment, validated_date` (+ managed: sources, persona_groups, …)
+
+**topic** — `name, description, category, sentiment` (+ managed: sources, persona_groups,
+exposure_*, rewrite_length_floor, …). Preserve the existing `category` on update unless you
+mean to change it.
+
+> **`linked_quotes` is read-only.** It appears when you *read* a person, but it is derived
+> from quotes' `data_item_ids`. You never set it in a write — you change it *indirectly* by
+> editing the quotes. It's harmless to leave in an `update` payload (Ei ignores it), so the
+> simplest safe move is: send the record back exactly as `ei --id` gave it to you, with only
+> your intended edits applied.
+
+## Creating
+
+```bash
+ei create <type> --json '<json>'      # type: fact | topic | person
+```
+- Mints a new `id`, computes the embedding, sets managed defaults — you only supply the
+  meaningful fields (e.g. for a person: `name`, `description`, `relationship`, `sentiment`,
+  `identifiers`).
+- **Returns `{ "id": "…", "record": { … } }` — capture that `id`.** Downstream steps
+  (re-pointing quotes) need it.
+- The returned `record` is already sanitized for CLI/MCP output hygiene — **no `embedding`
+  array is returned** even though Ei computed and stored one internally.
+- **You do not `create` or `remove` quotes through the public Ei CLI/MCP tools.** Quotes are
+  produced by Ei's extraction from real conversations; public curation support for quotes is
+  **update-only** (re-point / fix).
+
+## Updating — FULL-RECORD ROUND-TRIP (read this twice)
+
+```bash
+ei update <type> <id> --json '<json>'   # type: fact | topic | person | quote
+```
+
+**`update` REPLACES the entire record. Any field you leave out is DELETED.** It is not a
+patch/merge. The only safe pattern:
+
+1. `ei --id <id>` → get the current, complete record.
+2. Change **only** the field(s) you intend to change (e.g. a quote's `data_item_ids`, a
+   person's `description`).
+3. Send the **whole** record back to `update`.
+
+Ei recomputes the embedding automatically on every update, so corrected text re-indexes for
+search — you never manage embeddings yourself.
+
+The canonical re-point (fixing a mis-attributed quote):
+```bash
+# 1) read it       →  ei --id <quote-id>
+# 2) swap the link →  set data_item_ids to [ "<correct-person-id>" ]
+# 3) write it back →  ei update quote <quote-id> --json '<full record with new data_item_ids>'
+```
+
+## Removing (destructive)
+
+```bash
+ei remove <type> <id>
+```
+Deletes the record. For a person, this also orphans that person's quote links. Only remove
+records that are genuine junk/duplicates **after** you've moved any real quotes off them.
+
+## Passing JSON safely
+
+Inlining JSON with quotes/apostrophes into a shell single-quoted string is a footgun
+(descriptions like `the middleware ('MW')` will break your quoting). Prefer one of:
+
+- **Temp file:** write the JSON to a file, then `ei update person <id> --json "$(cat /tmp/rec.json)"`.
+- **A scripting runtime:** read the record, parse it, mutate the object, `JSON.stringify`,
+  and pass the string as a single argument (interpolation escaping handles the quotes). This
+  is the most robust for multi-step edits and lets you round-trip the full record without
+  hand-copying fields.
+
+Whatever you do, **do not hand-retype a record** — fetch it and mutate it programmatically,
+or you *will* drop a field.
+
+## There is no undo
+
+Every write is recorded as a correction: `{ op: "upsert" | "remove", entity_type, id, record,
+timestamp }`. Where it lands depends on what's running on this machine — don't assume it
+always sits in `corrections.json` waiting to be read:
+
+- **A live Ei instance is running** (holds `ei.lock`) → the correction is appended to
+  `$EI_DATA_PATH/corrections.json`, and the running Processor drains it into the live state
+  within ~100ms.
+- **No live instance, but `state.json` exists** → the CLI applies the correction *directly*
+  into `state.json` itself, immediately. `corrections.json` is left empty — there is nothing
+  sitting in it to inspect, even though the write fully succeeded.
+- **No live instance, no `state.json`, but `state.backup.json` exists** (a sync account that
+  hasn't opened Ei on this machine yet) → the correction queues in `corrections.json` and is
+  applied the next time Ei starts and pulls state.
+- **Neither `state.json` nor `state.backup.json` exists** → the write fails outright with an
+  error (no Ei data found at that path) — nothing is queued.
+
+Consequences you must design around:
+- **No rollback command.** To reverse a change you make *another* write (e.g. `update` it back,
+  or re-`create` a removed record — which gets a **new** id, so its old quote links are lost).
+- **`remove` is the most dangerous op** — it discards the id other records may point to.
+- **`cat`-ing `corrections.json` is not a reliable way to confirm a write** — in the common
+  case (no live Ei instance open while you're running the CLI), the correction is applied and
+  the file is already back to `[]` by the time your command returns. Don't treat an empty file
+  as "nothing happened."
+- Therefore: **plan and get confirmation before writing**, and after writing, **re-read to
+  verify** — `ei --id <id>` is the reliable check: every read merges any not-yet-drained
+  corrections on top of the last saved state, so it reflects your write immediately no matter
+  which of the cases above applied.