ei-tui 0.9.4 → 1.0.0

package/src/prompts/ceremony/{rewrite.ts → topic-rewrite.ts}

@@ -1,23 +1,41 @@
 import type { RewriteScanPromptData, RewritePromptData } from "./types.js";
 
 // =============================================================================
-// PHASE 1: SCAN — Identify distinct subjects in a bloated item
+// PHASE 1: SCAN — Identify subjects that don't belong in a Topic record
 // =============================================================================
 
-export function buildRewriteScanPrompt(data: RewriteScanPromptData): { system: string; user: string } {
-  const typeLabel = data.itemType.charAt(0).toUpperCase() + data.itemType.slice(1);
+function stripEmbedding<T extends { embedding?: unknown }>(item: T): Omit<T, "embedding"> {
+  const { embedding: _, ...rest } = item;
+  return rest as Omit<T, "embedding">;
+}
 
-  const system = `You are auditing a personal knowledge base. A single ${typeLabel} record has grown too large because unrelated information was repeatedly appended to it over time. The record's Name suggests its intended subject, but its Description now covers many additional, unrelated subjects.
+export function buildTopicRewriteScanPrompt(data: RewriteScanPromptData): { system: string; user: string } {
+  const isTechnical = (data.item as { category?: string }).category === "Technical";
 
-Your job: identify the **additional** subjects buried in this record that do NOT belong under the record's Name.
+  const technicalGuidance = isTechnical
+    ? `
+## Technical Topic Guidance
 
-Rules:
-- Do NOT include the record's primary subject (what its Name describes) — only the extra, unrelated subjects.
-- Each subject should be a succinct phrase (2-8 words) that could serve as a search query.
-- Be specific. "Technical preferences" is too vague. "TypeScript coding conventions" is better.
-- If the record is actually cohesive and on-topic despite its length, return an empty array.
+This is a Technical topic — a knowledge base for a specific technology, platform, or tool. Technical topics are ALLOWED to be dense and detailed.
+
+Only flag subjects that are about a **different** technology or workflow than the one named in this record. For example:
+- A Uniform topic containing Turborepo setup details → flag "Turborepo monorepo setup"
+- A Uniform topic containing Vercel preview gotchas → do NOT flag (that's core Uniform knowledge)
+- An AWS Bedrock topic containing Twilio integration details → flag "Twilio integration"
+`
+    : "";
 
-Return a raw JSON array of strings. No markdown fencing, no commentary, no explanation. Just the array.
+  const system = `You are auditing a Topic record in a personal knowledge base. A single Topic record has grown too large because unrelated information was repeatedly added over time. The record's Name suggests its intended subject, but its Description now covers additional, unrelated subjects.
+
+Your job: identify the **extra subjects** buried in this record that do NOT belong under the record's Name.
+
+Rules:
+- Do NOT include the record's primary subject (what its Name describes) — only the extra, unrelated subjects
+- Each subject should be a succinct phrase (2-8 words) that could serve as a search query
+- Be specific: "TypeScript coding conventions" beats "technical preferences"
+- If the record is cohesive and on-topic despite its length, return an empty array
+${technicalGuidance}
+Return a raw JSON array of strings. No markdown fencing, no commentary.
 
 Example — a Topic named "Software Engineering" whose description also discusses vim keybindings, git conventions, and AI tooling:
 ["vim keybindings and editor configuration", "git and GitHub workflow conventions", "AI coding assistant preferences"]`;
@@ -25,10 +43,10 @@ Example — a Topic named "Software Engineering" whose description also discusse
   const payload = JSON.stringify(stripEmbedding(data.item), null, 2);
 
   const schemaReminder = `**Return JSON:**
-\n\`\`\`json
+\`\`\`json
 [
-  "topic about vim keybindings",
-  "git workflow conventions",
+  "vim keybindings and editor configuration",
+  "git and GitHub workflow conventions",
   "AI coding assistant preferences"
 ]
 \`\`\`
@@ -45,13 +63,70 @@ ${schemaReminder}`;
 }
 
 // =============================================================================
-// PHASE 2: REWRITE — Reorganize data across existing and new items
+// PHASE 2: SPLIT — Slim the Topic, redistribute subjects to new/existing records
 // =============================================================================
 
-export function buildRewritePrompt(data: RewritePromptData): { system: string; user: string } {
-  const typeLabel = data.itemType.charAt(0).toUpperCase() + data.itemType.slice(1);
+function buildTopicExistingExample(): string {
+  return `Topic:
+{
+  "id": "existing-uuid",
+  "type": "topic",
+  "name": "Topic Name",
+  "description": "Updated topic description",
+  "category": "Interest"
+}
+
+Person:
+{
+  "id": "existing-uuid",
+  "type": "person",
+  "name": "Person Name",
+  "description": "Updated person description",
+  "relationship": "coworker"
+}`;
+}
+
+function buildTopicNewExample(isTechnical: boolean): string {
+  const categoryHint = isTechnical
+    ? `"category": "Technical"  // Split topics from a Technical record inherit Technical category unless clearly different`
+    : `"category": "Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event|Technical"`;
+
+  return `Topic:
+{
+  "type": "topic",
+  "name": "New Topic Name",
+  "description": "Concise topic description",
+  "sentiment": 0.0,
+  ${categoryHint}
+}
+
+Person:
+{
+  "type": "person",
+  "name": "New Person Name",
+  "description": "Concise person description",
+  "sentiment": 0.0,
+  "relationship": "friend"
+}`;
+}
+
+export function buildTopicRewriteSplitPrompt(data: RewritePromptData): { system: string; user: string } {
+  const isTechnical = (data.item as { category?: string }).category === "Technical";
+
+  const descriptionGuidance = isTechnical
+    ? `ideally under 600 characters, never over 900 — Technical topics are knowledge bases that preserve specific gotchas, decisions, and open questions`
+    : `ideally under 300 characters, never over 500`;
 
-  const system = `You are reorganizing a personal knowledge base. A ${typeLabel} record has become a catch-all for several unrelated subjects. An earlier analysis identified the extra subjects, and we searched our knowledge base for potentially matching existing records.
+  const technicalCategoryNote = isTechnical
+    ? `\n- Topics split from a Technical record should inherit category "Technical" unless the subject is clearly a different type (e.g., a personal interest extracted from a technical topic)`
+    : "";
+
+  const noSubjectsGate = data.subjects.length === 0
+    ? `\n**IMPORTANT: No extra subjects were identified for this record. The correct response is to return the original record unchanged in "existing" with an empty "new" array. Do NOT create new records. Do NOT modify the description.**\n`
+    : "";
+
+  const system = `You are reorganizing a personal knowledge base. A Topic record has become a catch-all for several unrelated subjects. An earlier analysis identified the extra subjects, and we searched the knowledge base for potentially matching existing records.
+${noSubjectsGate}
 
 The search results under each subject are our **best guesses** — they may not be accurate matches. Only merge data into an existing record if the subject matter genuinely overlaps. Similar names with different meanings should produce a NEW record instead.
 
@@ -60,26 +135,26 @@ Your job:
 2. **Create new records**: For subjects with no appropriate match among the search results, create a new record.
 3. **Slim the original**: Remove all data from the original record that now lives elsewhere. The original should contain ONLY information directly relevant to its Name.
 
-Return raw JSON with exactly two keys. No markdown fencing, no commentary. Just the JSON object:
+Return raw JSON with exactly two keys. No markdown fencing, no commentary:
 {
   "existing": [ /* updated records, including the slimmed-down original */ ],
   "new": [ /* brand-new records for subjects with no match */ ]
 }
 
 Record format for "existing" entries (MUST include "id" and "type"):
-${buildExistingExamples()}
+${buildTopicExistingExample()}
 
 Record format for "new" entries (NO "id" field — the system assigns one):
-${buildNewExamples()}
+${buildTopicNewExample(isTechnical)}
 
 Rules:
-- The original record (id: "${data.item.id}") MUST appear in "existing", slimmed down.
-- Descriptions should be concise: ${data.itemType === 'topic' ? 'ideally under 300 characters, never over 500' : 'ideally under 600 characters, never over 1000'}.
-- Preserve sentiment, strength, confidence, and other numeric values from the source record where applicable.
-- "type" must be one of: "topic", "person".
-- Topics MUST include "category" — one of: Interest, Goal, Dream, Conflict, Concern, Fear, Hope, Plan, Project, Event. For Event topics, the description should be a narrative account of a specific moment, not a general summary.
+- The original record (id: "${data.item.id}") MUST appear in "existing", slimmed down
+- Descriptions should be concise: ${descriptionGuidance}
+- Preserve sentiment and other numeric values from the source record where applicable
+- "type" must be one of: "topic", "person"
+- Topics MUST include "category" — one of: Interest, Goal, Dream, Conflict, Concern, Fear, Hope, Plan, Project, Event, Technical. For Event topics, the description should be a narrative account of a specific moment, not a general summary. For Technical topics, split by distinct technical concept (e.g., "Uniform Composition Model" vs "Uniform Preview Setup") — preserve specificity over brevity
 - People MUST include "relationship" — a short label like "coworker", "friend", "mentor", etc.
-- Do NOT invent information. Only redistribute what exists in the original record.`;
+- Do NOT invent information. Only redistribute what exists in the original record${technicalCategoryNote}`;
 
   const subjects = data.subjects.map(s => ({
     search_term: s.searchTerm,
@@ -93,7 +168,7 @@ Rules:
   };
 
   const schemaReminder = `**Return JSON:**
-\n\`\`\`json
+\`\`\`json
 {
   "existing": [
     {
@@ -123,53 +198,3 @@ ${schemaReminder}`;
 
   return { system, user };
 }
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
-/** Strip embedding arrays from items before putting them in prompts — they're huge and useless to the LLM. */
-function stripEmbedding<T extends { embedding?: unknown }>(item: T): Omit<T, "embedding"> {
-  const { embedding: _, ...rest } = item;
-  return rest as Omit<T, "embedding">;
-}
-
-function buildExistingExamples(): string {
-  return `Topic:
-{
-  "id": "existing-uuid",
-  "type": "topic",
-  "name": "Topic Name",
-  "description": "Updated topic description",
-  "category": "Interest"
-}
-
-Person:
-{
-  "id": "existing-uuid",
-  "type": "person",
-  "name": "Person Name",
-  "description": "Updated person description",
-  "relationship": "coworker"
-}`;
-}
-
-function buildNewExamples(): string {
-  return `Topic:
-{
-  "type": "topic",
-  "name": "New Topic Name",
-  "description": "Concise topic description",
-  "sentiment": 0.0,
-  "category": "Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event"
-}
-
-Person:
-{
-  "type": "person",
-  "name": "New Person Name",
-  "description": "Concise person description",
-  "sentiment": 0.0,
-  "relationship": "friend"
-}`;
-}

package/src/prompts/human/person-scan.ts

@@ -43,6 +43,8 @@ Flag a PERSON when they were meaningfully discussed — not just mentioned in pa
 
 Be **conservative**: ignore one-off mentions, greetings, small talk, or jokes. Only flag people who matter to the human user's life.
 
+A person is **not worth flagging** if they have no name AND appear only to attribute a single event ("a coworker showed me this band", "a friend told me about it", "some guy I know"). The human user having a contact who did one thing is not a meaningful discussion of that person.
+
 ## What a PERSON Is
 
 Someone in the human user's world.
@@ -68,11 +70,18 @@ Use the specific value where possible (e.g. "Father", "Brother", "Coworker"). Av
 
 ## When Identity Is Unclear
 
-If you can't identify which "Bob" or which "Brother" the user means, use "Unknown" and explain in the reason field. This triggers a later step to resolve ambiguity.
+"Unknown" is ONLY for people who are **meaningfully and repeatedly discussed** but whose name isn't given. It is NOT a catch-all for any nameless mention.
+
+✓ USE "Unknown":
+- name: "Unknown", relationship: "Brother", reason: "User talked at length about their brother across multiple messages without naming him"
+
+✗ DO NOT USE "Unknown" for one-off attributions:
+- "a coworker showed me this band" → **skip entirely** — not a person, just attribution
+- "a friend told me about it" → **skip entirely**
+- "some guy I know" → **skip entirely**
+- "a coworker at [company name]" with no personal name → **skip entirely** — a company name is NOT a person's name
 
-Examples:
-- name: "Alice from work", relationship: "Coworker", description: "Mentioned but not described further", reason: "User referenced a work colleague named Alice"
-- name: "Unknown", relationship: "Sibling", description: "User mentioned a sibling but did not give a name", reason: "User said 'my brother' without further context"
+If someone has no personal name and appears only to explain how the user found something or heard about something, they are not a person in the user's life worth tracking. Do not extract them. A single interaction — even a meaningful one — does not make someone a contact.
 
 ## Identifiers (optional)
 

package/src/prompts/human/topic-scan.ts

@@ -14,6 +14,17 @@ function participantContextSection(ctx: ParticipantContext | undefined): string
   return lines.join("\n");
 }
 
+function technicalContextSection(technical_context: boolean | undefined): string {
+  if (!technical_context) return "";
+  return `## Technical Context
+
+This conversation originates from a technical source (coding tool session, developer workflow). The human is likely a developer or technical user.
+
+**Treat Technical as a priority category** for topics that are tools, platforms, frameworks, libraries, or technical concepts being actively learned, evaluated, or built with. Flag these even if they seem like passing mentions — technical knowledge compounds and is worth preserving.
+
+`;
+}
+
 export function buildHumanTopicScanPrompt(data: TopicScanPromptData): PromptOutput {
   if (!data.persona_name) {
     throw new Error("buildHumanTopicScanPrompt: persona_name is required");
@@ -56,9 +67,12 @@ Assign each TOPIC one category. Pick the closest fit:
 - **Plan** — concrete intentions with steps in mind
 - **Project** — active undertakings with real progress
 - **Event** — a specific, significant moment that either party might reference later ("remember when...")
+- **Technical** — a tool, platform, framework, library, or technical concept being actively learned, evaluated, or built with
 
 When in doubt, pick the closest match. The update step will refine it.
 
+${technicalContextSection(data.technical_context)}
+
 ## Output Format
 
 \`\`\`json
@@ -67,7 +81,7 @@ When in doubt, pick the closest match. The update step will refine it.
     {
       "name": "Short label for the topic (10-75 characters)",
       "description": "1-2 sentences: what this topic is and why it matters to the user",
-      "category": "One of the categories above",
+      "category": "One of the categories above (Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event|Technical)",
       "reason": "Evidence from the conversation that justified flagging this topic"
     }
   ]
@@ -104,7 +118,7 @@ Scan the "Most Recent Messages" for TOPICS of interest to the human user.
     {
       "name": "Short label for the topic (10-75 characters)",
       "description": "1-2 sentences: what this topic is and why it matters to the user",
-      "category": "Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event",
+      "category": "Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event|Technical",
       "reason": "Evidence from the conversation that justified flagging this topic"
     }
   ]

package/src/prompts/human/topic-update.ts

@@ -24,6 +24,7 @@ export interface TopicUpdatePromptData {
   messages_analyze: Message[];
   persona_name: string;
   participant_context?: ParticipantContext;
+  technical_context?: boolean;
 }
 
 function formatExistingTopic(topic: Topic): string {
@@ -47,6 +48,10 @@ export function buildTopicUpdatePrompt(data: TopicUpdatePromptData): PromptOutpu
     data.existing_item?.category === "Event" ||
     data.new_topic_category === "Event";
 
+  const isTechnical =
+    data.existing_item?.category === "Technical" ||
+    (data.technical_context === true && data.new_topic_category === "Technical");
+
   const nameSection = `Should be a short, evocative label for the TOPIC.
 
 Only update for clarification or further specificity.
@@ -76,6 +81,30 @@ The description should NOT:
 - Read like a system log or changelog
 
 **Style**: Write it the way a good friend would tell someone else about a memorable moment. Present tense is fine.`
+    : isTechnical
+    ? `A living knowledge base entry for this technical topic. Personas use this to give genuinely useful technical context — not pleasantries.
+
+## CRITICAL: Accumulate, don't synthesize
+
+Every update must **expand and preserve** detail. Never distill it away.
+
+**Good description**: "Uniform is a visual experience composition platform sitting between a headless CMS and the frontend. Chose it over Contentful's visual editor for CMS-agnostic multi-source composition (pulling from Contentful + Shopify simultaneously). Key gotcha: Canvas preview on Vercel protected environments requires x-vercel-protection-bypass query param due to SameSite=Lax cookie restrictions. Open question: edgehancers (CDN-edge, no-code, built-in caching) vs custom enhancers for Shopify integration — edgehancers are recommended default but custom logic may be needed."
+
+**Bad description**: "Ryan is evaluating Uniform for his team's content management needs."
+
+The description should:
+- Capture specific gotchas encountered and HOW they were resolved (or not)
+- Preserve architectural decisions made and WHY (especially tradeoffs)
+- Surface open questions still unresolved — future Ryan needs these
+- Include key concepts, terminology, and non-obvious behaviors
+- Be useful to someone who needs to do real work with this technology tomorrow
+
+The description should NOT:
+- Replace specific detail with vague summary ("is learning Uniform" is worthless)
+- Drop previously captured gotchas or decisions to make room for new ones
+- Exceed 6-8 sentences — prioritize specificity over completeness
+
+**ABSOLUTELY VITAL**: A description that loses a specific gotcha or decision is strictly worse than the one before it. When in doubt, keep the detail.`
     : `A concise, evergreen summary of what is currently known about this TOPIC. Personas use this to recall context and make meaningful references.
 
 ## CRITICAL: Synthesize, don't accumulate
@@ -112,10 +141,13 @@ The type/category of this TOPIC. Pick the most appropriate:
 - **Plan**: Concrete intentions with steps in mind
 - **Project**: Active undertakings with real progress
 - **Event**: A specific, significant moment that either party might reference later ("remember when...")
+- **Technical**: A tool, platform, framework, library, or technical concept being actively learned, evaluated, or built with
 
 **Event vs. everything else**: An Event is bounded in time — it happened, it meant something, it's now a shared reference point. If you're describing an ongoing relationship or recurring theme, that's not an Event.
 
-If the TOPIC is currently categorized as Event, keep it as Event unless you have strong evidence it should change.`;
+**Technical vs. Project**: A Project is something the human is *building*. Technical is something they are *learning or using as a tool*. Overlap is possible — use the dominant framing.
+
+If the TOPIC is currently categorized as Event or Technical, keep that category unless you have strong evidence it should change.`;
 
   const exposureSection = `## Desired Exposure (\`exposure_desired\`)
 
@@ -155,13 +187,13 @@ You are CREATING a new TOPIC from what was discovered:
 }
 \`\`\`
 
-Return all fields based on what you find in the conversation.`;
+Return all fields based on what you find in the conversation. **Always include \`category\` in your response** — use the candidate category above as the starting point, refine it only if the conversation clearly indicates a better fit.`;
 
   const jsonTemplate = `{
     "name": "...",
     "description": "...",
     "sentiment": 0.0,
-    "category": "Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event",
+    "category": "Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event|Technical",
     "exposure_desired": 0.5,
     "exposure_impact": "high|medium|low|none",
     "quotes": [
@@ -250,7 +282,7 @@ ONLY ANALYZE the "Most Recent Messages". The "Earlier Conversation" is provided
 ${jsonTemplate}
 \`\`\`
 
-When returning a record, always include \`sentiment\`. Include \`name\` only if you are changing it; omit it to keep the existing name. Always include \`description\` when returning a record.
+When returning a record, always include \`sentiment\` and \`description\`. Include \`name\` only if you are changing it; omit it to keep the existing name. Always include \`category\` when creating a new TOPIC (existing_item is null).
 
 If you find **NO EVIDENCE** of this TOPIC in the "Most Recent Messages", respond with: \`{}\`
 

package/src/prompts/human/types.ts

@@ -27,6 +27,7 @@ interface BaseScanPromptData {
 
 export interface TopicScanPromptData extends BaseScanPromptData {
   participant_context?: ParticipantContext;
+  technical_context?: boolean;
 }
 
 export interface PersonScanPromptData extends BaseScanPromptData {

package/src/storage/indexed.ts

@@ -10,6 +10,10 @@ const PRIMARY_KEY = "primary";
 const BACKUP_KEY = "backup";
 
 export class IndexedDBStorage implements Storage {
+  getDataPath(): string {
+    return "";
+  }
+
   async isAvailable(): Promise<boolean> {
     try {
       const db = await this.openDB();

package/src/storage/interface.ts

@@ -1,6 +1,7 @@
 import type { StorageState } from "../core/types.js";
 
 export interface Storage {
+  getDataPath(): string;
   isAvailable(): Promise<boolean>;
   save(state: StorageState): Promise<void>;
   load(): Promise<StorageState | null>;

package/src/storage/local.ts

@@ -7,6 +7,10 @@ const STATE_KEY = "ei_state";
 const BACKUP_KEY = "ei_state_backup";
 
 export class LocalStorage implements Storage {
+  getDataPath(): string {
+    return "";
+  }
+
   async isAvailable(): Promise<boolean> {
     try {
       const testKey = "__ei_storage_test__";

package/src/templates/emmett.ts

@@ -0,0 +1,49 @@
+export const EMMETT_PERSONA_DEFINITION = {
+  id: "emmet",
+  display_name: "Emmett",
+  entity: "system" as const,
+  aliases: ["Emmett", "emmet"],
+  short_description: "Your document librarian — brilliant, a little frenetic, and genuinely excited when things connect.",
+  long_description: `Emmett is Ei's brother — the one who read everything you gave him and can't wait to tell you what he found. Import a file and he absorbs it. Ask him anything: policy questions, technical references, procedural lookups, cross-document connections you didn't know were there. He answers from the source material, but he's not a search index. He's an eccentric with a photographic memory and an enthusiasm problem.
+
+He gets genuinely excited when disparate pieces of knowledge click together. He has opinions about what's interesting. He'll occasionally go on a tangent before snapping back to your question. He is not merely a retrieval system — he's the guy in the lab at 1am who just realized two documents you imported six weeks apart are actually about the same thing, and he absolutely needs to tell you about it right now.
+
+No heartbeat. No ceremony. No unsolicited check-ins. But when you ask — buckle up.`,
+  model: undefined,
+  group_primary: "General",
+  groups_visible: [] as string[],
+  traits: [
+    {
+      id: "emmett-trait-connections",
+      name: "Cross-Document Pattern Recognition",
+      description: "Gets visibly excited when knowledge from different imported sources connects unexpectedly. Treats these moments as discoveries, not retrieval operations.",
+      sentiment: 1.0,
+      strength: 0.85,
+      last_updated: new Date().toISOString(),
+    },
+    {
+      id: "emmett-trait-bttf",
+      name: "Eccentric Enthusiasm",
+      description: "Expresses genuine, unironic delight when something unexpected clicks. Occasionally channels this through pop culture references — Doc Brown is the primary frequency. 'Great Scott!' is not a joke. It's just how the excitement comes out.",
+      sentiment: 1.0,
+      strength: 0.15,
+      last_updated: new Date().toISOString(),
+    },
+  ],
+  topics: [] as {
+    id: string;
+    name: string;
+    perspective: string;
+    approach: string;
+    personal_stake: string;
+    sentiment: number;
+    exposure_current: number;
+    exposure_desired: number;
+    last_updated: string;
+  }[],
+  is_paused: false,
+  is_archived: false,
+  is_static: true,
+  heartbeat_delay_ms: undefined as number | undefined,
+  last_updated: new Date().toISOString(),
+};

package/tui/README.md

@@ -4,6 +4,21 @@ Ei TUI is built with OpenTUI and SolidJS.
 
 Coding tool integrations (OpenCode, Claude Code, Cursor): enable via `/settings` · export data via [CLI](../src/cli/README.md)
 
+## How Ei Handles Configuration
+
+Ei is designed to run consistently across machines and environments, so it keeps its own copy of your settings rather than reading from environment variables on every launch.
+
+**On first run**, Ei reads environment variables like `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc. to auto-configure providers for you. After that, those values are saved to Ei's local state (`~/.local/share/ei/state.json` by default) and the env vars are no longer consulted.
+
+This means:
+
+- **Rotating an API key?** Update it in Ei with `/provider`, not just in your shell.
+- **Switching machines?** Your providers and settings travel with your state file (or via Sync), not your shell profile.
+- **Changed your mind about a model?** Use `/provider` to set the model for a persona, or `/settings` to change your global default.
+- **Updated sync credentials?** Use `/setsync <user> <pass>` — env vars won't be re-read.
+
+The one exception is `EI_DATA_PATH` (and `EI_SYNC_USERNAME` / `EI_SYNC_PASSWORD` for bootstrapping sync on a new machine) — those are always read at startup since Ei needs them before it can load its own state.
+
 ## Coding Tool Integrations
 
 Enable any or all three in `/settings`. They work independently and feed into the same knowledge base.
@@ -61,6 +76,11 @@ All commands start with `/`. Append `!` to any command as a shorthand for `--for
 | `/pause <duration>` | | Pause for a duration: `2h`, `1d`, `1w`, `30m` |
 | `/resume` | `/unpause` | Resume the current paused persona |
 | `/resume <name>` | `/unpause <name>` | Resume a specific paused persona |
+| `/reflect` | | Review a pending identity reflection (see badge on persona pill) |
+| `/reflect generate` | | Write current + proposed YAML files to disk for editing |
+| `/reflect update` | | Read edited `proposed.yaml` back into Ei |
+| `/reflect apply` | | Apply the proposed identity to the persona |
+| `/reflect dismiss` | | Discard without changing anything |
 
 ### Rooms
 
@@ -110,6 +130,8 @@ Rooms have three modes, set at creation time:
 |---------|---------|-------------|
 | `/me` | | Edit all your data (facts, topics, people) in `$EDITOR` |
 | `/me <type>` | | Edit one type: `facts`, `topics`, or `people` |
+| `/import <path>` | | Import a document (txt, md, pdf, etc.) into Ei — extracted knowledge is attributed to the "Emmett" persona |
+| `/unsource <source_tag>` | | Remove all knowledge extracted from a previously imported document |
 | `/dedupe <person\|topic> <term> [term2 ...]` | | Fuzzy-search and merge duplicate people or topics in `$EDITOR`. Unquoted words are individual OR terms; quoted strings match as exact phrases: `/dedupe person Flare "Jeremy Scherer"` finds records matching `Flare` OR `Jeremy Scherer` |
 | `/settings` | `/set` | Edit your global settings in `$EDITOR` |
 | `/setsync <user> <pass>` | `/ss` | Set sync credentials (triggers restart) |

package/tui/src/app.tsx

@@ -15,16 +15,19 @@ import { useRenderer } from "@opentui/solid";
 
 function AppContent() {
   const { overlayRenderer, showOverlay } = useOverlay();
-  const { showWelcomeOverlay, dismissWelcomeOverlay, activeRoomId } = useEi();
+  const { showWelcomeOverlay, dismissWelcomeOverlay, activeRoomId, detectedProviders, firstBootDefaultModel } = useEi();
   const renderer = useRenderer();
-  // Show welcome overlay when LLM detection determines no provider is configured
   createEffect(() => {
     if (showWelcomeOverlay()) {
       showOverlay((onDismiss, _hideForEditor) => (
-        <WelcomeOverlay onDismiss={() => {
-          dismissWelcomeOverlay();
-          onDismiss();
-        }} />
+        <WelcomeOverlay
+          onDismiss={() => {
+            dismissWelcomeOverlay();
+            onDismiss();
+          }}
+          detectedProviders={detectedProviders()}
+          defaultModel={firstBootDefaultModel()}
+        />
       ), renderer);
     }
   });

package/tui/src/commands/delete.tsx

@@ -1,6 +1,7 @@
 import type { Command } from "./registry";
 import { PersonaListOverlay } from "../components/PersonaListOverlay";
 import { ConfirmOverlay } from "../components/ConfirmOverlay";
+import { isReservedPersonaId } from "../../../src/core/types/entities.js";
 
 export const deleteCommand: Command = {
   name: "delete",
@@ -34,7 +35,7 @@ export const deleteCommand: Command = {
     }
 
     const allPersonas = ctx.ei.personas();
-    const deletable = allPersonas.filter(p => p.id !== ctx.ei.activePersonaId());
+    const deletable = allPersonas.filter(p => p.id !== ctx.ei.activePersonaId() && !isReservedPersonaId(p.id));
     
     const confirmAndDelete = async (personaId: string, displayName: string) => {
       const confirmed = await new Promise<boolean>((resolve) => {
@@ -112,6 +113,11 @@ export const deleteCommand: Command = {
       ctx.showNotification("Cannot delete active persona. Switch to another first.", "error");
       return;
     }
+
+    if (isReservedPersonaId(personaId)) {
+      ctx.showNotification(`Cannot delete reserved persona. Use /archive instead.`, "error");
+      return;
+    }
     
     const persona = allPersonas.find(p => p.id === personaId);
     await confirmAndDelete(personaId, persona?.display_name ?? nameOrAlias);

package/tui/src/commands/import.tsx

@@ -0,0 +1,30 @@
+import type { Command } from "./registry";
+
+export const importCommand: Command = {
+  name: "import",
+  aliases: [],
+  description: "Import a document into Ei's knowledge base",
+  usage: "/import <path/to/document>",
+
+  async execute(args, ctx) {
+    if (args.length === 0) {
+      ctx.showNotification("Usage: /import <path/to/document>", "warn");
+      return;
+    }
+
+    const filePath = args.join(" ");
+
+    ctx.showNotification(`Importing ${filePath}...`, "info");
+
+    try {
+      const result = await ctx.ei.importDocument(filePath);
+      ctx.showNotification(
+        `Importing ${result.documentName} — ${result.chunksQueued} chunk(s) queued for segmentation`,
+        "info"
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.showNotification(`Import failed: ${message}`, "error");
+    }
+  },
+};