ei-tui 1.6.8 → 1.7.0

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

@@ -0,0 +1,265 @@
+# reference: the `ei` CLI for persona authoring
+
+The Ei CLI is how you read and write personas. 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 persona "<Name>"             # find a persona by name — substring match on display_name,
+                                 # falls back to semantic search over long_description
+ei --id <id>                    # full record for one entity, including a persona
+```
+
+`ei persona "<Name>"` (the type-specific search, not the `--persona` filter flag) is how you
+find a persona by name. **`--persona "<Name>"` is a different feature** — it filters *other*
+entity types (facts/topics/people) down to what a named persona has learned; it never returns
+personas themselves, so it cannot be used to find one.
+
+`ei --id <id>` is your workhorse once you have the id. For a persona it returns the **full**
+record: identity fields, every entry in `traits[]` and `topics[]`, and the lifecycle flags.
+Always read the full record before writing — you cannot safely change one field of a persona
+without seeing the rest (full-record round-trip, below).
+
+## The persona record shape
+
+You must round-trip this on `update` (see "full-record round-trip" below). The writable
+surface is:
+
+```
+display_name,                          # required, non-empty; also checked against the
+                                        # reserved-name list (see below) on both create and update
+aliases: [ "…" ],                      # for fuzzy matching (e.g. "/persona Bob")
+short_description, long_description,
+model,
+group_primary, groups_visible: […],
+traits: [ PersonaTrait, … ],
+topics: [ PersonaTopic, … ],
+is_paused, pause_until,
+is_archived, archived_at,              # setting is_archived is how you archive/unarchive —
+                                        # there is no separate archive verb
+heartbeat_delay_ms, context_window_ms,
+include_message_timestamps, context_boundary,
+tools: { "<Provider>": { "<Tool>": true|false } }, # a map (not an id list) of every tool
+                                        # on every currently-enabled provider — see "Tool
+                                        # grants" below (not related to your own tool access)
+avatar_emoji, avatar_image,
+preferred_theme,
+notes: [ "…" ],                        # capped at 20 entries server-side — a write that
+                                        # pushes the array past 20 is rejected
+```
+
+**`PersonaTrait`** — a named character trait:
+```
+id,            # optional on write — see "auto-assigned ids" below
+name,
+description,
+sentiment,     # -1.0 to 1.0
+strength,      # optional, 0.0 to 1.0
+```
+
+**`PersonaTopic`** — a subject the persona has a stance on:
+```
+id,               # optional on write — see "auto-assigned ids" below
+name,
+perspective,      # their view/opinion on this topic
+approach,         # how they prefer to engage with it
+personal_stake,   # why it matters to them personally
+sentiment,        # -1.0 to 1.0
+exposure_current, # 0.0 to 1.0 — how recently/frequently it's come up
+exposure_desired, # 0.0 to 1.0 — how much they want to engage with it
+```
+
+**Auto-assigned ids.** If a trait or topic in your payload has no `id`, the server
+assigns a fresh one before persisting — the same way the top-level persona `id` is
+assigned on create. You never need to invent a UUID for a brand-new trait or topic;
+just omit `id` and let it be minted.
+
+**No minimum count.** Nothing here enforces a minimum number of traits or topics. (The
+reflection ceremony's own convention of "at least 3 traits, at least 3 topics" is guidance
+inside a *different* skill for a *different* situation — it is not a rule this path
+enforces. Adding a single trait to an otherwise-untouched persona is a completely valid
+edit.)
+
+**Server-managed, not part of the writable surface.** Fields set by Ei — read them,
+don't invent or hand-edit them:
+- `id`, `entity`, `last_updated`, `last_heartbeat`, `last_extraction`,
+  `description_embedding`, `pending_update`, `reflection_last_asked` — silently stripped
+  and ignored if present in an `update` payload (the natural result of round-tripping a
+  read), never a validation error.
+- `is_static` — marks built-in structural personas; not writable through this path at all.
+  Don't try to flip it.
+
+**Reserved names.** `display_name` is checked against a reserved-word list (currently
+`new`, `clone` — command keywords that collide with `/persona` subcommands) on **both**
+`create` and `update`. Renaming an existing persona *into* a reserved name is rejected
+exactly like creating one with that name.
+
+## Tool grants (`tools`)
+
+`tools` is a **map you read, flip, and write back** — not a list of ids you have to know
+in advance, and there's no separate step to enumerate what exists: a read of the persona
+**is** the live menu of what's grantable right now. A real read looks like this:
+
+```json
+{
+  "Ei Built-ins": { "Web Fetch": false, "Find Memory": true },
+  "Spotify": { "Currently Playing Track": false, "Liked Songs": false }
+}
+```
+
+- **Outer keys** are provider display names — but only for providers that are currently
+  **enabled**. A disabled provider (e.g. Spotify before the human finishes OAuth) does not
+  appear in the map at all — not present-with-everything-false, just absent. Its tools stay
+  invisible, and ungrantable, until the human enables it.
+- **Inner keys** are every tool belonging to that enabled provider, `true` if **this
+  persona** currently has it granted, `false` if not.
+- This has nothing to do with whatever tools *you* (the agent reading this file, via MCP or
+  any other mechanism your own harness uses) have access to. A `true` here means: the next
+  time a **human** talks to **that persona** inside Ei's TUI or web client, the persona may
+  call that tool mid-conversation.
+- Trust the map from a fresh read over anything written down anywhere, including this file
+  — the set of providers and tools can change over time.
+
+### Writing (grant/revoke)
+
+`create`/`update` take the **exact same map shape** back — the full-record round-trip rule
+(below) applied to `tools` specifically:
+
+1. Read the persona; look at its `tools` map.
+2. Flip the one boolean you mean to change (`false → true` to grant, `true → false` to
+   revoke).
+3. Send the **whole** map back, inside the whole record, unchanged apart from that flip.
+
+A key you omit from the map isn't "left unchanged" the way a patch would treat it — but
+since a disabled provider was never in your read to begin with, everything you can see on a
+read is everything you round-trip; there's no hidden state you can accidentally drop.
+
+**An unresolvable provider or tool display name is rejected, not a silent no-op.** If a name
+in your write payload doesn't match anything real — a typo, a renamed tool, a provider that
+no longer exists — the write fails with a clear validation error; it does not silently
+ignore the bad key and apply the rest. **Never hand-retype a provider or tool name from
+memory** — only use names that came from an actual read of this exact persona.
+
+**A grant under a currently-disabled provider survives your update automatically — you don't do anything for this to happen.** If this persona already has a tool granted under a provider that's disabled right now, that grant isn't in your read and doesn't belong in your write either, and it stays intact across the update regardless. Do **not** try to guess-reconstruct a disabled provider's block from memory to "preserve" it — you have no way to know what it actually contains, and a fabricated one is indistinguishable from inventing a brand-new grant under an unknown/disabled provider, so it gets rejected the same way. The rule stays simple: for every provider you *can* see, write back exactly what you read, edited only where you meant to edit; every provider you can't see isn't yours to touch, in either direction. This is not the same as revocation — flipping a visible tool's boolean to `false`, or leaving it out of an otherwise-included enabled provider's block, still removes it for real. Auto-preservation only ever applies to a provider that's invisible to you to begin with.
+
+## Creating
+
+```bash
+ei create persona --json '<json>'
+```
+- You supply the meaningful fields (at minimum `display_name`); everything else server-
+  managed gets sensible defaults, `id` is minted, traits/topics missing an `id` get one
+  assigned.
+- **Returns `{ "id": "…", "record": { … } }` — capture that `id`.**
+- The returned `record` is sanitized for CLI/MCP output hygiene — no `description_embedding`
+  is returned even though Ei computed and stored one internally.
+- This path does **not** trigger any automatic identity-generation job — you (and the user)
+  are authoring the full identity yourselves; there's no "fill in the rest for me" fallback.
+  If the user wants a persona with more character than they've specified, work it out with
+  them in step 3 (Plan) before you write, not by inventing details silently.
+
+## Updating — FULL-RECORD ROUND-TRIP (read this twice)
+
+```bash
+ei update persona <id> --json '<json>'
+```
+
+**`update` REPLACES the entire record. Any field you leave out is DELETED.** It is not a
+patch/merge. This applies to `traits[]` and `topics[]` as whole arrays too — if you send
+back a `traits` array with 3 of the persona's 4 traits, the 4th is gone. 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. append one entry to `traits`,
+   tweak one topic's `sentiment`, rewrite `long_description`).
+3. Send the **whole** record back to `update`.
+
+Ei recomputes the description embedding automatically on every update — you never manage
+it yourself.
+
+The canonical "add a trait":
+```bash
+# 1) read it        →  ei --id <persona-id>
+# 2) append          →  push a new { name, description, sentiment, strength? } onto
+#                        traits (no id needed — it's auto-assigned), leaving every
+#                        existing trait and everything else untouched
+# 3) write it back   →  ei update persona <persona-id> --json '<full record with new trait appended>'
+```
+
+## Removing (destructive)
+
+```bash
+ei remove persona <id>
+```
+Deletes the persona record permanently.
+
+**Reserved personas (`ei`, `emmet`) cannot be deleted.** This is checked
+**synchronously, before the correction is ever queued** — you get an immediate error,
+not a silent no-op some time later:
+```
+Cannot delete reserved persona "<id>". Use archive instead.
+```
+If a user wants to "get rid of" Ei or Emmet, that means **archive**, not delete:
+```bash
+ei update persona <id> --json '<full record with "is_archived": true>'
+```
+Non-reserved personas have no such restriction — `remove` deletes them outright. Confirm
+the user means "permanently gone," not "hide it" (archive is the reversible option for
+*any* persona, reserved or not — see `references/recipes.md`).
+
+## Passing JSON safely
+
+Inlining JSON with quotes/apostrophes into a shell single-quoted string is a footgun
+(descriptions like `the middleware ('MW')`, or a Yoda-style `long_description` full of
+inverted syntax and dashes, will break your quoting). Prefer one of:
+
+- **Temp file:** write the JSON to a file, then
+  `ei update persona <id> --json "$(cat /tmp/rec.json)"`.
+- **A scripting runtime:** read the record, parse it, mutate the object (e.g. push a new
+  trait, edit one field), `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 trait or field.
+
+## There is no undo
+
+Every write is recorded as a correction: `{ op: "upsert" | "remove", entity_type: "persona",
+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 persona — which gets a **new** id, so it's a different
+  persona as far as the rest of the system is concerned).
+- **`remove` is the most dangerous op** — for a non-reserved persona it succeeds
+  immediately and is permanent. For a reserved persona it's rejected outright (see above).
+- **`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.

package/skills/ei-persona/references/recipes.md

@@ -0,0 +1,247 @@
+# reference: persona-authoring recipes
+
+Pick the recipe that matches the task. Every recipe assumes you have already **found and
+read** the persona's full record, and that you will **confirm with the user**
+(`references/talking-to-the-user.md`) before writing and **verify** after. All writes
+follow the full-record round-trip rule in `references/cli.md`.
+
+Command mechanics live in `references/cli.md`; this file is the *sequence and judgment*
+for each operation.
+
+---
+
+## Recipe A — Add a trait
+
+**Symptom:** "give [persona] a new trait about being sarcastic" / "make Ei more playful"
+translated into a concrete new character trait.
+
+**Steps:**
+
+1. `ei --id <persona-id>` → read the full record. Look at the existing `traits[]` so the
+   new one doesn't duplicate or contradict one that's already there.
+2. Turn the request into a concrete trait: a short `name`, a `description` of what it
+   looks like in behavior (not just a label), a `sentiment` (-1..1, how the persona feels
+   about having it), and optionally a `strength` (0..1, how consistently it shows up). If
+   the user's request is vague ("sarcastic"), propose the concrete wording and get their
+   yes before writing — don't silently decide how sarcastic is "sarcastic."
+3. Append the new trait object to the existing `traits[]` array — **don't invent an
+   `id`**, it's auto-assigned. Leave every other trait, and every other field, untouched.
+4. `ei update persona <persona-id> --json '<full record with the trait appended>'`.
+5. Verify: re-read, confirm the new trait is present with the values you intended and
+   every prior trait is still there.
+
+---
+
+## Recipe B — Adjust a trait's strength, sentiment, or description
+
+**Symptom:** "[persona] should be more/less sarcastic" for a trait that already exists, or
+"the sarcasm trait's description doesn't feel right anymore."
+
+**Steps:**
+
+1. `ei --id <persona-id>` → read. Find the matching entry in `traits[]` by name.
+2. Change only the field(s) that need to change on that one trait object — `strength`
+   and/or `sentiment` (both stay within their bounds, -1..1 for sentiment, 0..1 for
+   strength) and/or `description`. Leave `id` and `name` as-is unless the user explicitly
+   wants a rename.
+3. `ei update persona <persona-id> --json '<full record with only that trait changed>'`.
+4. Verify the read-back shows the new value and every other trait unchanged.
+
+---
+
+## Recipe C — Remove a trait
+
+**Symptom:** "[persona] shouldn't be so formal anymore" meaning a trait should go away
+entirely, not just weaken.
+
+**Steps:**
+
+1. `ei --id <persona-id>` → read.
+2. Build the new `traits[]` array with that one entry filtered out — everything else in
+   the array, and the rest of the record, unchanged.
+3. `ei update persona <persona-id> --json '<full record with the trait removed>'`.
+4. Verify: re-read, confirm the trait is gone and nothing else moved.
+
+> If you're not sure whether the user wants the trait **gone** or just **weaker**, ask —
+> Recipe B (weaken) and Recipe C (remove) are different edits.
+
+---
+
+## Recipe D — Add / adjust / remove a topic
+
+**Symptom:** "[persona] should care about X" (add), "[persona]'s take on X has changed"
+(adjust), or "[persona] shouldn't talk about X anymore" (remove/reduce).
+
+Topics are the persona's *stance* on a subject — `perspective`, `approach`,
+`personal_stake`, `sentiment`, `exposure_current`, `exposure_desired` — not just a label,
+so a "shouldn't talk about X" request usually means one of two different things: **remove
+the topic** entirely, or **lower `exposure_desired`** so the persona still holds the
+opinion but doesn't bring it up. Ask which the user means if it's not obvious.
+
+**Add:**
+1. `ei --id <persona-id>` → read.
+2. Build the new topic: `name`, `perspective` (their view), `approach` (how they engage
+   with it), `personal_stake` (why it matters to them), `sentiment` (-1..1),
+   `exposure_current` and `exposure_desired` (both 0..1). No `id` needed — auto-assigned.
+3. Append to `topics[]`, leaving everything else untouched.
+4. `ei update persona <persona-id> --json '<full record with the topic appended>'`.
+5. Verify.
+
+**Adjust:** same shape as Recipe B, applied to the matching entry in `topics[]` — change
+only the field(s) that need to change (commonly `sentiment`, `exposure_desired`, or the
+prose fields), preserve `id`.
+
+**Remove:** same shape as Recipe C, applied to `topics[]`.
+
+---
+
+## Recipe E — Rewrite short/long description
+
+**Symptom:** "make Ei talk like Yoda" and similar — a request that changes *how the
+persona presents itself* at the character level, not just one trait.
+
+This is the recipe for the acceptance case of this skill: a broad character directive
+that mostly lands in `long_description` (and sometimes `short_description`), possibly
+alongside a trait or two.
+
+**Steps:**
+
+1. `ei --id <persona-id>` → read the full record, including current
+   `short_description`/`long_description` and existing `traits[]`/`topics[]`.
+2. Translate the directive into a concrete rewrite:
+   - "talk like Yoda" is primarily a **voice/manner** instruction — it belongs in
+     `long_description` ("speaks with inverted syntax, object before subject; sparse,
+     aphoristic; calls the user 'young padawan' or similar"), not a fabricated backstory.
+     Don't invent unrelated character facts (age, home planet, opinions) the user didn't
+     ask for.
+   - If the directive also implies a durable trait (e.g. "speaks in riddles" is arguably
+     a trait, not just a description line), you may propose adding one — but say so
+     explicitly when confirming, don't fold it in silently.
+   - Keep `short_description` a short label-level summary consistent with the new
+     `long_description`; update it too if the old one now reads as inconsistent (e.g. a
+     `short_description` of "concise and formal" contradicts a Yoda voice).
+3. Draft the new field value(s) and confirm with the user in plain language *before*
+   writing — this is a visible, felt change to how the persona talks, and it deserves a
+   clear description of the new voice, not raw text to approve blind.
+4. `ei update persona <persona-id> --json '<full record with only description field(s) changed>'`.
+5. Verify: re-read, and if you can, exercise the persona (or describe how the user can)
+   to confirm the new voice reads the way they wanted.
+
+---
+
+## Recipe F — Create a brand-new persona
+
+**Symptom:** "create a new assistant persona for me" / "I want a persona that specializes
+in X."
+
+**Steps:**
+
+1. Work out the essentials with the user first: `display_name` (checked against the
+   reserved-name list — can't be `new` or `clone`), and enough of a character brief to
+   write a `short_description`/`long_description` and a starting `traits[]`/`topics[]`
+   set. There is **no minimum count** and **no auto-generation fallback** on this path —
+   whatever character the persona has is whatever you and the user put in the payload.
+2. Draft the full creation payload: `display_name` plus whichever of
+   `short_description`, `long_description`, `traits`, `topics`, `model`, `group_primary`,
+   `groups_visible`, `tools` the user wants set at creation (for `tools`, see Recipe I
+   below and `references/cli.md`'s "Tool grants" section). Omit `id` on every trait/topic —
+   auto-assigned.
+3. Confirm the plan in plain language (name + character summary) before writing.
+4. `ei create persona --json '<payload>'` → **capture the returned `id`.**
+5. Verify: `ei --id <new-id>` and confirm the record matches what you intended. Tell the
+   user the persona now exists and how to reach it (e.g. `/persona <name>` if that's how
+   personas are selected in their client).
+
+---
+
+## Recipe G — Archive a persona (including a reserved one)
+
+**Symptom:** "archive Bob, I don't use him anymore" — or a user tries to "delete" Ei or
+Emmet and needs redirecting to the reversible option.
+
+**Steps:**
+
+1. `ei --id <id>` → read the full record.
+2. Set `is_archived: true` (and, if the shape calls for it, `archived_at` to the current
+   timestamp — otherwise leave managed timestamp fields as Ei set them). Change nothing
+   else.
+3. `ei update persona <id> --json '<full record with is_archived: true>'`.
+4. Verify: re-read, confirm `is_archived` is now `true`.
+5. Tell the user the persona is archived, not deleted — it can be brought back later by
+   setting `is_archived: false` the same way.
+
+Unarchiving is the same recipe in reverse: read, set `is_archived: false`, write, verify.
+
+---
+
+## Recipe H — Delete a persona (non-reserved only)
+
+**Symptom:** "delete the persona I made by accident."
+
+**Steps:**
+
+1. **Check whether it's reserved first.** If the target is `ei` or `emmet`, stop — this
+   recipe doesn't apply. Route to Recipe G (archive) and tell the user why: deleting a
+   reserved persona is rejected outright (`Cannot delete reserved persona "<id>". Use
+   archive instead.`), checked before the request is even queued.
+2. For a non-reserved persona: confirm with the user that they want it **permanently
+   gone**, not hidden — mention archive (Recipe G) as the reversible alternative, since
+   `remove` has no undo.
+3. `ei remove persona <id>`.
+4. Verify: `ei --id <id>` (or a search) no longer finds it.
+5. Tell the user it's gone, and that recreating a persona with the same name later gets a
+   **new** id — it will not be "the same" persona as far as anything that referenced the
+   old id is concerned.
+
+---
+
+## Recipe I — Grant or revoke a persona's tool access
+
+**Symptom:** "give DJ Spotify access so she can answer what she's listening to" / "let Ei
+search the web" / "[persona] shouldn't be able to read my files anymore."
+
+**Steps:**
+
+1. `ei --id <persona-id>` → read the full record. Look at the `tools` map — every tool
+   belonging to every currently-**enabled** provider, `true`/`false` for whether this
+   persona has it granted right now. This read **is** the full menu of what's grantable —
+   there's no separate enumeration step. A provider the human hasn't finished configuring
+   (e.g. Spotify before OAuth) simply won't appear in the map at all.
+2. Find the provider block and tool key matching what the user described — e.g. "Spotify"
+   → `"Currently Playing Track"`. If you don't recognize a capability the user named
+   anywhere in the map — including because the provider itself isn't in the map — say so
+   plainly (name what's missing) and ask what they meant. Don't guess a plausible-sounding
+   display name.
+3. Flip that **one** boolean — `false → true` to grant, `true → false` to revoke. Leave
+   every other entry in the map, and the rest of the record, exactly as you read it. (A
+   persona that has never had a Spotify tool before looks the same as any other case here:
+   its Spotify entries just read all-`false` until you flip the one the user asked for.)
+4. `ei update persona <persona-id> --json '<full record with that one tools entry
+   flipped>'`.
+5. Verify: re-read, confirm the entry you flipped shows the value you intended and every
+   other entry in `tools` — and every other field on the record — is unchanged. Tell the
+   user this only changes what **that persona** can do the next time a human chats with it
+   inside Ei's TUI or web client — it has no effect on your own tool access in this
+   session, or anything else about the current harness.
+
+> **An unresolvable provider or tool name is rejected, not a silent no-op.** If step 4
+> fails with a validation error, a name in your payload didn't match anything real — don't
+> retry with a guessed alternate spelling. Tell the user exactly what the error said, and
+> re-read the persona (step 1) to get the real names before trying again.
+
+---
+
+## If a write looks wrong afterward
+
+There's no undo, but the data isn't stuck — you fix a bad write with another write:
+- Wrong trait/topic value → `update` again with the correct full record.
+- Added the wrong trait → `update` again with it removed (Recipe C).
+- Removed something you shouldn't have → for a non-reserved persona, re-`create` it (note:
+  new id, and any prior references to the old id are gone). For a reserved persona this
+  never applies — you couldn't have deleted it in the first place.
+- Archived by mistake → set `is_archived: false` and write again.
+
+Re-read the persona with `ei persona "<name>" --id <id>` (or `ei --id <id>`) to verify what
+actually landed — don't rely on `corrections.json`. In the common case (no live Ei instance
+running), the write applies straight to `state.json` and `corrections.json` is immediately
+reset to `[]`, so it will often already be empty even after a fully successful write.

package/skills/ei-persona/references/talking-to-the-user.md

@@ -0,0 +1,107 @@
+# reference: working with a non-technical user
+
+The person asking you to change a persona's character may not be a developer. They
+cannot read JSON, they don't know what a "trait object" or an "id" is, and they should
+never have to. They think in **how the persona talks, what it's like, what it cares
+about** — talk to them in exactly those terms. Your competence shows up as *clarity and
+care*, not jargon.
+
+This matters because this skill is often the **only** way a non-technical person can
+shape a persona's identity. If you confuse or mislead them, they have no fallback.
+
+The judgment call here is different from `ei-curate`'s: there you were checking a plan
+*against evidence* ("does this match what actually happened?"). Here there's no evidence
+to check — you're checking a plan *against what the user asked for and whether it holds
+together as a coherent character* ("does this sound like what you meant, and does it fit
+the rest of who this persona is?").
+
+## Core rules
+
+1. **Never show raw records, JSON, ids, or embeddings.** Not to confirm, not to report.
+   They are noise to this user and erode trust ("I don't understand what you're showing
+   me").
+2. **Describe the character change, not the mechanism.** They care *what the persona will
+   be like afterward*, not which field or command you'll use.
+3. **Confirm before every write, in their language** — and when the request is vague,
+   turn it into something concrete *with them* before you write anything.
+4. **Flag incoherence, don't silently smooth it over.** If a requested change would clash
+   with something already on the record (a new "blunt and terse" trait next to an
+   existing "endlessly gentle" one, or a Yoda voice next to a `short_description` of
+   "concise corporate assistant"), say so and ask how they want it reconciled — don't
+   quietly overwrite the old trait or quietly leave the contradiction in place.
+5. **Report results as felt outcomes**, and tell them how to see/hear it for themselves.
+
+## Confirming a plan — translate before you ask
+
+Turn the operation into plain outcomes. For "make Ei talk like Yoda":
+
+> **Don't say:** "I'll `update` persona `ei`'s `long_description` field and append a new
+> entry to `traits`."
+>
+> **Say:** "I'll change how **Ei** talks: inverted sentence order, short and aphoristic,
+> the way Yoda speaks — while keeping Ei's actual personality and what Ei knows about you
+> the same underneath. I'll leave everything else about Ei untouched. Want me to go
+> ahead?"
+
+For a vague request, ask first instead of guessing:
+
+> "When you say make DJ 'more sarcastic' — do you mean sarcasm becomes DJ's default tone,
+> or more like an occasional dry aside? And is there anything DJ currently does that
+> should stay exactly the same?"
+
+Lead with what will change, name what stays the same, then ask. Short. No ids, no field
+names.
+
+## Confirming a create
+
+> "I'll create a new persona called **Nova** — a focused research assistant: direct,
+> skeptical of unverified claims, curious about edge cases. It won't know anything about
+> your other personas or their history; it starts blank. Sound right?"
+
+## Confirming an archive or delete
+
+Archive and delete read very differently to a non-technical user — make the distinction
+explicit every time, since "delete" is often used loosely to mean "I don't want to see it
+right now":
+
+> "I can either **archive** Bob (hides him, but you can bring him back later) or
+> **permanently delete** him (gone for good, and if you ever recreate a persona named Bob
+> it'll be a fresh one with no memory of this one). Which do you want?"
+
+If the target is a reserved persona (Ei, Emmet) and the user asked for delete:
+
+> "Ei can't be deleted outright — it's a built-in part of the system. I can **archive**
+> it instead, which hides it the same way delete would, without breaking anything. Want
+> me to do that?"
+
+## Reporting the result — outcome + how to check
+
+> "Done. Ei now speaks the way Yoda does — short, inverted, a little cryptic — while
+> everything else about Ei (what it knows about you, its other traits) is unchanged. Say
+> hello and you'll hear the difference right away."
+
+> "Done. DJ now has a new trait: dry, deadpan sarcasm, used often but not constantly. The
+> rest of DJ's personality is untouched."
+
+If you had to make a judgment call while translating a vague request into a concrete
+trait or description, name it: "I went with 'occasional dry aside' rather than
+'sarcastic by default' since you said you still wanted DJ to feel warm most of the time —
+let me know if that's not the balance you meant."
+
+## Being honest about limits (this builds trust, it doesn't erode it)
+
+- **No undo:** "There's no undo button on this, so I'll confirm with you before I change
+  anything — and if it doesn't land right, I can adjust it with another edit."
+- **Delete is permanent, archive isn't:** always offer archive as the reversible option
+  before a permanent delete goes through, for any persona.
+- **Reserved personas can't be deleted:** be upfront that Ei/Emmet redirect to archive,
+  and that this isn't a limitation you're imposing — it's a hard rule of the system.
+- **Partial fix:** if you changed most of what they asked but left something for them to
+  decide (an ambiguous instruction, a conflicting existing trait), say so plainly rather
+  than implying it's all done.
+
+## Tone
+
+Calm, plain, and precise. You're a collaborator helping someone design a character, not a
+database admin running migrations. Match their vocabulary, keep it short, and always
+leave them understanding exactly what the persona will be like now — and how to check.