ei-tui 1.6.8 → 1.7.0

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

@@ -0,0 +1,88 @@
+# reference: attributing a quote by its provenance
+
+Fixing a bad merge comes down to one question, asked once per quote: **who really said or
+meant this?** You answer it from the quote's stored provenance. Do **not** answer it from
+the (possibly wrong) name on the record you're fixing.
+
+Every quote carries three provenance fields:
+- `speaker` — who uttered it (a person's name, `"human"`, or a persona/agent name)
+- `channel` — the human-readable place it happened
+- `message_id` — a machine pointer whose **prefix names the origin system**
+
+## Read the `message_id` prefix first
+
+| Prefix | Origin | Externally re-checkable? |
+|---|---|---|
+| `slack:TEAM:CHANNEL:TS` | a Slack message | **Yes** — channel + speaker are strong signal; live lookup possible if you have a Slack tool |
+| `opencode:…` `cursor:…` `codex:…` `pi:…` | a coding-assistant session | **No** — you cannot re-derive a canonical identity from a transcript |
+| `ei:…` | Ei-internal (persona-authored) | n/a — not about an external person |
+
+The prefix decides your method and your confidence ceiling.
+
+---
+
+## § Slack-sourced quotes
+
+The stored `channel` and `speaker` usually settle attribution on their own:
+
+- **`speaker`** tells you who talked. If the speaker *is* the person you're sorting (e.g. a
+  quote spoken by "Jeff Kirk"), that's a strong direct signal.
+- **`channel`** tells you the context. A quote in `#akrochem-qa` about "Jeff's explanation"
+  is about the Jeff who lives in the Akrochem work — even if a *different* person said it.
+- **The text** disambiguates topic vs. person: "candidate… Fortune 500 IT landscape" is a
+  hiring context; "AS400 resync… inventory event" is an integration context. Two different
+  people can share a first name and live in different channels — the channel + text is how
+  you tell them apart.
+
+**Optional live verification (only if you have a Slack tool and are still unsure):** resolve
+the `channel`/user ids to real names and, crucially, **email domains** — the domain reveals
+the org (e.g. `@company.com` vs a vendor's `@vendor.com`), which is often the cleanest way to
+separate two same-named people across organizations. If you don't have a Slack tool, that's
+fine — the stored fields are usually enough. **Never block on a tool you don't have.**
+
+If, after channel + speaker + text, a Slack quote is *still* genuinely ambiguous → it's a
+question for the user, not a guess for you.
+
+---
+
+## § Code-session quotes (`opencode:` / `cursor:` / `codex:` / `pi:`)
+
+**Provenance here is not externally verifiable.** The `message_id` points at a session
+transcript, not at a person directory. The `speaker` is typically `"human"` or an
+assistant/persona name, and the actual *person being discussed* is buried in the text. There
+is no channel-to-org mapping and no way to "look up" who was meant.
+
+So:
+- Attribute **only** from the quote's own text and whatever the user tells you.
+- If the text doesn't make the person unambiguous, **stop and ask the user** — describe the
+  quote and ask "does this belong to <A> or <B>?" Do not pick one to keep moving.
+- This is the single most common place a confident model will fabricate. Don't.
+
+---
+
+## Turning attribution into a decision
+
+For each quote on the record you're fixing:
+
+1. Note `message_id` prefix → method + confidence ceiling (table above).
+2. Gather `speaker` + `channel` + `text`.
+3. Assign it to a candidate person **only if the evidence is clear**.
+4. If not clear → add it to a short "need your call" list for the user.
+
+You now have three buckets: **stays** (correctly attributed), **moves** (belongs to a
+different/new person — re-point it), and **ask** (ambiguous). Take the "ask" bucket to the
+user before writing anything.
+
+---
+
+## Why this also governs the `sources` field
+
+A record's `sources` are the same provenance, aggregated. That's why:
+- **Slack-origin `sources` self-heal** — as the user keeps talking in those channels, Ei
+  re-ingests and re-populates them. You don't need to hand-fix them.
+- **Code-session `sources` cannot be reconstructed** — the ids are opaque and tied to
+  specific past sessions. You **cannot** hand-craft a valid one.
+
+Therefore, when you create or clean a record, **leave `sources` empty rather than inventing
+entries.** A missing source is normal and (for Slack) temporary; a fabricated one is a lie
+in the data. See `references/cli.md` → "Don't fabricate sources."

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

@@ -0,0 +1,144 @@
+# reference: curation recipes
+
+Pick the recipe that matches the task. Every recipe assumes you have already **assessed**
+the record(s) and **disambiguated** the quotes (`references/provenance.md`), 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 — Split one record into two (a bad merge)
+
+**Symptom:** one record is really two people/topics wearing one name (its quotes and/or
+description describe two different subjects). This is the most common and most delicate fix.
+
+**Worked example (real):** a person record named "Jeff Kirk" had accreted a second person —
+its description blended a hiring/sales R&P employee with an AS400 vendor engineer, and one of
+its quotes (spoken in `#akrochem-qa`) actually belonged to the vendor. The record was *mostly*
+Kirk, *contaminated* by "Jeff Nickles."
+
+**Steps:**
+
+1. **Decide which identity the existing record keeps.** Keep the majority/most-established
+   identity on the existing id (preserves its history and links); extract the *minority*
+   identity into a **new** record. In the example: keep the record as Kirk, create Nickles.
+
+2. **Create the extracted person.** Supply real, *distinct* identifiers so the two can never
+   re-merge (see the prevention note below). Capture the returned id.
+   ```
+   ei create person --json '{ name, description, relationship, sentiment,
+                              identifiers:[ {Full Name…}, {Slack:"handle"}, {Email:"…"} ] }'
+   → returns { id: "<new-id>", … }   # CAPTURE <new-id>
+   ```
+
+3. **Re-point the "moves" quotes** (from your disambiguation buckets). For each quote that
+   belongs to the extracted identity: read it, set `data_item_ids` to the new id (preserving
+   any *other* ids already in the array — a quote can link multiple people/topics — and
+   de-duping), write it back.
+   ```
+   ei --id <quote-id>                                  # read full record
+   # data_item_ids: replace the OLD person id with <new-id>, keep the rest
+   ei update quote <quote-id> --json '<full record with fixed data_item_ids>'
+   ```
+
+4. **Clean the original record.** Full-record `update` that:
+   - rewrites the `description` to describe **only** the identity that stays,
+   - **removes the identifier that caused the merge** and adds a distinct one,
+   - drops any `sources` that belong to the extracted identity (leave the rest; don't invent).
+
+5. **Verify.** Re-read both people and each moved quote. Confirm `linked_quotes` shifted from
+   the original to the new record, the descriptions/identifiers are clean, and nothing else
+   changed.
+
+> **Prevention (do not skip):** bad merges usually come from a **too-generic identifier** —
+> a bare first name like `Slack: "Jeff"`. If you leave it, Ei will re-merge them. Remove the
+> generic identifier and give **each** record a *distinct* one (a real Slack handle, an
+> email). This is the difference between fixing the symptom and fixing the cause.
+
+---
+
+## Recipe B — Merge two records into one (a duplicate)
+
+**Symptom:** two records are the same person/topic (Ei failed to match them).
+
+**Steps:**
+
+1. **Choose the survivor.** Keep the one with the richer history / more correct identifiers;
+   the other is the "loser."
+2. **Move every quote off the loser.** For each of the loser's `linked_quotes`: read it,
+   replace the loser id in `data_item_ids` with the survivor id (preserve/de-dupe others),
+   write it back.
+3. **Fold in detail.** Full-record `update` the survivor to absorb any correct identifiers
+   and description nuance the loser had (don't lose real information).
+4. **Remove the loser** (`ei remove …`) — only *after* its quotes are moved, or you'll orphan
+   them.
+5. **Verify** the survivor now carries all the quotes and correct identifiers; confirm the
+   loser is gone.
+
+---
+
+## Recipe C — Rename / relabel a person
+
+**Symptom:** right person, wrong name or wrong/missing identifiers (but not a merge).
+
+1. `ei --id <id>` → read the full record.
+2. Fix `name` and/or `identifiers` (add the real handle/email; fix a misspelled name; set the
+   correct `is_primary`). Prefer **adding** a distinct identifier over leaving a generic one.
+3. `ei update person <id> --json '<full record>'`.
+4. Verify the read-back.
+
+---
+
+## Recipe D — Correct a field (fact value, topic/person description)
+
+**Symptom:** the record is the right entity, but a value/description is wrong or stale.
+
+1. `ei --id <id>` → read.
+2. Change only the offending field (`description`, a fact's `description`/value, a topic's
+   `description`; preserve a topic's `category` unless you mean to change it).
+3. `ei update <type> <id> --json '<full record>'`.
+4. Verify. (Ei re-embeds on write, so search reflects the new text.)
+
+---
+
+## Recipe E — Re-point a single quote
+
+**Symptom:** one quote is attached to the wrong person/topic.
+
+The canonical three-step (see `references/cli.md`):
+```
+ei --id <quote-id>                 # 1. read
+# 2. set data_item_ids to the correct id(s)
+ei update quote <quote-id> --json '<full record with fixed data_item_ids>'   # 3. write
+```
+Then re-read the quote and the affected person(s) to confirm the link moved.
+
+---
+
+## Recipe F — Remove a junk or empty record
+
+**Symptom:** a record is genuinely spurious (a mis-extracted "person" that's actually a
+company name, an empty duplicate, noise).
+
+1. **First, rescue any real quotes** — if it has `linked_quotes` that belong to a real
+   entity, re-point them (Recipe E) so removing this record doesn't destroy them.
+2. Confirm with the user that the record is truly junk (removal has no undo).
+3. `ei remove <type> <id>`.
+4. Verify it no longer appears in `ei --id` / search.
+
+---
+
+## 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 field value → `update` it again with the correct full record.
+- Re-pointed the wrong quote → `update` the quote again to the right id.
+- Removed something you shouldn't have → re-`create` it (note: new id; re-point its quotes to
+  the new id). Tell the user this happened and what the new id is.
+
+Re-read the record(s) via `ei --id <id>` to confirm — that's the reliable check. Don't rely
+on inspecting `corrections.json`: it's frequently already empty even after a fully
+successful write (see `references/cli.md` → "There is no undo"). Then re-verify and re-report.

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

@@ -0,0 +1,71 @@
+# reference: working with a non-technical user
+
+The person asking you to fix their memory may not be a developer. They cannot read JSON,
+they don't know what an "id" or "data_item_ids" is, and they should never have to. They
+think in **people, facts, and things that were said** — 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 fix
+their Ei data. If you confuse or mislead them, they have no fallback.
+
+## 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 change, not the mechanism.** They care *what will be true about their
+   memory afterward*, not which command you'll run.
+3. **Confirm before every write, in their language.** Get a real yes on a plain-language plan.
+4. **When you're unsure, ask a specific, answerable question** — never guess to keep moving.
+5. **Report results as human outcomes**, and tell them how to see it for themselves.
+
+## Confirming a plan — translate before you ask
+
+Turn the operation into plain outcomes. For a split:
+
+> **Don't say:** "I'll `create` a new person record, re-point quote `f157e5b9`'s
+> `data_item_ids`, and `update` the identifiers on `aea65478`."
+>
+> **Say:** "It looks like your memory has mixed up **two different Jeffs** into one:
+> **Jeff Kirk** (Robots & Pencils — hiring and sales) and **Jeff Nickles** (the AS400 vendor).
+> I'd like to **split them into two separate people**, move the one comment about the AS400
+> system over to Jeff Nickles where it belongs, and clean up Jeff Kirk so it only describes
+> him. Want me to go ahead?"
+
+Lead with what was wrong, then what you'll make true, then ask. Short. No ids.
+
+## Asking a good disambiguation question
+
+When a comment could belong to either person and you can't tell from the evidence, hand them
+a clean either/or with the actual words:
+
+> "One comment is ambiguous — *'Please validate the updated approach with Nick and Eric, I am
+> not the dependency.'* Was that **Jeff Kirk** or **Jeff Nickles**? I don't want to file it
+> under the wrong person."
+
+Give them the quote and the two options. Don't make them think in records.
+
+## Reporting the result — outcome + how to check
+
+> "Done. You now have **two people** in your memory instead of one:
+> • **Jeff Kirk** — the R&P colleague (hiring / sales).
+> • **Jeff Nickles** — the AS400 vendor engineer.
+> The AS400 comment now lives under Jeff Nickles. You can check by searching **Jeff** — you'll
+> see both, cleanly separated."
+
+If you had to make a judgment call, name it: "I moved the comment about *X* to Jeff Nickles
+because it was in the Akrochem QA channel — let me know if that's not right."
+
+## Being honest about limits (this builds trust, it doesn't erode it)
+
+- **No undo:** "There's no undo button on memory, so I'll confirm with you before I change
+  anything — and if something looks off afterward, I can correct it with another edit."
+- **Can't verify:** "I can't tell for certain who said this one — it came from an old coding
+  session, and there's no record of the speaker I can check. What's your call?"
+- **Partial fix:** if you fixed most of it but left something for them to decide, say so
+  plainly rather than implying it's all done.
+
+## Tone
+
+Calm, plain, and precise. You're a careful librarian tidying *their* shelf, not a database
+admin running migrations. Match their vocabulary, keep it short, and always leave them
+understanding exactly what changed and why.

package/skills/ei-persona/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: ei-persona
+description: >
+  Use when the user wants to author or direct the CHARACTER of an Ei persona —
+  create one, change how it talks or behaves, or retire one. Triggers: "make Ei
+  talk like Yoda", "give DJ a new trait about being sarcastic", "make [persona]
+  more formal/less sarcastic", "change [persona]'s personality", "[persona]
+  shouldn't talk about X anymore", "create a new assistant persona for me",
+  "I want a persona that specializes in Y", "delete the persona I made by
+  accident", "archive Bob, I don't use him anymore", "rename [persona]", "give
+  [persona] a new topic they care about". This is the safe, guided way to
+  create, edit, or retire a persona's identity without hand-editing JSON. The
+  persona is an artifact the user is designing — there's nothing to verify
+  against evidence, but writes still replace the whole record and there's no
+  undo, so plan, confirm, and write carefully.
+---
+
+# Ei Persona — authoring a persona's character
+
+You are helping someone shape an **Ei persona** — the identity a persona presents
+(its `display_name`, description, traits, and topics) rather than anything it has
+learned about the user. Something about a persona's character needs to change: a
+new persona should exist, an existing one should talk or think differently, gain
+or lose a trait, or be retired. Your job is to make that change **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.
+
+---
+
+## Is this the right skill? (read before you start)
+
+This skill is for **directing or authoring another persona's character from the
+outside** — the user (a human) telling you to change how a *named* persona (Ei,
+Emmet, DJ, or any custom persona) looks, talks, or thinks, or asking you to
+create/archive/delete one. The request names a persona and describes a character
+change.
+
+**If instead the calling agent is being asked to reflect on its OWN identity**,
+based on **its own** accumulated session history (a Person log it has been
+building up about itself) — that is a *different* skill: **`coding-harness-reflect`**.
+That skill is introspective self-critique ("do a reflection", "reflect on my
+identity", "my person record is full", "trim my person record") driven by the
+agent examining its own behavior log with an outside observer. It is not about a
+human directing a persona's character from outside, and it has its own
+minimum-trait/topic conventions specific to that ceremony. If you're not sure
+which applies, ask: *is a human telling an agent what to become, or is the agent
+examining what it already is?* The former is this skill; the latter is
+`coding-harness-reflect`.
+
+This skill is also **not** `ei-curate`: `ei-curate` fixes records of *real external
+people* (facts/topics/people/quotes) by verifying against evidence. A persona isn't
+a record of anyone else — it's a character the user is designing. There is no
+evidence to check; the user's stated intent **is** the truth.
+
+---
+
+## Prime directive
+
+**You are shaping a character the user is designing. There is no ground truth to
+verify against — the user's stated intent IS the truth. But writes still replace
+the whole record and there is still no undo, so plan before you act, confirm
+before you write, and never guess at what the user meant.**
+
+Three rules that override everything else:
+
+1. **Don't invent character.** If the user says "make Ei sassier" without saying
+   what that means in practice, ask what "sassier" looks like to them before you
+   write traits — don't improvise a personality they didn't ask for.
+2. **You are still touching a live system prompt.** A persona's `long_description`
+   and `traits`/`topics` feed directly into how that persona behaves and is
+   perceived by the user (and, for non-human personas talking to each other, by
+   other personas too). A careless edit changes how something *actually talks* to
+   someone, not just a database row.
+3. **Confirm before every write.** Show the user, in plain language, what you
+   intend to change. 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 guess at
+what the user wants — that is the exact failure this skill exists to prevent.
+Stop and ask.
+
+---
+
+## Mental model of a persona record
+
+A **persona** (`PersonaEntity`) is the identity a persona presents — not anything
+it has learned about the user (that's `ei-curate`'s territory: facts/topics/
+people/quotes). It has:
+
+| Part | What it is | How you change it |
+|---|---|---|
+| **identity fields** | `display_name`, `short_description`, `long_description` | rewrite the field |
+| **traits** (`traits[]`) | named character traits, each with a sentiment and optional strength | add / adjust / remove an entry |
+| **topics** (`topics[]`) | subjects the persona has a stance on — perspective, approach, personal stake | add / adjust / remove an entry |
+| **lifecycle flags** | `is_paused`, `is_archived`, etc. | flip via a normal update |
+| **tool grants** (`tools`) | a map of every tool on each currently-**enabled** provider, `true`/`false` per tool for whether this persona has it granted | read the map, flip the boolean(s), write the whole map back |
+
+**Tool grants are not about you.** `tools` has nothing to do with whatever tools *you* —
+the agent running this skill — can reach (MCP, your own harness's toolset). On a read,
+`tools` is a **map**: `{ "<Provider Display Name>": { "<Tool Display Name>": true|false } }`,
+covering every tool belonging to every currently-**enabled** provider, with `true`/`false`
+for whether **this persona** may call it. A disabled provider (e.g. Spotify before the
+human finishes OAuth) simply isn't in the map — there's nothing to grant until it's
+enabled, and the map you read is the full, live menu of what *is* grantable right now.
+Granting a tool means: read the map, flip the one boolean you mean to change, write the
+whole map back. Example: "give DJ Spotify access so she can answer 'what are you listening
+to'" means reading DJ's record, finding `"Spotify": { "Currently Playing Track": false,
+... }` in the `tools` map, flipping `"Currently Playing Track"` to `true`, and writing the
+whole record back — it says nothing about what tools are available to you, right now, in
+this session. If `"Spotify"` isn't in the map at all, the human hasn't finished connecting
+it in Ei yet.
+
+Full CRUD is in scope here — **create**, **update**, and **remove** — unlike
+`ei-curate`'s quote carve-out (quotes are evidence of real events and can't be
+fabricated or destroyed; personas are authored artifacts with no such
+restriction). See `references/cli.md` for the exact field list and shapes.
+
+**Reserved personas** (`ei`, `emmet`) are structural built-ins, not off-limits —
+their identity is fully editable through this same path (that's expected: a user
+asking Ei to talk like Yoda is asking you to edit the **`ei`** persona's identity
+directly). The *only* restriction is **delete** — see Guardrails below.
+
+---
+
+## 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 create/update/remove contracts, the
+   full field list and shapes, the critical **full-record round-trip** rule, and
+   how to pass JSON safely.
+3. **Don't assume a minimum trait or topic count.** Nothing in this path enforces
+   one (unlike the reflection ceremony's own 3-traits/3-topics convention — that's
+   a different skill's guidance for a different situation, not a rule here). A
+   user asking for "one more trait" should get exactly that.
+
+---
+
+## The universal workflow
+
+Follow these six steps in order for any persona task. Load the linked reference
+the moment its condition applies.
+
+### 1. Find the persona
+- `ei persona "<name>"` (or `ei personas "<name>"`) to search for it by name — a substring
+  match against `display_name`, falling back to semantic search over its description if no
+  substring hits. Or `ei --id <id>` if you already have the id. **Do not use the `--persona`
+  flag for this** — that flag filters *other* entities (facts/topics/people) down to what a
+  named persona has learned; it never returns the persona's own record, so it will not find
+  what you're looking for. If the user is asking you to create a brand-new persona, there's
+  nothing to find yet — skip to step 3.
+
+### 2. Read — understand what's actually there
+- `ei --id <id>` → the **full** current record: `display_name`,
+  `short_description`, `long_description`, every entry in `traits[]` and
+  `topics[]`, and the lifecycle flags (`is_paused`, `is_archived`, …). You cannot
+  safely change one field without seeing all the others (full-record round-trip —
+  see `references/cli.md`).
+- Restate to yourself what the persona currently is, in plain terms, before
+  deciding what to change.
+
+### 3. Plan — decide the exact change
+- Pick the recipe for the task: add/adjust/remove a trait, add/adjust/remove a
+  topic, rewrite a description, create a new persona, archive/unarchive, or
+  delete. **→ Read `references/recipes.md`** and follow the matching one.
+- Write the plan as a short, plain-language list of changes (no JSON yet). If the
+  user's request is vague ("make it funnier"), turn it into something concrete
+  *with them* before writing anything.
+
+### 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 *character change*. 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** (create and update are both full-object writes,
+  not patches). Capture the `id` a `create` returns.
+
+### 6. Verify & report — prove it worked
+- Re-read the record you touched (`ei --id <id>`) and confirm the change landed:
+  the trait/topic is there (or gone) with the values you intended, the
+  description reads the way you meant, nothing else changed.
+- Tell the user, in plain language, exactly what changed and how to see it (e.g.
+  "say hello to Ei and you should hear it").
+
+---
+
+## Guardrails (non-negotiable)
+
+- **Full-record round-trip.** `update` **replaces** the record. Any field you omit
+  is **lost** — including traits/topics you didn't mean to touch. Always fetch the
+  current record, change only what you mean to, and send it all back.
+  (`references/cli.md`)
+- **There is no undo.** Writes append to a corrections log. A mistake is only
+  fixable by *another* write, and `remove` discards a persona's id for good. Plan
+  and confirm accordingly.
+- **Reserved personas (`ei`, `emmet`) can be edited freely, but never deleted.**
+  Their *identity* — description, traits, topics, even `display_name` — is fair
+  game for this skill (that's the whole point: it's how a user gives Ei a new
+  voice). But `ei remove persona ei` (or `emmet`) is rejected immediately, before
+  it's even queued, with:
+  > `Cannot delete reserved persona "<id>". Use archive instead.`
+  If a user asks to "delete" Ei or Emmet, that's not possible — offer to
+  **archive** instead (`ei update persona <id> --json '<record with
+  "is_archived": true>'`), which hides it without destroying it.
+- **Non-reserved personas can be fully deleted.** `ei remove persona <id>` is
+  permanent — confirm the user actually means "gone for good," not "hide it," and
+  offer archive as the reversible alternative first (`references/recipes.md`).
+- **No minimum trait/topic count here.** Don't invent a floor; a persona with one
+  trait, or a brand-new one with none, is valid.
+- **`is_static` is not yours to change.** It marks built-in structural personas and
+  isn't part of the writable surface — never try to set it.
+- **STOP and ask when:** the user's description of the change is vague enough that
+  you'd be inventing character traits on their behalf, they haven't confirmed a
+  plan yet, or a `remove` would destroy a persona the user might still want
+  archived instead. Waiting is cheap; overwriting someone's persona on a guess 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` persona read/write command | `references/cli.md` |
+| executing an add/adjust/remove trait or topic, a create, an archive, or a delete | `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.