ei-tui 0.6.4 → 0.6.5

package/package.json

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

package/src/core/handlers/dedup.ts

@@ -114,7 +114,9 @@ export async function handleDedupCurate(
   // =========================================================================
   // PHASE 1: Update Quote foreign keys FIRST (before deletions)
   // =========================================================================
-  
+
+  const liveEntityIds = new Set(entityList.map((e: Fact | Topic | Person) => e.id));
+
   for (const removal of decisions.remove) {
     const quotes = state.quotes.filter((q: Quote) =>
       q.data_item_ids.includes(removal.to_be_removed)
@@ -123,6 +125,7 @@ export async function handleDedupCurate(
     for (const quote of quotes) {
       const updatedIds = quote.data_item_ids
         .map((id: string) => id === removal.to_be_removed ? removal.replaced_by : id)
+        .filter((id: string) => liveEntityIds.has(id))         // Drop links to already-merged entities
         .filter((id: string, idx: number, arr: string[]) => arr.indexOf(id) === idx);  // Dedupe
       
       stateManager.human_quote_update(quote.id, {

package/src/core/handlers/human-matching.ts

@@ -8,7 +8,7 @@ import {
 import type { PersonIdentifier } from "../types/data-items.js";
 import type { StateManager } from "../state-manager.js";
 import type { ItemMatchResult, ExposureImpact, TopicUpdateResult, PersonUpdateResult } from "../../prompts/human/types.js";
-import { queueTopicUpdate, queuePersonUpdate, type ExtractionContext } from "../orchestrators/index.js";
+import { queueTopicUpdate, queuePersonUpdate, queueTopicValidate, type ExtractionContext } from "../orchestrators/index.js";
 import { getEmbeddingService, getTopicEmbeddingText, getPersonEmbeddingText } from "../embedding-service.js";
 import { calculateExposureCurrent } from "../utils/exposure.js";
 
@@ -28,12 +28,13 @@ export function handleTopicMatch(response: LLMResponse, state: StateManager): vo
   const { messages_context, messages_analyze } = resolveMessageWindow(response, state);
 
   let matched_guid = result.matched_guid;
+  let resolvedTopic: import('../types/data-items.js').Topic | null = null;
   if (matched_guid === "new") {
     matched_guid = null;
   } else if (matched_guid) {
     const human = state.getHuman();
-    const found = human.topics.find(t => t.id === matched_guid);
-    if (!found) {
+    resolvedTopic = human.topics.find(t => t.id === matched_guid) ?? null;
+    if (!resolvedTopic) {
       console.warn(`[handleTopicMatch] matched_guid "${matched_guid}" not found in topics — treating as new`);
       matched_guid = null;
     }
@@ -57,7 +58,7 @@ export function handleTopicMatch(response: LLMResponse, state: StateManager): vo
     extraction_model: response.request.data.extraction_model as string | undefined,
   };
 
-  queueTopicUpdate(result, context, state);
+  queueTopicUpdate(result, context, state, resolvedTopic);
   const matched = matched_guid ? `matched GUID "${matched_guid}"` : "no match (new topic)";
   console.log(`[handleTopicMatch] topic "${context.candidateName}": ${matched}`);
 }
@@ -74,12 +75,13 @@ export function handlePersonMatch(response: LLMResponse, state: StateManager): v
   const { messages_context, messages_analyze } = resolveMessageWindow(response, state);
 
   let matched_guid = result.matched_guid;
+  let resolvedPerson: import('../types/data-items.js').Person | null = null;
   if (matched_guid === "new") {
     matched_guid = null;
   } else if (matched_guid) {
     const human = state.getHuman();
-    const found = human.people.find(p => p.id === matched_guid);
-    if (!found) {
+    resolvedPerson = human.people.find(p => p.id === matched_guid) ?? null;
+    if (!resolvedPerson) {
       console.warn(`[handlePersonMatch] matched_guid "${matched_guid}" not found in people — treating as new`);
       matched_guid = null;
     }
@@ -103,7 +105,7 @@ export function handlePersonMatch(response: LLMResponse, state: StateManager): v
     extraction_model: response.request.data.extraction_model as string | undefined,
   };
 
-  queuePersonUpdate(result, context, state);
+  queuePersonUpdate(result, context, state, resolvedPerson);
   const matched = matched_guid ? `matched GUID "${matched_guid}"` : "no match (new person)";
   console.log(`[handlePersonMatch] person "${context.candidateName}": ${matched}`);
 }
@@ -199,6 +201,11 @@ export async function handleTopicUpdate(response: LLMResponse, state: StateManag
     : state.messages_get(personaId);
   await validateAndStoreQuotes(result.quotes, allMessages, itemId, personaDisplayName, personaGroup, state);
 
+  if (isNewItem && embedding) {
+    const extractionModel = (response.request.data as Record<string, unknown>).extraction_model as string | undefined;
+    await queueTopicValidate(topic, state, extractionModel);
+  }
+
   console.log(`[handleTopicUpdate] ${isNewItem ? "Created" : "Updated"} topic "${resolvedName}"`);
 }
 

package/src/core/handlers/index.ts

@@ -88,4 +88,5 @@ export const handlers: Record<LLMNextStep, ResponseHandler> = {
   handleRoomJudge,
   handlePersonaPreview,
   [LLMNextStep.HandlePersonIdentifierMigration]: handlePersonIdentifierMigration,
+  [LLMNextStep.HandleTopicValidate]: handleDedupCurate,
 };

package/src/core/orchestrators/human-extraction.ts

@@ -13,6 +13,7 @@ import {
   type ItemMatchResult,
   type ParticipantContext,
 } from "../../prompts/human/index.js";
+import { buildValidatePrompt } from "../../prompts/ceremony/dedup.js";
 import { chunkExtractionContext } from "./extraction-chunker.js";
 import { getEmbeddingService, findTopK, getTopicEmbeddingText } from "../embedding-service.js";
 import { resolveTokenLimit } from "../llm-client.js";
@@ -290,6 +291,13 @@ export function queueDirectTopicUpdate(
 const EMBEDDING_TOP_K = 20;
 const EMBEDDING_MIN_SIMILARITY = 0.3;
 
+/**
+ * Minimum cosine similarity to trigger the post-create validate step.
+ * Higher than EMBEDDING_MIN_SIMILARITY (0.3) because we need near-duplicates,
+ * not just vague thematic overlap.
+ */
+export const VALIDATE_MIN_SIMILARITY = 0.85;
+
 /**
  * Queue a topic match request using embedding-based similarity (topics only).
  */
@@ -380,15 +388,15 @@ export function queueTopicUpdate(
     candidateCategory: string;
     extraction_model?: string;
   },
-  state: StateManager
+  state: StateManager,
+  resolvedItem?: Topic | null
 ): number {
-  const human = state.getHuman();
   const matchedGuid = matchResult.matched_guid;
   const isNewItem = matchedGuid === null;
 
-  let existingItem: Topic | null = null;
-  if (!isNewItem && matchedGuid) {
-    existingItem = human.topics.find(t => t.id === matchedGuid) ?? null;
+  let existingItem: Topic | null = resolvedItem ?? null;
+  if (!isNewItem && matchedGuid && existingItem === null) {
+    existingItem = state.getHuman().topics.find(t => t.id === matchedGuid) ?? null;
   }
 
   const extractionOptions: ExtractionOptions = { extraction_model: context.extraction_model };
@@ -523,15 +531,15 @@ export function queuePersonUpdate(
     candidateIdentifiers?: PersonIdentifier[];
     extraction_model?: string;
   },
-  state: StateManager
+  state: StateManager,
+  resolvedItem?: Person | null
 ): number {
-  const human = state.getHuman();
   const matchedGuid = matchResult.matched_guid;
   const isNewItem = matchedGuid === null;
 
-  let existingItem: Person | null = null;
-  if (!isNewItem && matchedGuid) {
-    existingItem = human.people.find(p => p.id === matchedGuid) ?? null;
+  let existingItem: Person | null = resolvedItem ?? null;
+  if (!isNewItem && matchedGuid && existingItem === null) {
+    existingItem = state.getHuman().people.find(p => p.id === matchedGuid) ?? null;
   }
 
   const candidateIdentifiers = context.candidateIdentifiers ?? [];
@@ -548,7 +556,7 @@ export function queuePersonUpdate(
   }
 
   const userIdentifierTypes = [...new Set(
-    human.people
+    state.getHuman().people
       .flatMap(p => (p.identifiers ?? []).map(i => i.type))
       .filter(Boolean)
   )];
@@ -598,4 +606,55 @@ export function queuePersonUpdate(
   return chunks.length;
 }
 
+export async function queueTopicValidate(
+  newTopic: Topic,
+  state: StateManager,
+  extractionModel?: string
+): Promise<void> {
+  if (!newTopic.embedding || newTopic.embedding.length === 0) {
+    console.log(`[queueTopicValidate] Skipping "${newTopic.name}" — no embedding available`);
+    return;
+  }
+
+  const human = state.getHuman();
+  const candidates = human.topics.filter(t => t.id !== newTopic.id && t.embedding && t.embedding.length > 0);
+
+  if (candidates.length === 0) {
+    console.log(`[queueTopicValidate] No existing topics with embeddings to compare against`);
+    return;
+  }
+
+  const topResult = findTopK(newTopic.embedding, candidates, 1);
+  if (topResult.length === 0 || topResult[0].similarity < VALIDATE_MIN_SIMILARITY) {
+    const best = topResult[0];
+    console.log(`[queueTopicValidate] "${newTopic.name}" is genuinely new (best match: ${best ? `"${best.item.name}" @ ${best.similarity.toFixed(3)}` : "none"})`);
+    return;
+  }
+
+  const existingTopic = topResult[0].item;
+  const similarity = topResult[0].similarity;
+
+  console.log(`[queueTopicValidate] Near-duplicate candidate: "${newTopic.name}" ↔ "${existingTopic.name}" (${similarity.toFixed(3)}) — queuing validate`);
+
+  const prompt = buildValidatePrompt({
+    established: existingTopic,
+    newcomer: newTopic,
+    itemType: "topic",
+    similarity,
+  });
+
+  state.queue_enqueue({
+    type: LLMRequestType.JSON,
+    priority: LLMPriority.Normal,
+    model: extractionModel,
+    system: prompt.system,
+    user: prompt.user,
+    next_step: LLMNextStep.HandleTopicValidate,
+    data: {
+      entity_type: "topic",
+      entity_ids: [existingTopic.id, newTopic.id],
+    },
+  });
+}
+
 

package/src/core/orchestrators/index.ts

@@ -8,6 +8,8 @@ export {
   queueTopicUpdate,
   queuePersonUpdate,
   queueEventSummary,
+  queueTopicValidate,
+  VALIDATE_MIN_SIMILARITY,
   type ExtractionContext,
   type ExtractionOptions,
 } from "./human-extraction.js";

package/src/core/types/enums.ts

@@ -51,6 +51,7 @@ export enum LLMNextStep {
   HandleRoomJudge = "handleRoomJudge",
   HandlePersonaPreview = "handlePersonaPreview",
   HandlePersonIdentifierMigration = "handlePersonIdentifierMigration",
+  HandleTopicValidate = "handleTopicValidate",
 }
 
 export enum ProviderType {

package/src/prompts/ceremony/dedup.ts

@@ -1,4 +1,4 @@
-import type { DedupPromptData } from "./types.js";
+import type { DedupPromptData, ValidatePromptData } from "./types.js";
 
 // =============================================================================
 // DEDUP CURATOR — Merge duplicate entities with data preservation
@@ -140,6 +140,94 @@ ${schemaReminder}`;
   return { system, user };
 }
 
+// =============================================================================
+// VALIDATE — Binary merge decision for a newly created record
+// =============================================================================
+
+export function buildValidatePrompt(data: ValidatePromptData): { system: string; user: string } {
+  const typeLabel = data.itemType.charAt(0).toUpperCase() + data.itemType.slice(1);
+  const pct = Math.round(data.similarity * 100);
+
+  const system = `# Your Task
+
+A new ${typeLabel} record was just created from a real conversation. The moment it landed in the system, we checked it against everything already stored and found one record with a similarity score of ${pct}% — high enough that they might be the same thing under different words.
+
+You are the last gate before a duplicate takes root.
+
+**Established record**: Has been in the system. Learned from prior conversations.
+**Newcomer**: Just synthesized from the most recent conversation. Description is current-state, not a log.
+
+## What You're Deciding
+
+Are these the same thing — the same interest, concern, goal, or moment — described twice? Or are they genuinely distinct, and both deserve to exist?
+
+Similarity of meaning is not the same as identity. "Concern about job security" and "Fear of career stagnation" share semantic space. They are not the same record.
+
+Ask yourself: *If a persona referenced the established record in conversation, would the newcomer feel like a repeat? Or would it feel like something different being said?*
+
+If they are the same thing: **merge**. Preserve every unique detail from both. The newcomer's description is synthesized and current — weight it, but don't discard what the established record learned first.
+
+If they are distinct: **keep both**. Return them both in \`update\` unchanged. Leave \`remove\` and \`add\` empty.
+
+## Output Format
+
+\`\`\`json
+{
+  "update": [ /* one or both records — include ALL fields from whichever survive */ ],
+  "remove": [ /* { "to_be_removed": "uuid", "replaced_by": "uuid" } — only if merging */ ],
+  "add": []
+}
+\`\`\`
+
+Rules:
+- \`add\` is always empty here. We are not creating new records from this decision.
+- If merging: the merged record goes in \`update\`, the absorbed record goes in \`remove\`.
+- If keeping both: return both in \`update\` exactly as received. Do not modify either.
+- Descriptions must stay concise — under 300 characters, never over 500. Synthesize; don't concatenate.
+- When merging numeric fields: take the HIGHER value for \`exposure_current\`, \`exposure_desired\`, \`strength\`, \`confidence\`. Average \`sentiment\`.
+- Do NOT invent information. Only what exists in these two records.
+
+Return raw JSON only. No markdown fencing, no commentary.`;
+
+  const payload = JSON.stringify({
+    established: stripEmbedding(data.established),
+    newcomer: stripEmbedding(data.newcomer),
+    item_type: data.itemType,
+    similarity_score: data.similarity,
+  }, null, 2);
+
+  const schemaReminder = `**Return JSON:**
+\n\`\`\`json
+{
+  "update": [
+    {
+      "id": "uuid-of-surviving-record",
+      "type": "${data.itemType}",
+      "name": "canonical name",
+      "description": "merged or unchanged description"
+    }
+  ],
+  "remove": [
+    {
+      "to_be_removed": "uuid-of-absorbed-record",
+      "replaced_by": "uuid-of-surviving-record"
+    }
+  ],
+  "add": []
+}
+\`\`\`
+
+If keeping both, return both in \`update\` unchanged with empty \`remove\` and \`add\`.`;
+
+  const user = `${payload}
+
+---
+
+${schemaReminder}`;
+
+  return { system, user };
+}
+
 // =============================================================================
 // Helpers
 // =============================================================================

package/src/prompts/ceremony/index.ts

@@ -2,7 +2,7 @@ export { buildPersonaExpirePrompt } from "./expire.js";
 export { buildPersonaExplorePrompt } from "./explore.js";
 export { buildDescriptionCheckPrompt } from "./description-check.js";
 export { buildRewriteScanPrompt, buildRewritePrompt } from "./rewrite.js";
-export { buildDedupPrompt } from "./dedup.js";
+export { buildDedupPrompt, buildValidatePrompt } from "./dedup.js";
 export { buildUserDedupPrompt } from "./user-dedup.js";
 export { buildPersonMigrationPrompt, type PersonMigrationPromptData } from "./person-migration.js";
 export type {
@@ -20,4 +20,5 @@ export type {
   RewriteResult,
   DedupPromptData,
   DedupResult,
+  ValidatePromptData,
 } from "./types.js";

package/src/prompts/ceremony/types.ts

@@ -107,6 +107,14 @@ export interface DedupPromptData {
   similarityRange: { min: number; max: number };  // e.g., { min: 0.90, max: 0.98 }
 }
 
+/** Input: exactly 2 records — one established, one just created — for binary merge decision. */
+export interface ValidatePromptData {
+  established: DataItemBase;
+  newcomer: DataItemBase;
+  itemType: RewriteItemType;
+  similarity: number;
+}
+
 /** Output: merge decisions (update/remove/add). */
 export interface DedupResult {
   update: Array<{

package/tui/src/commands/editor.tsx

@@ -26,16 +26,19 @@ export const editorCommand: Command = {
     });
     
     if (result.aborted) {
+      ctx.setInputText("");
       ctx.showNotification("Editor cancelled", "info");
       return;
     }
     
     if (!result.success) {
+      ctx.setInputText("");
       ctx.showNotification("Editor failed to open", "error");
       return;
     }
     
     if (result.content === null) {
+      ctx.setInputText("");
       ctx.showNotification("No changes made", "info");
       return;
     }

package/tui/src/commands/help.tsx

@@ -7,6 +7,6 @@ export const helpCommand: Command = {
   description: "Show help screen",
   usage: "/help or /h",
   execute: async (_args, ctx) => {
-    ctx.showOverlay((_hideOverlay, _hideForEditor) => <HelpOverlay onDismiss={_hideOverlay} />, ctx.renderer);
+    ctx.showOverlay((_hideOverlay, _hideForEditor) => <HelpOverlay onDismiss={_hideOverlay} renderer={ctx.renderer} />, ctx.renderer);
   },
 };

package/tui/src/commands/me.tsx

@@ -6,37 +6,73 @@ import { ConfirmOverlay } from "../components/ConfirmOverlay.js";
 
 type DataType = "facts" | "topics" | "people";
 
-const VALID_TYPES: DataType[] = ["facts", "topics", "people"];
+const TYPE_ALIASES: Record<string, DataType> = {
+  facts: "facts", fact: "facts",
+  topics: "topics", topic: "topics",
+  people: "people", person: "people", persons: "people",
+};
 
 export const meCommand: Command = {
   name: "me",
   aliases: [],
   description: "Edit your data in $EDITOR",
-  usage: "/me [facts|topics|people]",
-  
+  usage: "/me [fact|topic|person] [new | <search>]",
+
   async execute(args, ctx) {
     const human = await ctx.ei.getHuman();
-    
-    const filterArg = args[0]?.toLowerCase();
-    const filterType: DataType | null = filterArg && VALID_TYPES.includes(filterArg as DataType) 
-      ? filterArg as DataType 
-      : null;
-    
-    if (filterArg && !filterType) {
-      ctx.showNotification(`Invalid type: ${filterArg}. Use: facts, topics, people`, "error");
+
+    const typeArg = args[0]?.toLowerCase();
+    const filterType: DataType | null = typeArg ? (TYPE_ALIASES[typeArg] ?? null) : null;
+
+    if (typeArg && !filterType) {
+      ctx.showNotification(`Unknown type: ${typeArg}. Use: fact, topic, person`, "error");
       return;
     }
-    
+
+    const secondArg = args[1]?.toLowerCase();
+    const isNew = secondArg === "new";
+    const searchTerm = !isNew && secondArg ? args.slice(1).join(" ") : null;
+
+    if (isNew && args.length > 2) {
+      ctx.showNotification(
+        `Use /me ${typeArg} new to create, or /me ${typeArg} ${args.slice(2).join(" ")} to search`,
+        "error"
+      );
+      return;
+    }
+
+    if ((isNew || searchTerm) && !filterType) {
+      ctx.showNotification(`Specify a type first: /me fact|topic|person [new | <search>]`, "error");
+      return;
+    }
+
+    const filterItems = <T extends { name: string }>(items: T[]): T[] => {
+      if (isNew) return [];
+      if (searchTerm) return items.filter(i => i.name.toLowerCase().includes(searchTerm.toLowerCase()));
+      return items;
+    };
+
     const filteredHuman = filterType ? {
       ...human,
-      facts: filterType === "facts" ? human.facts : [],
-      topics: filterType === "topics" ? human.topics : [],
-      people: filterType === "people" ? human.people : [],
+      facts:  filterType === "facts"  ? filterItems(human.facts)  : [],
+      topics: filterType === "topics" ? filterItems(human.topics) : [],
+      people: filterType === "people" ? filterItems(human.people) : [],
     } : human;
+
+    const isEmpty = filteredHuman.facts.length === 0
+      && filteredHuman.topics.length === 0
+      && filteredHuman.people.length === 0;
+
+    if (searchTerm && isEmpty) {
+      ctx.showNotification(`No ${filterType} matching "${searchTerm}" — open editor to create one`, "info");
+    }
     
     const personaLookup = new Map(ctx.ei.personas().map(p => [p.id, p.display_name]));
     const allGroups = await ctx.ei.getGroupList();
-    let yamlContent = humanToYAML(filteredHuman, personaLookup, allGroups);
+    const sections = filterType
+      ? new Set<"facts" | "topics" | "people">([filterType])
+      : new Set<"facts" | "topics" | "people">(["facts", "topics", "people"]);
+    let yamlContent = humanToYAML(filteredHuman, personaLookup, allGroups, sections);
     let editorIteration = 0;
     
     while (true) {

package/tui/src/components/HelpOverlay.tsx

@@ -1,10 +1,13 @@
 import { useKeyboard } from "@opentui/solid";
-import { For, onMount, onCleanup } from "solid-js";
-import { getAllCommands } from "../commands/registry";
+import { onMount, onCleanup } from "solid-js";
+import type { CliRenderer } from "@opentui/core";
 import { useKeyboardNav } from "../context/keyboard.js";
+import { spawnPager } from "../util/editor.js";
+import { buildManPage } from "../util/help-content.js";
 
 interface HelpOverlayProps {
   onDismiss: () => void;
+  renderer: CliRenderer;
 }
 
 export function HelpOverlay(props: HelpOverlayProps) {
@@ -14,11 +17,14 @@ export function HelpOverlay(props: HelpOverlayProps) {
 
   useKeyboard((event) => {
     event.preventDefault();
-    props.onDismiss();
+    if (event.name === "m") {
+      props.onDismiss();
+      void spawnPager(buildManPage(), props.renderer);
+    } else {
+      props.onDismiss();
+    }
   });
 
-  const commands = getAllCommands();
-
   return (
     <box
       position="absolute"
@@ -31,43 +37,67 @@ export function HelpOverlay(props: HelpOverlayProps) {
       justifyContent="center"
     >
       <box
-        width={60}
+        width={82}
         backgroundColor="#1a1a2e"
         borderStyle="single"
         borderColor="#586e75"
         padding={2}
         flexDirection="column"
+        gap={1}
       >
 
-        <text fg="#eee8d5">
-          Commands:
-        </text>
-        <For each={commands.sort()}>
-          {(cmd) => (
-            <text fg="#93a1a1">
-              /{cmd.name} - {cmd.description}
-            </text>
-          )}
-        </For>
-        <text> </text>
+        <box flexDirection="row" gap={2}>
+
+          <box flexDirection="column" gap={1} width={38}>
+            <box flexDirection="column">
+              <text fg="#eee8d5">Keybindings</text>
+              <text fg="#93a1a1">  Ctrl+E    Open $EDITOR (preserves input)</text>
+              <text fg="#93a1a1">  Ctrl+C    Clear input / exit</text>
+              <text fg="#93a1a1">  Ctrl+B    Toggle sidebar</text>
+              <text fg="#93a1a1">  Escape    Abort / resume queue</text>
+              <text fg="#93a1a1">  PgUp/Dn  Scroll messages</text>
+            </box>
+
+            <box flexDirection="column">
+              <text fg="#eee8d5">Core</text>
+              <text fg="#93a1a1">  /set          Edit global settings</text>
+              <text fg="#93a1a1">  /q  /q!       Quit  (! = skip sync)</text>
+              <text fg="#93a1a1">  /provider     Manage LLM providers</text>
+              <text fg="#93a1a1">  /me           Edit your data</text>
+              <text fg="#93a1a1">  /d  /d &lt;name&gt; Edit persona details</text>
+            </box>
+          </box>
+
+          <box flexDirection="column" gap={1} width={38}>
+            <box flexDirection="column">
+              <text fg="#eee8d5">Persona</text>
+              <text fg="#93a1a1">  /p  /p new  /p update</text>
+              <text fg="#93a1a1">  /context   Message context</text>
+              <text fg="#93a1a1">  /pause  /resume</text>
+            </box>
+
+            <box flexDirection="column">
+              <text fg="#eee8d5">Rooms</text>
+              <text fg="#93a1a1">  /r  /r new    Room picker / create</text>
+              <text fg="#93a1a1">  /activate     Advance active node</text>
+              <text fg="#93a1a1">  /silence      Pass your turn</text>
+            </box>
+
+            <box flexDirection="column">
+              <text fg="#eee8d5">Extended</text>
+              <text fg="#93a1a1">  /tools        Tool providers</text>
+              <text fg="#93a1a1">  /auth spotify Spotify OAuth</text>
+              <text fg="#93a1a1">  /queue  /dlq  Inspect queues</text>
+            </box>
+          </box>
+
+        </box>
 
-        <text fg="#eee8d5">
-          Keybindings:
-        </text>
-        <text fg="#93a1a1">Escape - Abort operation / Resume queue</text>
-        <text fg="#93a1a1">Ctrl+C - Clear input / Exit</text>
-        <text fg="#93a1a1">Ctrl+B - Toggle sidebar</text>
-        <text fg="#93a1a1">Ctrl+E - Edit in $EDITOR</text>
-        <text fg="#93a1a1">PageUp/Down - Scroll messages</text>
-        <text> </text>
+        <box flexDirection="column">
+          <text fg="#586e75">  m - full manual  |  any key - dismiss</text>
+          <text fg="#2a2a3e">  Ei - 永 (ei) - eternal</text>
+        </box>
 
-        <text fg="#586e75">
-          Press any key to dismiss
-        </text>
-        <text> </text>
-        <text fg="#2a2a3e">
-          Ei - 永 (ei) - eternal
-        </text>
       </box>
     </box>
   );

package/tui/src/context/overlay.tsx

@@ -33,8 +33,10 @@ export const OverlayProvider: ParentComponent = (props) => {
     const hideOverlay = () => {
       logger.debug("[overlay] hideOverlay called");
       setOverlayRenderer(null);
+      cliRenderer?.requestRender();
     };
     setOverlayRenderer(() => () => renderer(hideOverlay, hideForEditor));
+    queueMicrotask(() => cliRenderer?.requestRender());
   };
 
   const hideOverlay = () => {

package/tui/src/index.tsx

@@ -4,6 +4,13 @@ import { App } from "./app";
 
 import { InstanceLock } from "./util/instance-lock";
 import { FileStorage } from "./storage/file";
+import pkg from "../../package.json";
+
+const args = process.argv.slice(2);
+if (args.includes("--version") || args.includes("version") || args.includes("-v")) {
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
 
 const storage = new FileStorage(Bun.env.EI_DATA_PATH);
 const lock = new InstanceLock(storage.getDataPath());

package/tui/src/util/editor.ts

@@ -23,6 +23,41 @@ export interface EditorResult {
   aborted: boolean;
 }
 
+export async function spawnPager(content: string, renderer: CliRenderer): Promise<void> {
+  const pager = process.env.PAGER || "less";
+  const tmpDir = os.tmpdir();
+  const tmpFile = path.join(tmpDir, `ei-help-${Date.now()}.txt`);
+
+  fs.writeFileSync(tmpFile, content, "utf-8");
+
+  await new Promise(resolve => setTimeout(resolve, 50));
+
+  return new Promise((resolve) => {
+    renderer.suspend();
+    renderer.currentRenderBuffer.clear();
+
+    const child = spawn(pager, [tmpFile], {
+      stdio: "inherit",
+      shell: true,
+    });
+
+    child.on("error", () => {
+      try { fs.unlinkSync(tmpFile); } catch {}
+      renderer.resume();
+      renderer.requestRender();
+      resolve();
+    });
+
+    child.on("exit", () => {
+      try { fs.unlinkSync(tmpFile); } catch {}
+      renderer.currentRenderBuffer.clear();
+      renderer.resume();
+      renderer.requestRender();
+      resolve();
+    });
+  });
+}
+
 export async function spawnEditorRaw(options: EditorRawOptions): Promise<EditorResult> {
   const { initialContent, filename } = options;
   const editor = process.env.EDITOR || process.env.VISUAL || "vi";
@@ -152,9 +187,7 @@ export async function spawnEditor(options: EditorOptions): Promise<EditorResult>
         logger.debug("[editor] already suspended before spawn, skipping resume");
       }
       
-      queueMicrotask(() => {
-        renderer.requestRender();
-      });
+      renderer.requestRender();
       
       if (code !== 0) {
         try { fs.unlinkSync(tmpFile); } catch {}

package/tui/src/util/help-content.ts

@@ -0,0 +1,136 @@
+export function buildManPage(): string {
+  return `EI(1)                           Ei Terminal UI                          EI(1)
+
+NAME
+    ei - local-first AI companion with persistent personas
+
+KEYBINDINGS
+    Ctrl+E        Open current input in $EDITOR (preserves text)
+    Ctrl+C        Clear input field (second press exits)
+    Ctrl+B        Toggle sidebar
+    Escape        Abort operation / resume queue
+    PageUp/Down   Scroll message history
+
+CORE COMMANDS
+    /settings, /set
+        Edit global settings in $EDITOR. Configure default model,
+        heartbeat interval, context window, integrations, and more.
+
+    /quit, /q
+        Save, sync, and exit. Add ! to force quit without syncing: /q!
+
+    /provider
+        Open provider picker to select, edit, or create LLM providers.
+        /provider <Name>           Set provider on active persona
+        /provider <Name>:<Model>   Set provider and model explicitly
+        /provider new              Create a new provider
+
+    /me
+        Edit your personal data (facts, topics, people) in $EDITOR.
+        Each section includes a commented stub — uncomment and fill it in
+        to create a new entry. No UUID required; one is generated for you.
+
+        /me fact               Edit only facts (stub included)
+        /me topic              Edit only topics (stub included)
+        /me person             Edit only people (stub included)
+        /me fact new           Open with just the new-fact stub
+        /me fact coffee        Filter facts whose name contains "coffee"
+        /me person "New York"  Quoted search for multi-word names
+
+    /details, /d
+        Edit the current persona's details in $EDITOR.
+        /d <name>     Edit a specific persona by name
+
+PERSONA COMMANDS
+    /persona, /p
+        Open persona picker. Switch, list, or create personas.
+        /p new <name>              Create a new persona
+        /p update <name> [person]  Regenerate persona from a person record
+
+    /context, /messages
+        Edit which messages are included in LLM context.
+
+    /pause
+        Pause the current persona indefinitely.
+        /pause <duration>   Pause for a duration: 2h, 1d, 1w
+
+    /resume, /unpause
+        Resume the current paused persona.
+        /resume <name>   Resume a specific persona
+
+    /new
+        Toggle a context boundary — starts a fresh conversation thread
+        without deleting history.
+
+    /quotes, /quote
+        Manage quotes attached to messages.
+        /quotes <N>            View quotes from message N
+        /quotes me             View your own quotes
+        /quotes search "term"  Search quotes by keyword
+        /quotes <persona>      View a persona's quotes
+
+ROOM COMMANDS
+    /room, /r
+        Open room picker. Switch or create rooms.
+        /room new         Create a new room (FFA, CYP, or MAP mode)
+        /room new <name>  Create with a pre-filled name
+
+    /activate, /a
+        Advance the active node in a CYP or MAP room.
+        /activate <num>   Activate a specific response by number
+
+    /silence
+        Pass your turn in a room with an optional reason.
+        /silence [reason]
+
+    /capture
+        Force-extract quotes, topics, and people from the current chat now.
+
+EXTENDED COMMANDS
+    /tools
+        Manage tool providers — enable or disable tools per persona.
+
+    /auth
+        Authenticate with an external service.
+        /auth spotify   Connect your Spotify account
+
+    /queue
+        Pause the queue and inspect or edit active items in $EDITOR.
+
+    /dlq
+        Inspect and recover failed (dead-letter) queue items in $EDITOR.
+
+    /dedupe
+        Find and merge duplicate people or topics.
+        /dedupe person Flare "Jeremy Scherer"
+        /dedupe topic AI "artificial intelligence"
+
+    /archive
+        Archive a persona or room. Lists archived items if no name given.
+        /archive <name>   Archive by name
+
+    /unarchive
+        Restore an archived persona or room and switch to it.
+        /unarchive <name>
+
+    /delete, /del
+        Permanently delete a persona. Cannot be undone.
+        /delete <name>
+
+    /setsync, /ss
+        Set sync credentials (triggers restart).
+        /setsync <username> <passphrase>
+
+    /editor, /e, /edit
+        Open $EDITOR with the current input field contents.
+        Note: Ctrl+E does the same thing without clearing the input first.
+
+TIPS
+    - Append ! to any command as shorthand for --force: /quit!
+    - Duration strings: 30m, 2h, 1d, 1w (used by /pause, /settings)
+    - All editor fields that say "null" inherit from your global settings
+    - $EDITOR and $PAGER are respected throughout
+
+Ei - 永 (ei) - eternal
+`;
+}

package/tui/src/util/yaml-human.ts

@@ -51,6 +51,19 @@ function readOnlyToEnd<T extends WithReadOnlyFields>(item: T): T {
   return { ...rest, learned_on, learned_by, validated_date, last_mentioned, last_updated, last_changed_by } as T;
 }
 
+const FIELD_ORDER = ['id', 'name', 'description', 'sentiment', 'relationship', 'category', 'exposure_current', 'exposure_desired'];
+
+function canonicalFieldOrder<T extends object>(item: T): T {
+  const ordered: Record<string, unknown> = {};
+  for (const key of FIELD_ORDER) {
+    if (key in item) ordered[key] = (item as Record<string, unknown>)[key];
+  }
+  for (const [key, val] of Object.entries(item)) {
+    if (!(key in ordered)) ordered[key] = val;
+  }
+  return ordered as T;
+}
+
 function buildGroupCheckboxMap(itemGroups: string[], allGroups: string[]): Record<string, boolean>[] {
   const activeSet = new Set(itemGroups);
   return [...new Set([...allGroups, ...itemGroups])].map(g => ({ [g]: activeSet.has(g) }));
@@ -65,8 +78,10 @@ function toYAMLIdentifiers(identifiers: PersonIdentifier[], personaLookup?: Map<
   });
 }
 
-function knownTypesComment(personaLookup?: Map<string, string>): string {
-  const lines = [`# Valid types: ${BUILT_IN_IDENTIFIER_TYPES.join(', ')}`];
+function knownTypesComment(people: Person[], personaLookup?: Map<string, string>): string {
+  const userTypes = people.flatMap(p => (p.identifiers ?? []).map(i => i.type));
+  const allTypes = [...new Set([...BUILT_IN_IDENTIFIER_TYPES, ...userTypes])];
+  const lines = [`# Valid types: ${allTypes.join(', ')}`];
   if (personaLookup && personaLookup.size > 0) {
     lines.push(`# Personas: ${Array.from(personaLookup.values()).join(', ')}`);
   }
@@ -84,11 +99,68 @@ function parseGroupCheckboxMap(groups: Record<string, boolean>[] | undefined): s
   return result;
 }
 
-export function humanToYAML(human: HumanEntity, personaLookup?: Map<string, string>, allGroups: string[] = []): string {
-  const data: EditableHumanData = {
-    facts: human.facts.map(f => { const { interested_personas: _ip, persona_groups, ...rest } = readOnlyToEnd(f); return { ...rest, persona_groups: buildGroupCheckboxMap(persona_groups ?? [], allGroups), _delete: false }; }),
-    topics: human.topics.map(t => { const { interested_personas: _ip, persona_groups, ...rest } = readOnlyToEnd(t); return { ...rest, persona_groups: buildGroupCheckboxMap(persona_groups ?? [], allGroups), _delete: false }; }),
-    people: human.people.map(p => {
+function sectionStub(type: "facts" | "topics" | "people", people: Person[], personaLookup?: Map<string, string>): string {
+  if (type === "facts") {
+    return [
+      `  # --- New Fact (uncomment to create) ---`,
+      `  # - name: ''`,
+      `  #   description: ''`,
+      `  #   sentiment: 0`,
+    ].join('\n');
+  }
+
+  if (type === "topics") {
+    return [
+      `  # --- New Topic (uncomment to create) ---`,
+      `  # - name: ''`,
+      `  #   description: ''`,
+      `  #   category: ''  # Interest, Goal, Dream, Conflict, Concern, Fear, Hope, Plan, Project`,
+      `  #   exposure_desired: 0.5`,
+      `  #   sentiment: 0`,
+    ].join('\n');
+  }
+
+  const userTypes = people.flatMap(p => (p.identifiers ?? []).map(i => i.type));
+  const allTypes = [...new Set([...BUILT_IN_IDENTIFIER_TYPES, ...userTypes])];
+  const identifierTypeHint = allTypes.join(', ');
+  const personaNames = personaLookup && personaLookup.size > 0
+    ? Array.from(personaLookup.values()).join(', ')
+    : null;
+
+  return [
+    `  # --- New Person (uncomment to create) ---`,
+    `  # - name: ''`,
+    `  #   description: ''`,
+    `  #   relationship: ''`,
+    `  #   exposure_desired: 0.5`,
+    `  #   sentiment: 0`,
+    `  #   identifiers:`,
+    `  #     # Valid types: ${identifierTypeHint}`,
+    ...(personaNames ? [`  #     # Personas: ${personaNames}`] : []),
+    `  #     - type: ''`,
+    `  #       value: ''`,
+    `  #       primary: true`,
+  ].join('\n');
+}
+
+export function humanToYAML(
+  human: HumanEntity,
+  personaLookup?: Map<string, string>,
+  allGroups: string[] = [],
+  sections?: Set<"facts" | "topics" | "people">,
+): string {
+  const activeSections = sections ?? new Set<"facts" | "topics" | "people">(["facts", "topics", "people"]);
+
+  const data: Partial<EditableHumanData> = {};
+
+  if (activeSections.has("facts") && human.facts.length > 0) {
+    data.facts = human.facts.map(f => { const { interested_personas: _ip, persona_groups, ...rest } = readOnlyToEnd(f); return { ...rest, persona_groups: buildGroupCheckboxMap(persona_groups ?? [], allGroups), _delete: false }; });
+  }
+  if (activeSections.has("topics") && human.topics.length > 0) {
+    data.topics = human.topics.map(t => { const { interested_personas: _ip, persona_groups, ...rest } = readOnlyToEnd(t); return { ...rest, persona_groups: buildGroupCheckboxMap(persona_groups ?? [], allGroups), _delete: false }; });
+  }
+  if (activeSections.has("people") && human.people.length > 0) {
+    data.people = human.people.map(p => {
       const { identifiers, interested_personas: _ip, persona_groups, ...rest } = readOnlyToEnd(p);
       return {
         ...rest,
@@ -96,31 +168,51 @@ export function humanToYAML(human: HumanEntity, personaLookup?: Map<string, stri
         identifiers: toYAMLIdentifiers(identifiers ?? [], personaLookup),
         _delete: false as const,
       };
-    }),
+    });
+  }
+
+  const personComment = knownTypesComment(human.people, personaLookup);
+
+  const applyReadOnlyMarkers = (yaml: string): string =>
+    yaml
+      .replace(/^(\s+)(learned_on: .+)$/mg, '$1# [read-only] $2')
+      .replace(/^(\s+)(learned_by: )(.+)$/mg, (_, indent, key, val) => {
+        const trimmed = val.trim();
+        const displayName = personaLookup?.get(trimmed) ?? trimmed;
+        return `${indent}# [read-only] ${key}${displayName}`;
+      })
+      .replace(/^(\s+)(validated_date: .+)$/mg, '$1# [read-only] $2')
+      .replace(/^(\s+)(last_mentioned: .+)$/mg, '$1# [read-only] $2')
+      .replace(/^(\s+)(last_updated: .+)$/mg, '$1# [read-only] $2')
+      .replace(/^(\s+)(last_changed_by: )(.+)$/mg, (_, indent, key, val) => {
+        const trimmed = val.trim();
+        const displayName = personaLookup?.get(trimmed) ?? trimmed;
+        return `${indent}# [read-only] ${key}${displayName}`;
+      })
+      .replace(/^(\s+)(identifiers:)/mg, (_, indent, _key) => {
+        return `${indent}${personComment}\n${indent}identifiers:`;
+      });
+
+  const serializeSection = (key: "facts" | "topics" | "people", items: unknown[] | undefined): string => {
+    const stub = sectionStub(key, human.people, personaLookup);
+    if (!items || items.length === 0) {
+      return `${key}:\n${stub}`;
+    }
+    const ordered = (items as object[]).map(canonicalFieldOrder);
+    const itemsYaml = YAML.stringify(ordered, { lineWidth: 0 })
+      .split('\n')
+      .map(line => `  ${line}`)
+      .join('\n')
+      .trimEnd();
+    return `${key}:\n${applyReadOnlyMarkers(itemsYaml)}\n${stub}`;
   };
 
-  const personComment = knownTypesComment(personaLookup);
-
-  return YAML.stringify(data, {
-    lineWidth: 0,
-  })
-  .replace(/^(\s+)(learned_on: .+)$/mg, '$1# [read-only] $2')
-  .replace(/^(\s+)(learned_by: )(.+)$/mg, (_, indent, key, val) => {
-    const trimmed = val.trim();
-    const displayName = personaLookup?.get(trimmed) ?? trimmed;
-    return `${indent}# [read-only] ${key}${displayName}`;
-  })
-  .replace(/^(\s+)(validated_date: .+)$/mg, '$1# [read-only] $2')
-  .replace(/^(\s+)(last_mentioned: .+)$/mg, '$1# [read-only] $2')
-  .replace(/^(\s+)(last_updated: .+)$/mg, '$1# [read-only] $2')
-  .replace(/^(\s+)(last_changed_by: )(.+)$/mg, (_, indent, key, val) => {
-    const trimmed = val.trim();
-    const displayName = personaLookup?.get(trimmed) ?? trimmed;
-    return `${indent}# [read-only] ${key}${displayName}`;
-  })
-  .replace(/^(\s+)(identifiers:)/mg, (_, indent, _key) => {
-    return `${indent}${personComment}\n${indent}identifiers:`;
-  });
+  const parts: string[] = [];
+  if (activeSections.has("facts")) parts.push(serializeSection("facts", data.facts));
+  if (activeSections.has("topics")) parts.push(serializeSection("topics", data.topics));
+  if (activeSections.has("people")) parts.push(serializeSection("people", data.people));
+
+  return parts.join('\n') + '\n';
 }
 
 export interface HumanYAMLResult {
@@ -192,7 +284,7 @@ export function humanFromYAML(yamlContent: string, original?: HumanEntity): Huma
     .split('\n')
     .filter(line => !/^\s*#\s*\[read-only\]/.test(line))
     .join('\n');
-  const data = YAML.parse(stripped) as EditableHumanData;
+  const data = (YAML.parse(stripped) ?? {}) as EditableHumanData;
 
   const deletedFactIds: string[] = [];
   const deletedTopicIds: string[] = [];
@@ -207,10 +299,11 @@ export function humanFromYAML(yamlContent: string, original?: HumanEntity): Huma
       deletedFactIds.push(f.id);
     } else {
       const { _delete, persona_groups: groupMap, ...parsed } = f;
+      if (!parsed.id) parsed.id = crypto.randomUUID();
       const originalFact = original?.facts.find(of => of.id === parsed.id);
       const fact: Fact = originalFact
         ? { ...originalFact, ...parsed, persona_groups: parseGroupCheckboxMap(groupMap) }
-        : { ...parsed, persona_groups: parseGroupCheckboxMap(groupMap) };
+        : { ...parsed, last_updated: new Date().toISOString(), persona_groups: parseGroupCheckboxMap(groupMap) };
       facts.push(fact);
       if (!originalFact || factChanged(fact, originalFact)) {
         if (fact.description && !originalFact?.validated_date) {
@@ -227,10 +320,11 @@ export function humanFromYAML(yamlContent: string, original?: HumanEntity): Huma
       deletedTopicIds.push(t.id);
     } else {
       const { _delete, persona_groups: groupMap, ...parsed } = t;
+      if (!parsed.id) parsed.id = crypto.randomUUID();
       const originalTopic = original?.topics.find(ot => ot.id === parsed.id);
       const topic: Topic = originalTopic
         ? { ...originalTopic, ...parsed, persona_groups: parseGroupCheckboxMap(groupMap) }
-        : { ...parsed, persona_groups: parseGroupCheckboxMap(groupMap) };
+        : { ...parsed, last_updated: new Date().toISOString(), persona_groups: parseGroupCheckboxMap(groupMap) };
       topics.push(topic);
       if (!originalTopic || topicChanged(topic, originalTopic)) {
         changedTopicIds.add(topic.id);
@@ -244,6 +338,7 @@ export function humanFromYAML(yamlContent: string, original?: HumanEntity): Huma
       deletedPersonIds.push(p.id);
     } else {
       const { _delete, identifiers: yamlIdentifiers, persona_groups: groupMap, ...parsed } = p;
+      if (!parsed.id) parsed.id = crypto.randomUUID();
       const identifiers: PersonIdentifier[] = (yamlIdentifiers ?? []).map(({ type, value, primary }) => ({
         type,
         value,
@@ -252,7 +347,7 @@ export function humanFromYAML(yamlContent: string, original?: HumanEntity): Huma
       const originalPerson = original?.people.find(op => op.id === parsed.id);
       const person: Person = originalPerson
         ? { ...originalPerson, ...parsed, identifiers, persona_groups: parseGroupCheckboxMap(groupMap) }
-        : { ...parsed, identifiers, persona_groups: parseGroupCheckboxMap(groupMap) };
+        : { ...parsed, last_updated: new Date().toISOString(), identifiers, persona_groups: parseGroupCheckboxMap(groupMap) };
       people.push(person);
       if (!originalPerson || personChanged(person, originalPerson)) {
         changedPersonIds.add(person.id);

package/tui/src/util/yaml-persona.ts

@@ -7,6 +7,7 @@ import type {
   ProviderAccount,
 } from "../../../src/core/types.js";
 import { modelGuidToDisplay, displayToModelGuid } from "./yaml-shared.js";
+import { parseDuration, formatDuration } from "./duration.js";
 
 const PLACEHOLDER_LONG_DESC = "Detailed description of this persona's personality, background, and role";
 
@@ -36,8 +37,8 @@ interface EditablePersonaData {
   groups_visible?: Record<string, boolean>[];
   traits: YAMLTrait[];
   topics: YAMLPersonaTopic[];
-  heartbeat_delay_ms?: string | number;
-  context_window_hours?: number;
+  heartbeat_delay_ms?: string | null;
+  context_window_hours?: number | null;
   is_paused?: boolean;
   pause_until?: string;
   is_static?: boolean;
@@ -175,10 +176,10 @@ export function newPersonaFromYAML(yamlContent: string, allTools?: ToolDefinitio
     groups_visible: groupsVisible.length > 0 ? groupsVisible : ["General"],
     traits,
     topics,
-    heartbeat_delay_ms: data.heartbeat_delay_ms === 'default' || data.heartbeat_delay_ms === undefined
+    heartbeat_delay_ms: data.heartbeat_delay_ms == null
       ? undefined
-      : Number(data.heartbeat_delay_ms) || undefined,
-    context_window_hours: data.context_window_hours,
+      : parseDuration(data.heartbeat_delay_ms) ?? undefined,
+    context_window_hours: data.context_window_hours ?? undefined,
     tools: resolvePersonaToolsFromMap(data.tools, allTools ?? [], allProviders ?? []),
   };
 }
@@ -216,8 +217,8 @@ export function personaToYAML(persona: PersonaEntity, allGroups?: string[], allT
       : persona.topics.map(({ name, perspective, approach, personal_stake, exposure_current, exposure_desired }) => ({
           name, perspective, approach, personal_stake, exposure_current, exposure_desired
         })),
-    heartbeat_delay_ms: persona.heartbeat_delay_ms || 'default',
-    context_window_hours: persona.context_window_hours,
+    heartbeat_delay_ms: persona.heartbeat_delay_ms ? formatDuration(persona.heartbeat_delay_ms) : null,
+    context_window_hours: persona.context_window_hours ?? null,
     is_paused: persona.is_paused || undefined,
     pause_until: persona.pause_until,
     is_static: persona.is_static || undefined,
@@ -324,10 +325,10 @@ export function personaFromYAML(yamlContent: string, original: PersonaEntity, al
     groups_visible: groupsVisible,
     traits,
     topics,
-    heartbeat_delay_ms: data.heartbeat_delay_ms === 'default' || data.heartbeat_delay_ms === undefined
+    heartbeat_delay_ms: data.heartbeat_delay_ms == null
       ? undefined
-      : Number(data.heartbeat_delay_ms) || undefined,
-    context_window_hours: data.context_window_hours,
+      : parseDuration(data.heartbeat_delay_ms) ?? undefined,
+    context_window_hours: data.context_window_hours ?? undefined,
     is_paused: data.is_paused ?? false,
     pause_until: data.pause_until,
     is_static: data.is_static ?? false,

package/tui/src/util/yaml-settings.ts

@@ -8,6 +8,7 @@ import type {
 import type { ClaudeCodeSettings } from "../../../src/integrations/claude-code/types.js";
 import type { CursorSettings } from "../../../src/integrations/cursor/types.js";
 import { modelGuidToDisplay, displayToModelGuid } from "./yaml-shared.js";
+import { parseDuration, formatDuration } from "./duration.js";
 
 interface EditableSettingsData {
   default_model?: string | null;
@@ -15,7 +16,7 @@ interface EditableSettingsData {
   rewrite_model?: string | null;
   time_mode?: "24h" | "12h" | "local" | "utc" | null;
   name_display?: string | null;
-  default_heartbeat_ms?: number | null;
+  default_heartbeat_ms?: string | null;
   default_context_window_hours?: number | null;
   message_min_count?: number | null;
   message_max_age_days?: number | null;
@@ -28,28 +29,28 @@ interface EditableSettingsData {
   };
   opencode?: {
     integration?: boolean | null;
-    polling_interval_ms?: number | null;
+    polling_interval_ms?: string | null;
     last_sync?: string | null;
     extraction_point?: string | null;
     extraction_model?: string | null;
   };
   claudeCode?: {
     integration?: boolean | null;
-    polling_interval_ms?: number | null;
+    polling_interval_ms?: string | null;
     last_sync?: string | null;
     extraction_point?: string | null;
     extraction_model?: string | null;
   };
   cursor?: {
     integration?: boolean | null;
-    polling_interval_ms?: number | null;
+    polling_interval_ms?: string | null;
     last_sync?: string | null;
     extraction_point?: string | null;
   };
   backup?: {
     enabled?: boolean | null;
     max_backups?: number | null;
-    interval_ms?: number | null;
+    interval_ms?: string | null;
   };
 }
 
@@ -65,7 +66,7 @@ export function settingsToYAML(settings: HumanSettings | undefined, accounts: Pr
     rewrite_model: guidToDisplay(settings?.rewrite_model),
     time_mode: settings?.time_mode ?? null,
     name_display: settings?.name_display ?? null,
-    default_heartbeat_ms: settings?.default_heartbeat_ms ?? 1800000,
+    default_heartbeat_ms: formatDuration(settings?.default_heartbeat_ms ?? 1800000),
     default_context_window_hours: settings?.default_context_window_hours ?? 8,
     message_min_count: settings?.message_min_count ?? 200,
     message_max_age_days: settings?.message_max_age_days ?? 14,
@@ -78,28 +79,28 @@ export function settingsToYAML(settings: HumanSettings | undefined, accounts: Pr
     },
     opencode: {
       integration: settings?.opencode?.integration ?? false,
-      polling_interval_ms: settings?.opencode?.polling_interval_ms ?? 60000,
+      polling_interval_ms: formatDuration(settings?.opencode?.polling_interval_ms ?? 60000),
       extraction_model: guidToDisplay(settings?.opencode?.extraction_model) ?? 'default',
       last_sync: settings?.opencode?.last_sync ?? null,
       extraction_point: settings?.opencode?.extraction_point ?? null,
     },
     claudeCode: {
       integration: settings?.claudeCode?.integration ?? false,
-      polling_interval_ms: settings?.claudeCode?.polling_interval_ms ?? 60000,
+      polling_interval_ms: formatDuration(settings?.claudeCode?.polling_interval_ms ?? 60000),
       extraction_model: guidToDisplay(settings?.claudeCode?.extraction_model) ?? 'default',
       last_sync: settings?.claudeCode?.last_sync ?? null,
       extraction_point: settings?.claudeCode?.extraction_point ?? null,
     },
     cursor: {
       integration: settings?.cursor?.integration ?? false,
-      polling_interval_ms: settings?.cursor?.polling_interval_ms ?? 60000,
+      polling_interval_ms: formatDuration(settings?.cursor?.polling_interval_ms ?? 60000),
       last_sync: settings?.cursor?.last_sync ?? null,
       extraction_point: settings?.cursor?.extraction_point ?? null,
     },
     backup: {
       enabled: settings?.backup?.enabled ?? false,
       max_backups: settings?.backup?.max_backups ?? 24,
-      interval_ms: settings?.backup?.interval_ms ?? 3600000,
+      interval_ms: formatDuration(settings?.backup?.interval_ms ?? 3600000),
     },
   };
 
@@ -117,6 +118,11 @@ export function settingsFromYAML(yamlContent: string, original: HumanSettings |
   const nullToUndefined = <T>(value: T | null | undefined): T | undefined =>
     value === null ? undefined : value;
 
+  const parseMsDuration = (value: string | null | undefined, fallback: number): number | undefined => {
+    if (value == null) return undefined;
+    return parseDuration(value) ?? fallback;
+  };
+
   const displayToGuid = (display: string | null | undefined): string | undefined => {
     if (!display || display === 'default') return undefined;
     return displayToModelGuid(display, accounts) ?? display;
@@ -138,7 +144,7 @@ export function settingsFromYAML(yamlContent: string, original: HumanSettings |
   if (data.opencode) {
     opencode = {
       integration: nullToUndefined(data.opencode.integration),
-      polling_interval_ms: nullToUndefined(data.opencode.polling_interval_ms),
+      polling_interval_ms: parseMsDuration(data.opencode.polling_interval_ms, 60000),
       last_sync: original?.opencode?.last_sync,
       extraction_point: original?.opencode?.extraction_point,
       processed_sessions: original?.opencode?.processed_sessions,
@@ -150,7 +156,7 @@ export function settingsFromYAML(yamlContent: string, original: HumanSettings |
   if (data.claudeCode) {
     claudeCode = {
       integration: nullToUndefined(data.claudeCode.integration),
-      polling_interval_ms: nullToUndefined(data.claudeCode.polling_interval_ms),
+      polling_interval_ms: parseMsDuration(data.claudeCode.polling_interval_ms, 60000),
       last_sync: original?.claudeCode?.last_sync,
       extraction_point: original?.claudeCode?.extraction_point,
       processed_sessions: original?.claudeCode?.processed_sessions,
@@ -162,7 +168,7 @@ export function settingsFromYAML(yamlContent: string, original: HumanSettings |
   if (data.cursor) {
     cursor = {
       integration: nullToUndefined(data.cursor.integration),
-      polling_interval_ms: nullToUndefined(data.cursor.polling_interval_ms),
+      polling_interval_ms: parseMsDuration(data.cursor.polling_interval_ms, 60000),
       last_sync: original?.cursor?.last_sync,
       extraction_point: original?.cursor?.extraction_point,
       processed_sessions: original?.cursor?.processed_sessions,
@@ -174,7 +180,7 @@ export function settingsFromYAML(yamlContent: string, original: HumanSettings |
     backup = {
       enabled: nullToUndefined(data.backup.enabled),
       max_backups: nullToUndefined(data.backup.max_backups),
-      interval_ms: nullToUndefined(data.backup.interval_ms),
+      interval_ms: parseMsDuration(data.backup.interval_ms, 3600000),
       last_backup: original?.backup?.last_backup,
     };
   }
@@ -186,7 +192,7 @@ export function settingsFromYAML(yamlContent: string, original: HumanSettings |
     rewrite_model: displayToGuid(data.rewrite_model),
     time_mode: nullToUndefined(data.time_mode),
     name_display: nullToUndefined(data.name_display),
-    default_heartbeat_ms: nullToUndefined(data.default_heartbeat_ms),
+    default_heartbeat_ms: parseMsDuration(data.default_heartbeat_ms, 1800000),
     default_context_window_hours: nullToUndefined(data.default_context_window_hours),
     message_min_count: nullToUndefined(data.message_min_count),
     message_max_age_days: nullToUndefined(data.message_max_age_days),