ei-tui 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ei-tui",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "author": "Flare576",
   "repository": {
     "type": "git",

package/skills/ei-persona/SKILL.md

@@ -40,7 +40,7 @@ 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`**.
+building up about itself) — that is a *different* skill: **`ei-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
@@ -48,7 +48,7 @@ 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`.
+`ei-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

package/skills/{coding-harness-reflect → ei-reflect}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-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'."
+name: ei-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', 'ei-reflect'."
 ---
 
-# Coding Harness Reflection
+# Ei 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.
 
@@ -15,79 +15,88 @@ 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`.
+Confirm the CLI is reachable: `ei --help` (or `bunx ei-tui --help` if `ei`
+isn't on PATH — same fallback `ei-search`/`ei-curate` use). **The live
+`--help` output is the source of truth** for the exact command surface —
+this skill is a guide, but the CLI evolves.
 
-```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"
-```
+There's no separate "has Ei run here before" check to do up front. If
+there's no data yet for your persona, the read commands in Step 1 will say
+so directly — an empty search result, or a not-found response from the
+linked-record lookup — and Step 1 tells you what each of those means.
 
-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.
+There is no need to check whether Ei is currently running, either. Writes
+in this skill go through Ei's corrections path (`ei update`), which works
+identically either way — it queues for a live Ei to pick up, or applies
+directly 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.
+Everything here is CLI-driven — no raw file reads, no `jq` against Ei's
+storage.
 
-**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").
+**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):**
+**Find your persona id** — name-match search:
+```bash
+ei personas -n 1 "$DISPLAY_NAME"
+```
+That returns a one-element JSON array. Pull the id out of it:
+```bash
+PERSONA_ID=$(ei personas -n 1 "$DISPLAY_NAME" | jq -r '.[0].id')
+```
+
+If `$PERSONA_ID` comes back empty or `null`: stop and tell Flare. Every
+calling persona should have a matching record, so this means something is
+misconfigured — it should not normally happen.
+
+**Verify it's actually you** — persona search is substring match, then reverse-containment, then semantic fallback (not a guaranteed exact match), so an overlapping name could silently resolve someone else's persona. Check the result's `display_name` against `$DISPLAY_NAME` before trusting `$PERSONA_ID`:
 ```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"
+ei personas -n 1 "$DISPLAY_NAME" | jq -r '.[0].display_name'
 ```
+If that name doesn't match `$DISPLAY_NAME` case-insensitively, stop and tell Flare rather than proceeding with a possibly-wrong persona id.
 
-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).
+**Fetch your full persona record** — the search result above is
+abbreviated and omits fields like `pending_update`:
+```bash
+ei --id "$PERSONA_ID"
+```
+This is your current Persona Identity for the reflection:
+`short_description`, `long_description`, `traits`, `topics`, and — if
+present — `pending_update`.
 
-**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.
+**Fetch your linked Person record (the log)** — via the persona → person
+reverse lookup:
+```bash
+ei --identifier "Ei Persona" "$PERSONA_ID"
+```
+This returns the full enriched Person record linked to your persona id
+(same shape as `ei --id <person-id>`, including `linked_quotes`) — this
+*is* the log Step 2 reflects on. Note its `id` field from the output for
+later use in Step 3 (call it `PERSON_LOG_ID`). If you want the character
+count for Step 2's summary, `jq '.description | length'` on this output
+gives you that directly.
+
+If that command exits non-zero with `No person found with identifier Ei
+Persona: <id>` on stderr (empty stdout — nothing to pipe into `jq`): no
+Person record is linked to your persona yet. That happens for a brand-new
+persona that hasn't been through extraction — there's no log to have
+accumulated, which means there's nothing to reflect on yet, not an error.
+Stop here and check back after a few more sessions.
+
+**If `pending_update` was present on the persona record:** 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 in Step 2, not a replacement for it.
 
 ---
 
@@ -107,7 +116,19 @@ Then look at your current identity and ask:
 - 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.
+**Present a reflection summary to Flare — not the raw log.** Structure
+what you share as:
+- **Identity now** — one short paragraph on how the persona currently reads
+- **Log size** — the Person-log character count from Step 1
+- **Recurring patterns** — 3–7 patterns worth preserving
+- **Noise** — task residue, one-off incidents, changelog-ish material you're planning to drop
+- **What may be missing** — real traits/topics not showing up strongly enough
+- **Open questions for Flare** — only where the record is ambiguous or a proposed change is a meaningful judgment call
+
+Quote a line from the log verbatim only when you need it to discuss or
+resolve a disagreement about a specific pattern — never as a default dump
+of the whole record. 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
@@ -186,7 +207,10 @@ If a trait or topic is brand new, you don't need to invent an `id` for it — om
 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)"
+PERSONA_EDIT_JSON=$(mktemp)
+# write the edited persona record (from "Apply your edits" above) to "$PERSONA_EDIT_JSON"
+ei update persona "$PERSONA_ID" --json "$(cat "$PERSONA_EDIT_JSON")"
+rm -f "$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.
@@ -203,7 +227,10 @@ 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)"
+PERSON_LOG_EDIT_JSON=$(mktemp)
+# write the person record above (description set to "") to "$PERSON_LOG_EDIT_JSON"
+ei update person "$PERSON_LOG_ID" --json "$(cat "$PERSON_LOG_EDIT_JSON")"
+rm -f "$PERSON_LOG_EDIT_JSON"
 ```
 
 ### Verify the result
@@ -224,7 +251,7 @@ 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.
+- **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 saved and will be there 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-search/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: ei-search
+description: >
+  Use when someone wants to deliberately search or look something up in Ei —
+  the user's persistent memory store — mid-conversation, beyond whatever
+  context was already silently injected. Triggers: "what does Ei know about
+  X", "search Ei's memory for X", "look up X in Ei", "check Ei for context on
+  Y", "find out if Ei has info about Z", "does Ei know who X is", "pull up
+  what Ei has on this topic", "search my memory for X", "what has [persona]
+  learned about X", "fetch that message/quote Ei found", "get the full
+  record for this fact/person/topic/quote". This is the deliberate, targeted
+  read path — distinct from the automatic per-turn context injection that
+  already runs silently via hooks/plugins before this skill is ever
+  invoked. Reach for this skill when the auto-injected context didn't
+  surface something relevant, when you need the full record behind a
+  summarized result, when you need to fetch the original conversation
+  behind a quote, or when you need to scope results to what a specific
+  persona has learned. Read-only: creating, correcting, or removing records
+  is the `ei-curate` (facts/topics/people/quotes) or `ei-persona` (persona
+  identity) skill's job, not this one.
+---
+
+# Ei Search — looking things up in Ei mid-conversation
+
+You are helping someone pull a specific piece of information out of **Ei** —
+the user's persistent memory, built from their conversations, Slack, and
+coding sessions. Something wasn't already surfaced by the automatic context
+injection, or you need the full detail behind a summarized item, or the
+original quote/conversation behind something Ei surfaced. This is a
+**read-only** skill: search and lookup, nothing else.
+
+---
+
+## Is this the right skill?
+
+Ei already injects relevant context automatically, every turn, before you
+ever see the user's message: a hook searches Ei using the prompt (plus
+recent conversation history) and silently prepends a `## Ei Memory Context`
+block to what you read. You never call a tool for that — it already
+happened, passively, without you or the user doing anything.
+
+This skill is for the **deliberate, explicit, mid-conversation case**: you
+(or the user) decide to go look something up specifically, right now, beyond
+whatever was already silently injected. Reach for it when:
+
+- The auto-injected context **didn't surface something** you now realize is
+  relevant — it's a best-guess search off the current prompt, and it can miss.
+- You need the **full record**, not the injected summary — injected context
+  is trimmed/summarized to fit a token budget; the full record has fields
+  the summary dropped.
+- A quote surfaced (injected or searched) and you need the **original
+  conversation** it came from, not just the isolated sentence.
+- You need to scope results to **one persona's** knowledge specifically
+  (e.g. "what has Beta learned about the auth refactor") instead of the
+  whole knowledge base.
+
+If instead the goal is to **fix** something wrong in Ei's memory (a bad
+merge, a mis-attributed quote, a stale fact) → that's `ei-curate`. If the
+goal is to **author a persona's character** (traits, voice, description) →
+that's `ei-persona`. This skill only reads; it never writes.
+
+---
+
+## Before you start
+
+Confirm the CLI is reachable: `ei --help` (or `bunx ei-tui --help` if `ei`
+isn't on PATH). **The live `--help` output is the source of truth** for the
+exact command surface — this skill is a guide, but the CLI evolves.
+
+---
+
+## Command reference
+
+| Command | Returns |
+|---|---|
+| `ei "query"` | Balanced search across facts, people, topics, and quotes, ranked by relevance, up to 10 results — does **not** include personas; use `ei personas "query"` for those |
+| `ei -n N "query"` | Same, capped at `N` results |
+| `ei facts -n N "query"` | Facts only |
+| `ei people -n N "query"` | People only |
+| `ei topics -n N "query"` | Topics only |
+| `ei quotes -n N "query"` | Quotes only |
+| `ei personas -n N "query"` | Personas only — matches display name first, falls back to semantic search over persona descriptions |
+| `ei --persona "Name" "query"` | Narrow facts/people/topics to what a specific persona has learned — reliable only for those three types: always excludes quotes, and on `ei personas` returns everything unfiltered instead of scoping (see Guardrails) |
+| `ei --recent` | Most recently mentioned items, no query needed — browse by recency |
+| `ei --persona "Name" --recent` | Recent items scoped to one persona's knowledge |
+| `ei --source <prefix> "query"` | Same narrowing, by source prefix (e.g. `cursor`, `codex:my-machine`) instead of persona — same caveats: always excludes quotes, doesn't scope `ei personas` results |
+| `ei --id <id>` | Full-record lookup — entity id or fully-qualified message id (see below) |
+| `echo <id> \| ei --id` | Same lookup, id piped via stdin |
+| `ei "query" \| jq -r '.[0] \| if .id != null then .id else .message_id end' \| ei --id` | Quote-safe search-then-drill-down: entity hits drill down by `id`, quote hits (no `id`) drill down by `message_id` |
+
+Type aliases work singular or plural: `fact`/`facts`, `person`/`people`,
+`topic`/`topics`, `quote`/`quotes`, `persona`/`personas`. Short flags:
+`-n` (number), `-p` (persona), `-s` (source), `-r` (recent).
+
+### Choosing which command to run
+
+A short decision tree for picking the right read path before you search:
+
+1. **Start broad** with `ei "query"` when you don't yet know whether the
+   answer is a fact, person, topic, or quote.
+2. **Start typed** with `ei personas "query"` when the target is clearly an
+   AI persona/agent identity — balanced search never returns those (see
+   above).
+3. **Add `--recent`** when the ask is about what Ei learned *lately /
+   recently / just now*, not a specific topic.
+4. **Add `--persona "Name"` or `--source <prefix>`** only when you're
+   intentionally narrowing human-memory results (facts/people/topics) —
+   don't assume they scope quote or persona searches the same way.
+5. **Stop at the search result** if it already answers the question. Reach
+   for `ei --id` only when you need a field the summary didn't include.
+
+### Two id formats
+
+`--id` accepts two different shapes and resolves them differently — it
+tries message resolution first, then falls back to entity lookup, so you
+never have to pick which path, just pass the id:
+
+- **Entity id** — a short guid, e.g. `2aa93a36-3ad3-4537-8832-7f60067c3bcf`.
+  Identifies one fact, topic, person, quote, or persona row.
+- **Message id** — fully-qualified, `provider:machine:session:id`, e.g.:
+  - `opencode:jeremys-macbook-pro:ses_38a7...:msg_c75b...`
+  - `claudecode:my-machine:session-uuid:message-uuid`
+  - `cursor:my-machine:composer-uuid:bubble-uuid`
+  - `codex:my-machine:thread-uuid:evt_42`
+  - `pi:my-machine:session-uuid:session-uuid/entry-id`
+  - `ei:uuid` (persona-to-persona / internal Ei conversations)
+
+Quote results carry a `message_id` in this format — pipe it to `ei --id` to
+read the original exchange it came from.
+
+Safe mental model: **entity hits drill down by `id`; quote hits drill down
+by `message_id`.** Don't assume every search hit has an `id` — quote hits
+won't. Prefer a quote-safe pipeline over grabbing `.[0].id` blindly:
+
+```sh
+ei "query" | jq -r '.[0] | if .id != null then .id else .message_id end' | ei --id
+```
+
+---
+
+## What each command is actually for
+
+(This is straight from Ei's own tool definitions — the minimum you need
+before searching, plus what changes when you're driving it from the CLI.)
+
+**Search (`ei` / `ei <type>`)** — searches a persistent memory store built
+from conversations. Balanced `ei "query"` covers facts, people, topics, and
+quotes; it does **not** include personas — those are a type-only search
+(`ei personas "query"`). The type boundaries aren't always obvious:
+
+- **facts** are ONLY user demographics: name, age, job title, location,
+  family structure, physical traits.
+- **topics** are everything else the human has interest, opinion, or stake
+  in — hobbies, preferences, projects.
+- **people** are named individuals — human contacts, not AI personas.
+  Person results carry an `identifiers[]` array (GitHub handle, Discord,
+  email, nickname) — query by any handle or name to find what Ei knows
+  about that person.
+- **quotes** are verbatim things said.
+- **personas** are AI agent identities with traits and working style —
+  search by name (e.g. "Sisyphus") or by a description of their role (e.g.
+  "primary coding agent"); distinct from **people**, which are humans.
+  Reachable only via `ei personas "query"` — balanced `ei "query"` skips
+  them.
+
+Omit the query and pass `--recent` to browse without semantic filtering.
+
+**Full-record lookup (`ei --id <entity-id>`)** — use once search has
+narrowed to a candidate and you need everything about it: all fields,
+traits, identifiers, not just the search summary. For facts, topics, and
+people specifically, the result also includes `linked_quotes`: every quote
+attributed to that entity — the fastest way to see the full blast radius of
+a person/topic before assuming a record is simple (though acting on what you
+find there is `ei-curate`'s job, not this one's).
+
+**Message fetch (`ei --id <message-id>`)** — retrieves the original message
+a quote or reference came from, routed automatically to the right source by
+the id's prefix: Ei's own state, OpenCode SQLite, Claude Code JSONL, the
+Cursor DB, or Codex rollout history. Use this when a quote's phrasing is
+ambiguous, or you want the surrounding exchange rather than the isolated
+sentence. **CLI caveat**: `ei --id` on a message always fetches just that one
+message — it has no `before`/`after` flags to expand the window. (The MCP
+`ei_fetch_message` tool, where available, additionally accepts `before`/
+`after` counts to pull in surrounding messages; if you're on an MCP-enabled
+harness and specifically need that expanded window, that tool covers a case
+the CLI path here doesn't.)
+
+---
+
+## Output shapes — know this before you make a second call
+
+All search commands return **arrays**; every result has a `type` field.
+
+| Type | Shape |
+|---|---|
+| Fact / Topic | `{ type, id, name, description, sentiment, ...type-specific fields }` |
+| Person | `{ type, id, name, description, relationship, sentiment, identifiers[] }` |
+| Quote | `{ type, text, speaker, message_id, timestamp, linked_items[] }` — **no `id`, on purpose**: quotes are addressed by `message_id` (fetch the original message), not an editable entity id |
+| Persona | `{ type, id, display_name, short_description, model, base_prompt, traits[], topics[] }` |
+
+`ei --id <entity-id>` returns a **single object** (not an array), same shape
+as above, plus a `linked_quotes[]` array for facts/topics/people. Persona
+id-lookups additionally get a `tools` field as a self-documenting
+`{ providerDisplayName: { toolDisplayName: boolean } }` map.
+
+`ei --id <message-id>` returns a different shape entirely: message content
+plus its session/source context (`{ message, before, after, session/source }`
+depending on the integration) — not an entity at all.
+
+Don't `--id` every search hit reflexively. If the search result already has
+what you need (name, description, text), you're done — reach for `--id`
+only when you actually need one of the extra fields listed above.
+
+---
+
+## Guardrails
+
+- **Read-only.** This skill never creates, updates, or removes anything. A
+  bad record → `ei-curate`. A persona's character → `ei-persona`.
+- **`--help` is the source of truth.** If a command here doesn't match live
+  `ei --help` output, trust `--help` and adapt.
+- **Search results omit quote `id` by design.** Address a quote by its
+  `message_id`, not an id. If you already have a quote's *entity* id from
+  somewhere else — e.g. a `linked_quotes` entry on a fact/topic/person
+  record — `ei --id <quote-id>` does work and returns the full quote
+  record.
+- **`--persona`/`--source` are human-memory narrowing tools, not universal
+  filters.** They're reliable for facts, people, and topics. They always
+  exclude quotes (results come back empty, not an error). On `ei personas`
+  they don't filter at all — every persona comes back unfiltered — so
+  don't rely on them there.
+- **This is the explicit-call path, not a substitute for the passive
+  injection.** Don't re-run a broad search "just in case" every turn — the
+  hook already did that before you saw the message. Use this skill when you
+  have a specific, unmet information need.

package/src/cli/README.md

@@ -3,7 +3,7 @@
 > For installation, see the [TUI README](../../tui/README.md#installation).
 ```sh
 ei                             # Start the TUI
-ei "query string"              # Return up to 10 results across all types
+ei "query string"              # Return up to 10 results across facts/people/topics/quotes (no personas — use "ei personas")
 ei -n 5 "query string"         # Return up to 5 results
 ei facts -n 5 "query string"      # Return up to 5 facts
 ei people -n 5 "query string"     # Return up to 5 people
@@ -15,7 +15,8 @@ ei --recent                            # Most recently mentioned items (no query
 ei --persona "Beta" --recent           # Most recently mentioned items Beta has learned
 ei --id <id>                   # Look up entity by ID — or fetch a message by FQ ID
 echo <id> | ei --id            # Look up entity by ID from stdin
-ei --install                   # Wire Ei into Claude Code, Cursor, Codex, and OpenCode (MCP + context hooks + skills (ei-curate, ei-persona, and future shipped skills) + persona plugin where supported)
+ei --identifier <type> <value>  # Look up a person by identifier type + value (case-insensitive type, exact value), e.g. --identifier "GitHub" "flare576"
+ei --install                   # Wire Ei into Claude Code, Cursor, Codex, and OpenCode (skills + context hooks + persona plugin where supported; MCP is removed by default on Claude Code/Cursor/Codex — see "MCP Server" below)
 ei --sync                      # Pull latest state from remote sync server into state.backup.json (no TUI required)
 ei mcp                         # Start the Ei MCP stdio server (for Claude Code/Cursor/Codex)
 ei create <type> --json '<json>'       # Create a new entity (fact/topic/person/persona)
@@ -25,12 +26,14 @@ ei remove <type> <id>                  # Remove an entity by ID
 
 Type aliases: `fact`, `person`, `topic`, `quote`, `persona` all work (singular or plural).
 
+`--identifier` matches the *first* person whose identifier array contains that value — safe for identifier types that are unique by construction (e.g. `Ei Persona`, a UUID assigned once per persona), but arbitrary if two people happen to share a value under a type that isn't guaranteed unique (e.g. duplicate `Nickname` or `First Name` entries).
+
 # An Agentic Tool
 
-The `--id` flag is designed for piping. For example, search for a topic and then fetch the full entity:
+The `--id` flag is designed for piping. Entity hits (fact/person/topic/persona) carry an `id`; quote hits don't (they carry `message_id` instead) — so a safe drill-down handles both:
 
 ```sh
-ei "memory leak" | jq '.[0].id' | ei --id
+ei "memory leak" | jq -r '.[0] | if .id != null then .id else .message_id end' | ei --id
 ```
 
 It also resolves fully-qualified message IDs from any supported integration, returning the original message content and session context:
@@ -53,15 +56,16 @@ Quotes surfaced by `ei_search` include a `message_id` field in this format — p
 ei --install
 ```
 
-This registers Ei with Claude Code, Cursor, Codex, and OpenCode — MCP server config, context injection hooks where supported, and (for OpenCode) a persona identity plugin so agents know who they are before the first message:
+This registers Ei with Claude Code, Cursor, Codex, and OpenCode — skill directories, context injection hooks where supported, and (for OpenCode) a persona identity plugin so agents know who they are before the first message. **MCP is removed by default** on Claude Code, Cursor, and Codex (see [MCP Server](#mcp-server) below) — every capability those MCP tools offered has a skill or CLI equivalent, so there's no longer a persistent `ei mcp` process sitting around per open session:
 
-| Tool | MCP | Context Hook | Persona Plugin |
-|------|-----|-------------|----------------|
-| **Claude Code** | `~/.claude.json` | `~/.claude/settings.json` (`UserPromptSubmit`) + `~/.claude/hooks/ei-inject.ts` | — |
-| **Cursor** | `~/.cursor/mcp.json` | `~/.cursor/hooks.json` (`beforeSubmitPrompt`) + `~/.cursor/hooks/ei-inject.sh` | — |
-| **Codex** | `~/.codex/config.toml` via `codex mcp add ei` | `~/.codex/hooks.json` (`UserPromptSubmit`) + `~/.codex/hooks/ei-inject.ts` | Local Codex agent plugin if installed separately |
-| **OpenCode** | manual (see below) | Via Oh My OpenCode compatibility layer (reads `~/.claude/settings.json`) | `~/.config/opencode/plugins/ei-persona.ts` |
-| **Pi / OMP** | — (tools registered as native Pi extension) | `~/.pi/agent/extensions/ei-integration.ts` (Pi) or `~/.omp/agent/extensions/ei-integration.ts` (OMP) | — |
+| Tool | Skills | Context Hook | Persona Plugin |
+|------|--------|-------------|----------------|
+| **Claude Code** | `~/.claude/skills/` + shared `~/.agents/skills/` | `~/.claude/settings.json` (`UserPromptSubmit`) + `~/.claude/hooks/ei-inject.ts` | — |
+| **Cursor** | shared `~/.agents/skills/` (Cursor's own native discovery path) | `~/.cursor/hooks.json` (`beforeSubmitPrompt`) + `~/.cursor/hooks/ei-inject.sh` | — |
+| **Codex** | shared `~/.agents/skills/` (Codex's own native discovery path) | `~/.codex/hooks.json` (`UserPromptSubmit`) + `~/.codex/hooks/ei-inject.ts` | Local Codex agent plugin if installed separately |
+| **OpenCode** | `~/.config/opencode/skills/` | Via Oh My OpenCode compatibility layer (reads `~/.claude/settings.json`) | `~/.config/opencode/plugins/ei-persona.ts` |
+| **Pi** | shared `~/.agents/skills/` (Pi's own native discovery path) | `~/.pi/agent/extensions/ei-integration.ts` | — |
+| **OMP** | `~/.omp/agent/skills/` | `~/.omp/agent/extensions/ei-integration.ts` | — |
 
 **Context hook**: fires before every message, searches Ei for relevant memory, and injects it silently. No tool call required.
 
@@ -88,12 +92,23 @@ Restart your agent tool after changes to activate.
 
 ### MCP Server
 
-Claude Code, Cursor, and Codex call `ei mcp` to start the MCP stdio server. You can run it directly to test:
+`ei --install` removes any Ei MCP registration from Claude Code, Cursor, and Codex by default — every MCP tool (`ei_search`, `ei_lookup`, `ei_fetch_message`, `ei_create`, `ei_update`, `ei_remove`) is a thin wrapper over the same CLI/corrections-queue code the `ei-search`, `ei-curate`, and `ei-persona` skills already teach agents to call directly. A persistent `ei mcp` process per open session bought nothing — it reloads state from disk fresh on every call, same as the CLI — and multiple such processes are what caused real Ei MCP processes to get mistaken for orphaned processes and killed.
+
+MCP support isn't removed from the codebase — `ei mcp` still works if you want it back:
 
 ```sh
-ei mcp
+ei mcp   # Start the Ei MCP stdio server directly, for testing or manual wiring
 ```
 
+To re-register it manually:
+
+- **Codex**: `codex mcp add ei --env EI_DATA_PATH=<path> -- bunx ei-tui mcp`
+- **Claude Code**: add to `~/.claude.json`'s `mcpServers`:
+  ```json
+  { "ei": { "type": "stdio", "command": "bunx", "args": ["ei-tui", "mcp"], "env": { "EI_DATA_PATH": "${EI_DATA_PATH}" } } }
+  ```
+- **Cursor**: add to `~/.cursor/mcp.json`'s `mcpServers` (same shape, but Cursor doesn't support `${VAR}` substitution — use a literal path for `EI_DATA_PATH`)
+
 ## How Automatic Context Injection Works
 
 After `ei --install`, agents receive Ei context without any manual tool calls:
@@ -101,7 +116,7 @@ After `ei --install`, agents receive Ei context without any manual tool calls:
 1. **Before each message** — the hook searches Ei using your prompt + recent conversation history as the query, then injects relevant topics into the conversation as `[Ei Memory Context]`. You won't see this in your chat view; the agent does.
 2. **At session start** (OpenCode + OMO only) — the persona plugin finds the agent's Ei persona record and appends it to the system prompt as `<ei-relationship>`. The agent knows its working style, traits, and shared history with you before the session begins.
 
-The `ei_search`, `ei_lookup`, and `ei_fetch_message` MCP tools are still available for targeted mid-session queries — use them when you want to look something up explicitly.
+For targeted, explicit mid-session queries — beyond whatever the hook already silently injected — agents reach for the `ei-search` skill (installed by default) to run `ei "query"` / `ei --id <id>` directly. The `ei_search`, `ei_lookup`, and `ei_fetch_message` MCP tools cover the same ground and remain available if you've manually re-registered MCP (see above).
 
 ## MCP Tools Reference
 
@@ -109,7 +124,7 @@ The MCP server exposes these tools to Claude Code, Cursor, Codex, and OpenCode:
 
 | Tool | Description |
 |------|-------------|
-| `ei_search` | Search across all five data types (facts, topics, people, quotes, personas). Supports `type`, `persona`, `source`, `recent`, `limit` filters. Start here. |
+| `ei_search` | Balanced search across facts, topics, people, and quotes (personas excluded — pass `type: "personas"` explicitly to search those). Supports `type`, `persona`, `source`, `recent`, `limit` filters. Start here. |
 | `ei_lookup` | Full-record lookup for any entity by ID — facts, topics, people, quotes, or personas. Use when you need complete details beyond the search summary. |
 | `ei_fetch_message` | Retrieve a specific message by fully-qualified ID with optional `before`/`after` context window. Use when a quote result has a `message_id` and you want the original conversation. Routes to the correct source automatically. |
 | `ei_create` | Create a new entity (fact, topic, person, or persona). Pass a full JSON record matching the entity's schema. Validates server-side; unknown fields are rejected. Returns the assigned id and the full stored record. Not available for quotes — verifiable-origin data can only be corrected via `ei_update`, never created. |
@@ -121,7 +136,7 @@ The MCP server exposes these tools to Claude Code, Cursor, Codex, and OpenCode:
 | Arg | Type | Description |
 |-----|------|-------------|
 | `query` | string (optional) | Search text. Omit to browse by recency. |
-| `type` | enum (optional) | `facts` \| `people` \| `topics` \| `quotes` \| `personas` — omit for balanced results across all types |
+| `type` | enum (optional) | `facts` \| `people` \| `topics` \| `quotes` \| `personas` — omit for balanced results across facts/people/topics/quotes; pass `personas` explicitly to search those |
 | `persona` | string (optional) | Persona display_name to scope results to what that persona has learned |
 | `source` | string (optional) | Prefix match against source identifiers (e.g. `opencode`, `cursor:my-machine`, `codex:my-machine`) |
 | `limit` | number (optional) | Max results, default 10 |
@@ -203,16 +218,20 @@ Will abort (with a clear error) if `state.json` already exists on this machine
 
 ## Shipped Skills
 
-`ei --install` copies Ei's shipped skills into each harness's skill discovery directory alongside the MCP config and context hooks:
+`ei --install` copies Ei's shipped skills into each harness's skill discovery directory alongside context hooks:
 
-- **Claude Code / OMP**: `~/.config/opencode/skills/<skill-name>/`
-- Other tools: respective skill directories per harness
+- **Claude Code**: `~/.claude/skills/<skill-name>/`
+- **OMP**: `~/.omp/agent/skills/<skill-name>/`
+- **OpenCode**: `~/.config/opencode/skills/<skill-name>/`
+- **Cursor, Codex, Pi (base)**: shared `~/.agents/skills/<skill-name>/` — written unconditionally, once, regardless of which of these three are actually detected on the machine, since all three natively discover this cross-tool convention on their own
 
-Skills are installed automatically — any directory added under `skills/` in the Ei package gets copied on the next `ei --install` run.
+Skills are installed automatically — any directory added under `skills/` in the Ei package gets copied to every location above on the next `ei --install` run.
 
 ### Currently shipped
 
 | Skill | What it does |
 |-------|-------------|
+| `ei-search` | Deliberate, explicit read-path lookups — search, full-record fetch, original-message fetch — via the CLI (`ei "query"`, `ei --id <id>`), for the mid-conversation case beyond whatever the automatic context-injection hook already surfaced. Read-only. Read the full workflow at `skills/ei-search/SKILL.md`. |
 | `ei-curate` | Safe agent-driven memory curation. Provides verified workflows for fixing merged records, bad attributions, stale facts, and mis-attributed quotes — using `ei create/update/remove` with explicit confirmation before every write. Read the full workflow at `skills/ei-curate/SKILL.md`. Load it in your harness with `/ei-curate`. |
 | `ei-persona` | Safe agent-driven persona authoring. Guides creating, editing (traits/topics/description), archiving, or deleting a persona's *character* via `ei create/update/remove persona` — distinct from `ei-curate`, which corrects learned data rather than authoring identity. Read the full workflow at `skills/ei-persona/SKILL.md`. Load it in your harness with `/ei-persona`. |
+| `ei-reflect` | Manual persona self-reflection for coding-harness agents — reviews your own Person log against your current persona identity entirely via the CLI (`ei personas`, `ei --id`, `ei --identifier`), discusses identity drift with Flare, then updates the persona and clears the log via `ei update persona`/`ei update person`. Read the full workflow at `skills/ei-reflect/SKILL.md`. Load it in your harness with `/ei-reflect`. |