zam-core 0.7.1 → 0.7.2

package/dist/cli/index.js

@@ -4,7 +4,7 @@
 import { readFileSync as readFileSync16 } from "fs";
 import { dirname as dirname10, join as join25 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
-import { Command as Command25 } from "commander";
+import { Command as Command26 } from "commander";
 
 // src/cli/commands/agent.ts
 import { existsSync as existsSync13 } from "fs";
@@ -543,6 +543,7 @@ var SCHEMA = `
 CREATE TABLE IF NOT EXISTS tokens (
   id            TEXT PRIMARY KEY,
   slug          TEXT UNIQUE NOT NULL,
+  title         TEXT NOT NULL DEFAULT '',
   concept       TEXT NOT NULL,
   domain        TEXT NOT NULL DEFAULT '',
   bloom_level   INTEGER NOT NULL DEFAULT 1 CHECK (bloom_level BETWEEN 1 AND 5),
@@ -691,6 +692,8 @@ CREATE INDEX IF NOT EXISTS idx_cards_token_user ON cards(token_id, user_id);
 CREATE INDEX IF NOT EXISTS idx_review_logs_card ON review_logs(card_id);
 CREATE INDEX IF NOT EXISTS idx_review_logs_user ON review_logs(user_id, reviewed_at);
 CREATE INDEX IF NOT EXISTS idx_session_steps_session ON session_steps(session_id);
+CREATE INDEX IF NOT EXISTS idx_tokens_title ON tokens(title);
+CREATE INDEX IF NOT EXISTS idx_tokens_domain ON tokens(domain);
 `;
 
 // src/kernel/db/sync-adapter.ts
@@ -1024,6 +1027,15 @@ async function runMigrations(db) {
       embedded_at  TEXT NOT NULL DEFAULT (datetime('now'))
     )
   `);
+  if (!tokenCols.some((c) => c.name === "title")) {
+    await db.exec(
+      `ALTER TABLE tokens ADD COLUMN title TEXT NOT NULL DEFAULT ''`
+    );
+  }
+  await db.exec(`CREATE INDEX IF NOT EXISTS idx_tokens_title ON tokens(title)`);
+  await db.exec(
+    `CREATE INDEX IF NOT EXISTS idx_tokens_domain ON tokens(domain)`
+  );
 }
 
 // src/kernel/db/snapshot.ts
@@ -1516,12 +1528,14 @@ async function createToken(db, input8) {
   if (bloom < 1 || bloom > 5) {
     throw new Error(`bloom_level must be between 1 and 5, got ${bloom}`);
   }
+  const title = input8.title ?? "";
   await db.prepare(`
-    INSERT INTO tokens (id, slug, concept, domain, bloom_level, context, symbiosis_mode, source_link, question, provider, topic_id, created_at, updated_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO tokens (id, slug, title, concept, domain, bloom_level, context, symbiosis_mode, source_link, question, provider, topic_id, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     id,
     input8.slug,
+    title,
     input8.concept,
     input8.domain ?? "",
     bloom,
@@ -1564,6 +1578,10 @@ async function updateToken(db, slug, updates) {
   }
   const fields = [];
   const values = [];
+  if (updates.title !== void 0) {
+    fields.push("title = ?");
+    values.push(updates.title ?? "");
+  }
   if (updates.concept !== void 0) {
     fields.push("concept = ?");
     values.push(updates.concept);
@@ -1669,13 +1687,14 @@ async function deleteToken(db, slug) {
   await db.transaction(async (tx) => {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const skillRows = await tx.prepare("SELECT id, token_slugs FROM agent_skills").all();
+    const skillUpdateStmt = tx.prepare(
+      "UPDATE agent_skills SET token_slugs = ?, updated_at = ? WHERE id = ?"
+    );
     for (const row of skillRows) {
       const tokenSlugs = JSON.parse(row.token_slugs);
       const filtered = tokenSlugs.filter((tokenSlug) => tokenSlug !== slug);
       if (filtered.length !== tokenSlugs.length) {
-        await tx.prepare(
-          "UPDATE agent_skills SET token_slugs = ?, updated_at = ? WHERE id = ?"
-        ).run(JSON.stringify(filtered), now, row.id);
+        await skillUpdateStmt.run(JSON.stringify(filtered), now, row.id);
       }
     }
     await tx.prepare("DELETE FROM tokens WHERE id = ?").run(token.id);
@@ -1689,10 +1708,16 @@ async function findTokens(db, query) {
   const shortTerms = searchTokens.filter((t2) => t2.length <= 2);
   const longTerms = searchTokens.filter((t2) => t2.length > 2);
   const scoreMap = /* @__PURE__ */ new Map();
-  const likeSQL = `SELECT * FROM tokens WHERE deprecated_at IS NULL AND (lower(slug) LIKE ? OR lower(concept) LIKE ? OR lower(domain) LIKE ?)`;
+  const likeSQL = `SELECT * FROM tokens WHERE deprecated_at IS NULL AND (lower(slug) LIKE ? OR lower(title) LIKE ? OR lower(concept) LIKE ? OR lower(domain) LIKE ?)`;
+  const likeStmt = db.prepare(likeSQL);
   for (const term of longTerms) {
     const pattern = `%${term}%`;
-    const rows = await db.prepare(likeSQL).all(pattern, pattern, pattern);
+    const rows = await likeStmt.all(
+      pattern,
+      pattern,
+      pattern,
+      pattern
+    );
     for (const row of rows) {
       const entry = scoreMap.get(row.id);
       if (entry) {
@@ -1705,7 +1730,7 @@ async function findTokens(db, query) {
   if (shortTerms.length > 0 || longTerms.length === 0) {
     const allTokens = await db.prepare("SELECT * FROM tokens WHERE deprecated_at IS NULL").all();
     for (const token of allTokens) {
-      const words = `${token.slug} ${token.concept} ${token.domain}`.toLowerCase().split(/[\s,.\-_/\\:;!?()[\]{}]+/).filter(Boolean);
+      const words = `${token.slug} ${token.title} ${token.concept} ${token.domain}`.toLowerCase().split(/[\s,.\-_/\\:;!?()[\]{}]+/).filter(Boolean);
       let matchCount = 0;
       for (const term of shortTerms.length > 0 ? shortTerms : searchTokens) {
         for (const w of words) {
@@ -1739,6 +1764,11 @@ async function listTokens(db, options) {
     tokens = await db.prepare(
       "SELECT * FROM tokens WHERE domain = ? AND deprecated_at IS NULL ORDER BY bloom_level, slug"
     ).all(options.domain);
+  } else if (options?.domainPrefix) {
+    const prefix = options.domainPrefix;
+    tokens = await db.prepare(
+      `SELECT * FROM tokens WHERE (domain = ? OR domain LIKE ?) AND deprecated_at IS NULL ORDER BY bloom_level, slug`
+    ).all(prefix, `${prefix}/%`);
   } else {
     tokens = await db.prepare(
       "SELECT * FROM tokens WHERE deprecated_at IS NULL ORDER BY bloom_level, domain, slug"
@@ -1750,7 +1780,20 @@ async function listTokens(db, options) {
   return tokens;
 }
 function slugify(text) {
-  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+  return text.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+function getShortSlug(slug, domainPrefix) {
+  if (domainPrefix) {
+    const folded = domainPrefix.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    if (folded && slug.startsWith(`${folded}-`)) {
+      return slug.substring(folded.length + 1);
+    }
+  }
+  return slug;
+}
+function getDisplayTitle(t2, activeDomainScope) {
+  if (t2.title?.trim()) return t2.title.trim();
+  return getShortSlug(t2.slug, activeDomainScope);
 }
 async function generateTokenSlug(db, domain, concept, question) {
   const baseText = question && question.trim().length > 0 ? question : concept;
@@ -1780,6 +1823,7 @@ async function listPersonalCards(db, userId, options) {
     SELECT 
       t.id AS tokenId,
       t.slug,
+      t.title,
       t.concept,
       t.domain,
       t.bloom_level AS bloomLevel,
@@ -1881,6 +1925,7 @@ async function importCurriculumCards(db, userId, cards) {
         );
         token = await createToken(tx, {
           slug: finalSlug,
+          title: card.title,
           concept: card.concept,
           domain: card.domain,
           bloom_level: bloom,
@@ -1998,23 +2043,28 @@ async function confirmCardSplit(db, userId, originalSlug, action, originalQuesti
         (/* @__PURE__ */ new Date()).toISOString(),
         originalToken.id
       );
+      const insertPrereqStmt = tx.prepare(
+        "INSERT OR IGNORE INTO prerequisites (token_id, requires_id) VALUES (?, ?)"
+      );
       for (const propToken of proposalTokens) {
-        await tx.prepare(
-          "INSERT OR IGNORE INTO prerequisites (token_id, requires_id) VALUES (?, ?)"
-        ).run(originalToken.id, propToken.id);
+        await insertPrereqStmt.run(originalToken.id, propToken.id);
       }
       await tx.prepare(
         "UPDATE cards SET blocked = 1 WHERE token_id = ? AND user_id = ?"
       ).run(originalToken.id, userId);
+      const checkPrereqsStmt = tx.prepare(
+        "SELECT COUNT(*) as n FROM prerequisites WHERE token_id = ?"
+      );
+      const unblockCardStmt = tx.prepare(
+        "UPDATE cards SET blocked = 0, due_at = ? WHERE id = ?"
+      );
       for (const propToken of proposalTokens) {
         const card = await ensureCard(tx, propToken.id, userId);
         if (card.blocked === 1) {
-          const prereqOfPrereq = await tx.prepare(
-            "SELECT COUNT(*) as n FROM prerequisites WHERE token_id = ?"
-          ).get(propToken.id);
+          const prereqOfPrereq = await checkPrereqsStmt.get(propToken.id);
           if (prereqOfPrereq.n === 0) {
             const now = (/* @__PURE__ */ new Date()).toISOString();
-            await tx.prepare("UPDATE cards SET blocked = 0, due_at = ? WHERE id = ?").run(now, card.id);
+            await unblockCardStmt.run(now, card.id);
           }
         }
       }
@@ -2085,6 +2135,7 @@ async function confirmFoundations(db, userId, originalSlug, proposals) {
           );
           token = await createToken(tx, {
             slug: finalSlug,
+            title: card.title,
             concept: card.concept,
             domain: card.domain,
             bloom_level: bloom,
@@ -2151,6 +2202,7 @@ async function confirmSourceImport(db, userId, sourceId, proposals) {
         }
         token = await createToken(tx, {
           slug: finalSlug,
+          title: card.title,
           concept: card.concept,
           domain: card.domain,
           bloom_level: bloom,
@@ -2253,7 +2305,7 @@ async function addPrerequisite(db, tokenId, requiresId) {
 }
 async function getPrerequisites(db, tokenId) {
   return await db.prepare(
-    `SELECT p.token_id, p.requires_id, t.slug, t.concept, t.domain, t.bloom_level
+    `SELECT p.token_id, p.requires_id, t.slug, t.title, t.concept, t.domain, t.bloom_level
        FROM prerequisites p
        JOIN tokens t ON t.id = p.requires_id
        WHERE p.token_id = ?`
@@ -2261,7 +2313,7 @@ async function getPrerequisites(db, tokenId) {
 }
 async function getDependents(db, tokenId) {
   return await db.prepare(
-    `SELECT p.token_id, p.requires_id, t.slug, t.concept, t.domain, t.bloom_level
+    `SELECT p.token_id, p.requires_id, t.slug, t.title, t.concept, t.domain, t.bloom_level
        FROM prerequisites p
        JOIN tokens t ON t.id = p.token_id
        WHERE p.requires_id = ?`
@@ -2292,6 +2344,7 @@ async function getTokenNeighborhood(db, tokenId, userId) {
   const toNode = (t2, card) => ({
     id: t2.id,
     slug: t2.slug,
+    title: t2.title ?? t2.slug,
     concept: t2.concept,
     domain: t2.domain,
     bloom_level: t2.bloom_level,
@@ -2311,6 +2364,7 @@ async function getTokenNeighborhood(db, tokenId, userId) {
       {
         id: p.requires_id,
         slug: p.slug,
+        title: p.title,
         concept: p.concept,
         domain: p.domain,
         bloom_level: p.bloom_level
@@ -2323,6 +2377,7 @@ async function getTokenNeighborhood(db, tokenId, userId) {
       {
         id: d.token_id,
         slug: d.slug,
+        title: d.title,
         concept: d.concept,
         domain: d.domain,
         bloom_level: d.bloom_level
@@ -2437,7 +2492,8 @@ import { createHash as createHash2 } from "crypto";
 function embeddingContentForToken(t2) {
   return `${t2.concept}
 ${t2.question ?? ""}
-${t2.domain}`;
+${t2.domain}
+${t2.title ?? ""}`;
 }
 function computeContentHash(text) {
   return createHash2("sha256").update(text, "utf8").digest("hex");
@@ -4601,6 +4657,7 @@ async function buildReviewQueue(db, options) {
          c.id       AS card_id,
          c.token_id AS token_id,
          t.slug     AS slug,
+         t.title    AS title,
          t.concept  AS concept,
          t.domain   AS domain,
          t.bloom_level AS bloom_level,
@@ -4622,6 +4679,7 @@ async function buildReviewQueue(db, options) {
          c.id       AS card_id,
          c.token_id AS token_id,
          t.slug     AS slug,
+         t.title    AS title,
          t.concept  AS concept,
          t.domain   AS domain,
          t.bloom_level AS bloom_level,
@@ -4681,6 +4739,7 @@ function rowToItem(row) {
     cardId: row.card_id,
     tokenId: row.token_id,
     slug: row.slug,
+    title: getDisplayTitle(row),
     concept: row.concept,
     domain: row.domain,
     bloomLevel: row.bloom_level,
@@ -6640,6 +6699,11 @@ function parseGeneratedCardArray(responseText, label, limits) {
         );
       }
     }
+    if (card.title !== void 0 && (typeof card.title !== "string" || card.title.trim().length === 0)) {
+      throw new Error(
+        `Invalid ${label} card at index ${index}: title must be a non-empty string if provided`
+      );
+    }
     if (typeof card.bloom_level !== "number" || !Number.isInteger(card.bloom_level) || card.bloom_level < 1 || card.bloom_level > 5) {
       throw new Error(
         `Invalid ${label} card at index ${index}: bloom_level must be an integer from 1 to 5`
@@ -6653,6 +6717,7 @@ function parseGeneratedCardArray(responseText, label, limits) {
     return {
       question: card.question,
       concept: card.concept,
+      title: card.title ? card.title : void 0,
       domain: card.domain,
       context: card.context,
       bloom_level: card.bloom_level,
@@ -6703,10 +6768,11 @@ Your task is to analyze curriculum objectives, syllabus requirements, or textboo
 For each extracted learning card, you MUST generate:
 1. "question": A clear, concise active-recall question testing the concept. The question must not reveal the answer itself.
 2. "concept": The reference answer, core fact, or target conceptual explanation.
-3. "domain": The category of the card. Use "${targetCategory}" as the default, but you may refine it if a specific sub-topic is evident.
-4. "context": The exact sentence or short excerpt from the source text that this card is based on.
-5. "bloom_level": Initial Bloom cognitive level (1 = Remember, 2 = Understand, 3 = Apply, 4 = Analyze, 5 = Synthesize).
-6. "symbiosis_mode": ZAM agent symbiosis level: "shadowing" (reading/monitoring), "copilot" (interactive helper), or "autonomy" (autonomous tasks).
+3. "title": A short, human-friendly title for the knowledge graph node. Concise name for the concept. No domain prefix. Human-readable, natural language. Support Unicode (umlauts, Chinese, Japanese, Arabic, etc.). Name the core idea as well as possible.
+4. "domain": The category of the card. Use "${targetCategory}" as the default, but you may refine it if a specific sub-topic is evident.
+5. "context": The exact sentence or short excerpt from the source text that this card is based on.
+6. "bloom_level": Initial Bloom cognitive level (1 = Remember, 2 = Understand, 3 = Apply, 4 = Analyze, 5 = Synthesize).
+7. "symbiosis_mode": ZAM agent symbiosis level: "shadowing" (reading/monitoring), "copilot" (interactive helper), or "autonomy" (autonomous tasks).
 
 Guidelines:
 - Break complex requirements into multiple separate, atomic cards.
@@ -7635,6 +7701,114 @@ async function ensureHighQualityQuestion(db, token) {
   }
   return null;
 }
+async function generateTitleViaLLM(db, input8, opts = {}) {
+  const cfg = await getProviderForRole(db, "text");
+  const endpoint = await resolveUsableTextEndpoint(db);
+  const systemPrompt = `You are an expert at naming knowledge items for a personal knowledge graph.
+Your task: given a knowledge token's concept (the full reference answer), question, domain, and optional context, produce a short, descriptive, human-friendly TITLE.
+
+Strict rules from the project ADR:
+- Concise name for the concept (\u2264 80 chars ideal).
+- Thoughtful, memorable name \u2014 NOT a definition or the first sentence of the concept.
+- NEVER echo the domain name (e.g. do not say "Node Drain" if domain is "axon-ivy"; just "Node Drain Protection").
+- Prefer a name over spoiling the full concept.
+- Support Unicode (umlauts, etc.).
+- Output the title in the same language as the concept/content (e.g., German if the concept is German, English if the concept is English).
+- Output ONLY the raw title text. No preamble, quotes, explanations, or markdown.
+
+Example good titles:
+- "RAG Retrieval Quality Evaluation" (for RAG failure modes focused on retrieval)
+- "Pythagorean Theorem Converse Proof"
+- "macOS Applications Directory Layout"
+- "Chronotype Sleep Preference"`;
+  const userPrompt = `Domain: ${input8.domain}
+Slug: ${input8.slug}
+Question: ${input8.question || "(none)"}
+Concept: ${input8.concept}
+Context: ${input8.context || "(none)"}
+
+Title:`;
+  const url = `${endpoint.url}/chat/completions`;
+  const apiKey = endpoint.apiKey;
+  const model = endpoint.model;
+  try {
+    const res = await fetchWithInteractiveTimeout(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt }
+        ],
+        temperature: 0.2,
+        max_tokens: 100
+      }),
+      locale: cfg.locale,
+      timeoutMs: opts.timeoutMs,
+      hardTimeoutMs: opts.timeoutMs
+    });
+    const text = await readChatContent(res, "title generation");
+    return {
+      text: text.trim(),
+      model,
+      providerName: endpoint.providerName
+    };
+  } catch (_e) {
+    return {
+      text: input8.concept.split(/[.;]/)[0].trim().substring(0, 80),
+      model: "fallback",
+      providerName: "heuristic"
+    };
+  }
+}
+async function repairUmlautsViaLLM(db, input8, opts = {}) {
+  const cfg = await getProviderForRole(db, "text");
+  const endpoint = await resolveUsableTextEndpoint(db);
+  const systemPrompt = `You are an expert editor specializing in German language orthography.
+Your task: given a text that may contain legacy ASCII-folded German umlauts (like 'ue' instead of '\xFC', 'ae' instead of '\xE4', 'oe' instead of '\xF6', 'Ue' instead of '\xDC', etc.), repair them back to proper German umlauts (\xE4, \xF6, \xFC, \xC4, \xD6, \xDC, \xDF) where appropriate.
+
+Strict rules:
+- ONLY change character sequences that are clearly meant to be German umlauts (e.g. change "Ueber" to "\xDCber", "fuer" to "f\xFCr", "moeglich" to "m\xF6glich").
+- DO NOT change words that are correct in their current form (e.g. do NOT change "nahe" to "n\xE4he", do NOT change English words or technical terms, do NOT change names like "Ueda").
+- Output ONLY the repaired text. No preamble, no explanation, no markdown formatting.`;
+  const userPrompt = `Text to repair:
+"""
+${input8.text}
+"""
+
+Repaired text:`;
+  const url = `${endpoint.url}/chat/completions`;
+  const apiKey = endpoint.apiKey;
+  const model = endpoint.model;
+  try {
+    const res = await fetchWithInteractiveTimeout(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: userPrompt }
+        ],
+        temperature: 0.1
+      }),
+      locale: cfg.locale,
+      timeoutMs: opts.timeoutMs,
+      hardTimeoutMs: opts.timeoutMs
+    });
+    const text = await readChatContent(res, "umlaut repair");
+    return text.trim();
+  } catch (_e) {
+    return input8.text;
+  }
+}
 
 // src/cli/adapters/source-reader.ts
 var MAX_SOURCE_BYTES = 2 * 1024 * 1024;
@@ -7946,7 +8120,7 @@ function cleanHtmlText(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/bildungsplan-bw/manifest.ts
@@ -8117,7 +8291,7 @@ function cleanHtmlText2(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison2(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/bildungsplan-hamburg/manifest.ts
@@ -8275,7 +8449,7 @@ function cleanHtmlText3(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison3(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/fachanforderungen-sh/manifest.ts
@@ -8432,7 +8606,7 @@ function cleanHtmlText4(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison4(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/kerncurriculum-hessen/manifest.ts
@@ -8626,7 +8800,7 @@ function cleanHtmlText5(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison5(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/kerncurriculum-niedersachsen/manifest.ts
@@ -8798,7 +8972,7 @@ function cleanHtmlText6(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison6(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/kernlehrplan-nrw/manifest.ts
@@ -9013,7 +9187,7 @@ function cleanHtmlText7(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison7(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/lehrplaene-rp/manifest.ts
@@ -9170,7 +9344,7 @@ function cleanHtmlText8(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison8(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/lehrplan-saarland/manifest.ts
@@ -9327,7 +9501,7 @@ function cleanHtmlText9(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison9(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/lehrplan-sachsen/manifest.ts
@@ -9512,7 +9686,7 @@ function cleanHtmlText10(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison10(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/lehrplan-thueringen/manifest.ts
@@ -9667,7 +9841,7 @@ function cleanHtmlText11(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison11(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/lehrplanplus-bayern/manifest.ts
@@ -9911,7 +10085,7 @@ function cleanHtmlText12(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison12(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/rahmenlehrplan-berlin-brandenburg/manifest.ts
@@ -10096,7 +10270,7 @@ function cleanHtmlText13(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison13(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/rahmenplan-mv/manifest.ts
@@ -10253,7 +10427,7 @@ function cleanHtmlText14(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison14(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/providers/rahmenrichtlinien-st/manifest.ts
@@ -10408,7 +10582,7 @@ function cleanHtmlText15(html) {
   return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join("\n");
 }
 function normalizeForComparison15(str) {
-  return str.toLowerCase().replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
+  return str.toLowerCase().replace(/ä/g, "ae").replace(/ö/g, "oe").replace(/ü/g, "ue").replace(/ß/g, "ss").replace(/&[a-z0-9#]+;/gi, "").replace(/[^a-z0-9]/gi, "");
 }
 
 // src/cli/curriculum/registry.ts
@@ -10606,7 +10780,8 @@ async function findPossibleDuplicates(db, candidate, embed = embedQuery) {
   const queryText = embeddingContentForToken({
     concept: candidate.concept,
     question: candidate.question ?? null,
-    domain: candidate.domain ?? ""
+    domain: candidate.domain ?? "",
+    title: candidate.title ?? null
   });
   const q2 = await embed(db, queryText);
   if (!q2) {
@@ -10637,6 +10812,7 @@ async function findPossibleDuplicates(db, candidate, embed = embedQuery) {
       results.push({
         slug: hit.slug,
         concept: hit.concept,
+        title: hit.title,
         similarity: hit.similarity
       });
     }
@@ -12400,10 +12576,12 @@ bridgeCommand.command("add-token").description("Create a token + card from JSON
     const possibleDuplicates = await findPossibleDuplicates(db, {
       concept: data?.concept,
       question: data?.question ?? null,
-      domain: data?.domain
+      domain: data?.domain,
+      title: data?.title ?? null
     });
     const token = await createToken(db, {
       slug: data?.slug,
+      title: data?.title,
       concept: data?.concept,
       domain: data?.domain,
       bloom_level: data?.bloom_level ?? 1,
@@ -12483,6 +12661,8 @@ bridgeCommand.command("relevant-tokens").description("Find tokens relevant to a
       const card = await getCard(db, t2.id, userId);
       tokens.push({
         slug: t2.slug,
+        title: t2.title,
+        display_title: getDisplayTitle(t2),
         concept: t2.concept,
         domain: t2.domain,
         bloom_level: t2.bloom_level,
@@ -12545,7 +12725,8 @@ bridgeCommand.command("suggest-foundations").description("Propose existing token
       queryText = embeddingContentForToken({
         concept: data.concept,
         question: typeof data.question === "string" ? data.question : null,
-        domain: typeof data.domain === "string" ? data.domain : ""
+        domain: typeof data.domain === "string" ? data.domain : "",
+        title: typeof data.title === "string" ? data.title : null
       });
       if (data.bloom_level !== void 0) {
         if (typeof data.bloom_level !== "number" || !Number.isInteger(data.bloom_level) || data.bloom_level < 1 || data.bloom_level > 5) {
@@ -13777,12 +13958,18 @@ bridgeCommand.command("list-tokens").description(
 ).option(
   "--user <id>",
   "User ID (default: whoami) \u2014 when provided, includes personal card info"
-).option("--domain <domain>", "Filter by domain").action(async (opts) => {
+).option("--domain <domain>", "Filter by exact domain").option(
+  "--domain-prefix <prefix>",
+  "Filter by domain prefix (e.g. docuware-cops) \u2014 uses / separator for hierarchy"
+).action(async (opts) => {
   await withDb2(async (db) => {
     const userId = opts.user ? await resolveUser(opts, db, { json: true }) : void 0;
+    const listOpts = {};
+    if (opts.domain) listOpts.domain = opts.domain;
+    if (opts.domainPrefix) listOpts.domainPrefix = opts.domainPrefix;
     const tokens = await listTokens(
       db,
-      opts.domain ? { domain: opts.domain } : void 0
+      Object.keys(listOpts).length ? listOpts : void 0
     );
     const cardMap = /* @__PURE__ */ new Map();
     if (userId && tokens.length > 0) {
@@ -13799,6 +13986,8 @@ bridgeCommand.command("list-tokens").description(
       return {
         id: t2.id,
         slug: t2.slug,
+        title: t2.title,
+        display_title: getDisplayTitle(t2),
         concept: t2.concept,
         domain: t2.domain,
         bloomLevel: t2.bloom_level,
@@ -13832,6 +14021,8 @@ bridgeCommand.command("get-neighborhood").description(
     const mapToken = (nt) => ({
       id: nt.id,
       slug: nt.slug,
+      title: nt.title,
+      display_title: getDisplayTitle(nt),
       concept: nt.concept,
       domain: nt.domain,
       bloomLevel: nt.bloom_level,
@@ -13863,7 +14054,7 @@ bridgeCommand.command("personal-card-list").description("List and search persona
     jsonOut2({ cards });
   });
 });
-bridgeCommand.command("personal-card-create").description("Atomically create a token and its personal card (JSON)").option("--user <id>", "User ID (default: whoami)").requiredOption("--concept <concept>", "Concept description / answer").option("--domain <domain>", "Knowledge category / domain", "").option("--question <question>", "Question prompt for recall").option("--source-link <link>", "Source file path or reference URL").option("--bloom <level>", "Bloom taxonomy level (1-5)", "1").option(
+bridgeCommand.command("personal-card-create").description("Atomically create a token and its personal card (JSON)").option("--user <id>", "User ID (default: whoami)").requiredOption("--concept <concept>", "Concept description / answer").option("--title <title>", "Human-friendly display title").option("--domain <domain>", "Knowledge category / domain", "").option("--question <question>", "Question prompt for recall").option("--source-link <link>", "Source file path or reference URL").option("--bloom <level>", "Bloom taxonomy level (1-5)", "1").option(
   "--mode <mode>",
   "Symbiosis mode: shadowing | copilot | autonomy | none",
   "none"
@@ -13891,6 +14082,7 @@ bridgeCommand.command("personal-card-create").description("Atomically create a t
     const { token, card } = await db.transaction(async (tx) => {
       const createdToken = await createToken(tx, {
         slug,
+        title: opts.title,
         concept: opts.concept,
         domain: opts.domain,
         bloom_level: bloom,
@@ -13907,6 +14099,8 @@ bridgeCommand.command("personal-card-create").description("Atomically create a t
       token: {
         id: token.id,
         slug: token.slug,
+        title: token.title,
+        display_title: getDisplayTitle(token),
         concept: token.concept,
         domain: token.domain,
         bloomLevel: token.bloom_level,
@@ -13928,13 +14122,14 @@ bridgeCommand.command("personal-card-create").description("Atomically create a t
     });
   });
 });
-bridgeCommand.command("personal-card-update").description("Update the mutable token fields of a personal card (JSON)").option("--user <id>", "User ID (default: whoami)").requiredOption("--slug <slug>", "Token slug to update").option("--concept <concept>", "Updated concept text").option("--domain <domain>", "Updated domain / category").option("--bloom <level>", "Updated Bloom taxonomy level (1-5)").option("--context <context>", "Updated context").option(
+bridgeCommand.command("personal-card-update").description("Update the mutable token fields of a personal card (JSON)").option("--user <id>", "User ID (default: whoami)").requiredOption("--slug <slug>", "Token slug to update").option("--title <title>", "Updated display title").option("--concept <concept>", "Updated concept text").option("--domain <domain>", "Updated domain / category").option("--bloom <level>", "Updated Bloom taxonomy level (1-5)").option("--context <context>", "Updated context").option(
   "--mode <mode>",
   "Updated symbiosis mode: shadowing | copilot | autonomy | none"
 ).option("--source-link <link>", "Updated source link").option("--question <question>", "Updated question text").action(async (opts) => {
   await withDb2(async (db) => {
     const userId = await resolveUser(opts, db, { json: true });
     const updates = {};
+    if (opts.title !== void 0) updates.title = opts.title;
     if (opts.concept !== void 0) updates.concept = opts.concept;
     if (opts.domain !== void 0) updates.domain = opts.domain;
     if (opts.bloom !== void 0) {
@@ -13976,6 +14171,8 @@ bridgeCommand.command("personal-card-update").description("Update the mutable to
       token: {
         id: token.id,
         slug: token.slug,
+        title: token.title,
+        display_title: getDisplayTitle(token),
         concept: token.concept,
         domain: token.domain,
         bloomLevel: token.bloom_level,
@@ -14008,7 +14205,12 @@ bridgeCommand.command("personal-card-remove").description(
         success: true,
         preview: true,
         requiresConfirmation: true,
-        token: { id: token.id, slug: token.slug },
+        token: {
+          id: token.id,
+          slug: token.slug,
+          title: token.title,
+          display_title: getDisplayTitle(token)
+        },
         impact
       });
       return;
@@ -14037,7 +14239,12 @@ bridgeCommand.command("personal-card-delete").description("Hard-delete a token a
         success: true,
         preview: true,
         requiresConfirmation: true,
-        token: { id: token.id, slug: token.slug },
+        token: {
+          id: token.id,
+          slug: token.slug,
+          title: token.title,
+          display_title: getDisplayTitle(token)
+        },
         impact
       });
       return;
@@ -14929,11 +15136,567 @@ async function setupTurso(urlArg, tokenArg, mode) {
   }
 }
 
+// src/cli/commands/doctor.ts
+import { Command as Command5 } from "commander";
+function shouldApplyFixes(opts) {
+  return opts.fix === true && opts.dryRun !== true;
+}
+async function confirmDeterministicChanges(opts, message) {
+  if (opts.yes) return true;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error(
+      "Cannot request confirmation in a non-interactive terminal. Re-run with --yes to apply deterministic fixes."
+    );
+    return false;
+  }
+  const { confirm: confirm5 } = await import("@inquirer/prompts");
+  return confirm5({ message, default: false });
+}
+function canRunInteractiveChoices(opts, taskName) {
+  if (opts.yes) {
+    console.error(
+      `--yes cannot choose how to resolve ${taskName}. Re-run without --yes in an interactive terminal.`
+    );
+    return false;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error(
+      `${taskName} fixes require an interactive terminal because each change needs an explicit choice.`
+    );
+    return false;
+  }
+  return true;
+}
+function getWeakTitleReason(t2) {
+  const title = (t2.title || "").trim();
+  if (!title) {
+    return "Missing or empty title";
+  }
+  if (title === t2.slug) {
+    return "Title is equal to technical slug";
+  }
+  if (title.length < 3) {
+    return "Title is suspiciously short";
+  }
+  if (title.length > 100) {
+    return "Title is too long (> 100 chars)";
+  }
+  if (t2.domain) {
+    const domParts = t2.domain.split(/[-/]/).filter((p) => p.length > 2);
+    const titleLower2 = title.toLowerCase();
+    for (const part of domParts) {
+      if (titleLower2.includes(part.toLowerCase())) {
+        return `Domain echo (contains '${part}' from domain '${t2.domain}')`;
+      }
+    }
+  }
+  const conceptClean = (t2.concept || "").trim().toLowerCase();
+  const titleLower = title.toLowerCase();
+  if (conceptClean.startsWith(titleLower) && t2.concept.length > title.length + 5 && !/[.!?]/.test(title)) {
+    const titleWords = titleLower.split(/\s+/).length;
+    if (titleWords <= 5) {
+      return "Concept-prefix copy";
+    }
+  }
+  if (title.endsWith("?") || /^(what|how|why|who|where|when|which|is|are|was|were|can|do|does|did|ueber|fuer|nahe)\b/i.test(
+    title
+  )) {
+    return "Question stump or interrogative structure";
+  }
+  if (title.length > 3 && /[a-zA-Z]/.test(title)) {
+    if (title === title.toUpperCase()) {
+      return "All uppercase";
+    }
+    if (title === title.toLowerCase()) {
+      return "All lowercase";
+    }
+  }
+  return null;
+}
+function stripLeadingDomainWords(value, domain) {
+  let result = value.trim();
+  for (const word of domain.split(/[-/]/).filter(Boolean)) {
+    const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    result = result.replace(new RegExp(`^${escaped}\\s+`, "i"), "");
+  }
+  return result.trim();
+}
+function truncateTitle(value) {
+  const trimmed = value.trim().replace(/^["']+|["']+$/g, "");
+  return trimmed.length <= 80 ? trimmed : `${trimmed.substring(0, 77).trimEnd()}...`;
+}
+function titleFromSlug(token) {
+  return getShortSlug(token.slug, token.domain).split(/[-_]+/).filter(Boolean).map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`).join(" ");
+}
+function validatedTitleProposal(token, raw) {
+  const candidates = [
+    raw,
+    (token.concept || "").split(/[.;]/)[0] || "",
+    titleFromSlug(token)
+  ];
+  for (const candidate of candidates) {
+    const normalized = truncateTitle(
+      stripLeadingDomainWords(candidate, token.domain || "")
+    );
+    if (normalized.length > 0 && getWeakTitleReason({ ...token, title: normalized }) === null) {
+      return normalized;
+    }
+  }
+  return null;
+}
+var doctorTasks = [
+  {
+    name: "titles",
+    description: "Backfill missing/weak human-friendly titles (no domain echoes, descriptive names).",
+    run: async (db, opts) => {
+      const tokens = await listTokens(db, {});
+      const needing = tokens.map((t2) => {
+        const reason = getWeakTitleReason(t2);
+        return reason ? { token: t2, reason } : null;
+      }).filter((x) => x !== null);
+      console.log(
+        `Found ${needing.length} tokens needing title work (of ${tokens.length}).`
+      );
+      if (needing.length === 0) return;
+      const cfg = await getLlmConfig(db);
+      const useLLM = cfg.enabled && !opts.noLlm;
+      console.log(
+        `Title generation mode: ${useLLM ? "LLM" : "Heuristic fallback"}${opts.timeoutMs ? ` (timeout: ${opts.timeoutMs}ms)` : ""}`
+      );
+      console.log("Generating proposed titles...");
+      const proposals = [];
+      let rejected = 0;
+      for (let i = 0; i < needing.length; i++) {
+        const item = needing[i];
+        process.stdout.write(
+          `\r  [${i + 1}/${needing.length}] ${item.token.slug.slice(0, 40)}...`
+        );
+        let rawProposal = "";
+        if (useLLM) {
+          try {
+            const gen = await generateTitleViaLLM(
+              db,
+              {
+                slug: item.token.slug,
+                concept: item.token.concept,
+                domain: item.token.domain,
+                question: item.token.question,
+                context: item.token.context
+              },
+              { timeoutMs: opts.timeoutMs }
+            );
+            rawProposal = gen.text;
+          } catch (_e) {
+            rawProposal = (item.token.concept || "").split(/[.;]/)[0]?.trim() || item.token.slug.replace(/-/g, " ");
+          }
+        } else {
+          rawProposal = (item.token.concept || "").split(/[.;]/)[0]?.trim() || item.token.slug.replace(/-/g, " ");
+        }
+        const proposed = validatedTitleProposal(item.token, rawProposal);
+        if (!proposed) {
+          rejected++;
+          continue;
+        }
+        proposals.push({
+          token: item.token,
+          oldTitle: item.token.title,
+          newTitle: proposed,
+          reason: item.reason
+        });
+      }
+      process.stdout.write("\n");
+      if (rejected > 0) {
+        console.warn(
+          `Skipped ${rejected} token(s) because no proposal passed title quality validation.`
+        );
+      }
+      if (proposals.length === 0) return;
+      if (!shouldApplyFixes(opts)) {
+        console.log("\nProposed changes (Dry run):");
+        for (const prop of proposals) {
+          console.log(
+            `  ${prop.token.slug}: "${prop.oldTitle}" -> "${prop.newTitle}" (Reason: ${prop.reason})`
+          );
+        }
+        console.log("\nRun with --fix to apply these changes.");
+        return;
+      }
+      if (!opts.yes) {
+        console.log("\nProposed changes:");
+        for (const prop of proposals) {
+          console.log(
+            `  ${prop.token.slug}: "${prop.oldTitle}" -> "${prop.newTitle}" (Reason: ${prop.reason})`
+          );
+        }
+      }
+      const confirmed = await confirmDeterministicChanges(
+        opts,
+        `Apply these ${proposals.length} proposed titles?`
+      );
+      if (!confirmed) {
+        console.log("Cancelled. No titles were updated.");
+        return;
+      }
+      let fixed = 0;
+      for (const prop of proposals) {
+        await updateToken(db, prop.token.slug, { title: prop.newTitle });
+        fixed++;
+        console.log(`Set title for ${prop.token.slug} -> ${prop.newTitle}`);
+      }
+      console.log(`Successfully fixed ${fixed} titles.`);
+    }
+  },
+  {
+    name: "texts",
+    description: "Repair legacy ASCII umlauts in prose fields (question/concept/context).",
+    run: async (db, opts) => {
+      const tokens = await listTokens(db, {});
+      const cfg = await getLlmConfig(db);
+      const useLLM = cfg.enabled && !opts.noLlm;
+      const replacements = [
+        [/\bUeber\b/g, "\xDCber"],
+        [/\bueber\b/g, "\xFCber"],
+        [/\bFuer\b/g, "F\xFCr"],
+        [/\bfuer\b/g, "f\xFCr"],
+        [/\bMuehe\b/g, "M\xFChe"],
+        [/\bmuehe\b/g, "m\xFChe"],
+        [/\bKuer\b/g, "K\xFCr"],
+        [/\bkuer\b/g, "k\xFCr"],
+        [/\bUebung\b/g, "\xDCbung"],
+        [/\buebung\b/g, "\xFCbung"],
+        [/\bMoeglich\b/g, "M\xF6glich"],
+        [/\bmoeglich\b/g, "m\xF6glich"],
+        [/\bMoeglichkeiten\b/g, "M\xF6glichkeiten"],
+        [/\bmoeglichkeiten\b/g, "m\xF6glichkeiten"],
+        [/\bSchoen\b/g, "Sch\xF6n"],
+        [/\bschoen\b/g, "sch\xF6n"],
+        [/\bKoennen\b/g, "K\xF6nnen"],
+        [/\bkoennen\b/g, "k\xF6nnen"],
+        [/\bMuessen\b/g, "M\xFCssen"],
+        [/\bmuessen\b/g, "m\xFCssen"],
+        [/\bDuerfen\b/g, "D\xFCrfen"],
+        [/\bduerfen\b/g, "d\xFCrfen"],
+        [/\bAerger\b/g, "\xC4rger"],
+        [/\baerger\b/g, "\xE4rger"],
+        [/\bGruende\b/g, "Gr\xFCnde"],
+        [/\bgruende\b/g, "gr\xFCnde"]
+      ];
+      const toFix = [];
+      console.log("Analyzing prose text fields for legacy umlauts...");
+      for (const t2 of tokens) {
+        const fields = [
+          { key: "question", val: t2.question },
+          { key: "concept", val: t2.concept },
+          { key: "context", val: t2.context },
+          { key: "title", val: t2.title }
+        ];
+        for (const f of fields) {
+          if (!f.val || typeof f.val !== "string") continue;
+          let repaired = f.val;
+          if (useLLM) {
+            const hasPossibleUmlautFold = /[aou]e/i.test(f.val);
+            if (hasPossibleUmlautFold) {
+              try {
+                repaired = await repairUmlautsViaLLM(
+                  db,
+                  { text: f.val },
+                  { timeoutMs: opts.timeoutMs }
+                );
+                if (repaired === f.val) {
+                  for (const [from, to] of replacements) {
+                    repaired = repaired.replace(from, to);
+                  }
+                }
+              } catch (_e) {
+                for (const [from, to] of replacements) {
+                  repaired = repaired.replace(from, to);
+                }
+              }
+            }
+          } else {
+            for (const [from, to] of replacements) {
+              repaired = repaired.replace(from, to);
+            }
+          }
+          if (repaired !== f.val) {
+            toFix.push({ token: t2, field: f.key, old: f.val, new: repaired });
+          }
+        }
+      }
+      console.log(`Found ${toFix.length} prose fields with legacy umlauts.`);
+      if (toFix.length === 0) return;
+      if (!shouldApplyFixes(opts)) {
+        console.log("\nProposed changes (Dry run):");
+        for (const fix of toFix) {
+          console.log(`  ${fix.token.slug} [${fix.field}]:`);
+          console.log(`    Old: "${fix.old}"`);
+          console.log(`    New: "${fix.new}"`);
+        }
+        console.log("\nRun with --fix to apply these changes.");
+        return;
+      }
+      if (!opts.yes) {
+        console.log("\nProposed changes:");
+        for (const fix of toFix) {
+          console.log(
+            `  ${fix.token.slug} [${fix.field}]: "${fix.old}" -> "${fix.new}"`
+          );
+        }
+      }
+      const confirmed = await confirmDeterministicChanges(
+        opts,
+        `Apply these ${toFix.length} prose fixes?`
+      );
+      if (!confirmed) {
+        console.log("Cancelled. No changes made.");
+        return;
+      }
+      let fixed = 0;
+      for (const fix of toFix) {
+        const updates = {};
+        updates[fix.field] = fix.new;
+        await updateToken(db, fix.token.slug, updates);
+        fixed++;
+      }
+      console.log(
+        `Fixed ${fixed} fields. (Re-embed will happen automatically for changed content.)`
+      );
+    }
+  },
+  {
+    name: "duplicates",
+    description: "List semantic duplicates for review/merge.",
+    run: async (db, opts) => {
+      const applyingFixes = shouldApplyFixes(opts);
+      if (applyingFixes && !canRunInteractiveChoices(opts, "duplicate fixes")) {
+        return;
+      }
+      const modelSetting = await getSetting(db, "llm.embedding.model");
+      if (!modelSetting) {
+        console.log(
+          "No embedding model configured. Please configure an embedding model to scan duplicates."
+        );
+        return;
+      }
+      const model = canonicalEmbeddingModelId(modelSetting);
+      if (model !== modelSetting.trim().toLowerCase()) {
+        console.log(
+          `Using canonical embedding model "${model}" for configured alias "${modelSetting}".`
+        );
+      }
+      let coverage = await getEmbeddingCoverage(db, model);
+      const initiallyIncomplete = coverage.missing + coverage.stale;
+      if (initiallyIncomplete > 0) {
+        if (applyingFixes) {
+          console.log(
+            `Embedding coverage is incomplete (${coverage.missing} missing, ${coverage.stale} stale). Attempting backfill...`
+          );
+          const result = await ensureTokenEmbeddings(db, {
+            limit: coverage.tokens
+          });
+          coverage = await getEmbeddingCoverage(db, model);
+          const remaining = coverage.missing + coverage.stale;
+          if (remaining > 0) {
+            console.warn(
+              `Warning: Duplicate scan is incomplete: ${remaining} of ${coverage.tokens} active tokens still lack a fresh "${model}" embedding.${result.reason ? ` ${result.reason}` : ""}`
+            );
+          } else {
+            console.log(
+              `Embedding backfill complete (${result.embedded} updated).`
+            );
+          }
+        } else {
+          console.warn(
+            `Warning: Duplicate scan is incomplete: ${initiallyIncomplete} of ${coverage.tokens} active tokens lack a fresh "${model}" embedding. Dry-run will not backfill them; run 'zam token reembed' first for a complete scan.`
+          );
+        }
+      }
+      console.log(`Listing embedded tokens for model "${model}"...`);
+      const embedded = await listEmbeddedTokens(db, model);
+      const threshold = await resolveDedupThreshold(db);
+      console.log(
+        `Scanning ${embedded.length} tokens for semantic duplicates (threshold: ${threshold})...`
+      );
+      const duplicates = [];
+      const seenPairs = /* @__PURE__ */ new Set();
+      for (let i = 0; i < embedded.length; i++) {
+        for (let j = i + 1; j < embedded.length; j++) {
+          const sim = cosineSimilarity(
+            embedded[i].embedding,
+            embedded[j].embedding
+          );
+          if (sim >= threshold) {
+            const idA = embedded[i].token.id;
+            const idB = embedded[j].token.id;
+            const pairKey = idA < idB ? `${idA}:${idB}` : `${idB}:${idA}`;
+            if (!seenPairs.has(pairKey)) {
+              seenPairs.add(pairKey);
+              duplicates.push({
+                a: embedded[i].token,
+                b: embedded[j].token,
+                similarity: sim
+              });
+            }
+          }
+        }
+      }
+      console.log(`Found ${duplicates.length} duplicate pairs.`);
+      if (duplicates.length === 0) return;
+      if (!applyingFixes) {
+        console.log("\nDuplicate pairs found (Dry run):");
+        for (const pair of duplicates) {
+          console.log(
+            `  - "${pair.a.slug}" and "${pair.b.slug}" (similarity: ${pair.similarity.toFixed(3)})`
+          );
+        }
+        console.log("\nRun with --fix to resolve duplicates interactively.");
+        return;
+      }
+      const { select: select3 } = await import("@inquirer/prompts");
+      let deprecatedCount = 0;
+      for (const pair of duplicates) {
+        console.log(
+          `
+Duplicate pair found (similarity: ${pair.similarity.toFixed(3)}):`
+        );
+        console.log(
+          `  1. ${pair.a.slug}: "${pair.a.concept.substring(0, 100)}..."`
+        );
+        console.log(
+          `  2. ${pair.b.slug}: "${pair.b.concept.substring(0, 100)}..."`
+        );
+        const choice = await select3({
+          message: "Select action:",
+          choices: [
+            { name: "Keep both", value: "keep" },
+            { name: `Deprecate ${pair.a.slug}`, value: "deprecate_a" },
+            { name: `Deprecate ${pair.b.slug}`, value: "deprecate_b" }
+          ]
+        });
+        if (choice === "deprecate_a") {
+          await deprecateToken(db, pair.a.slug);
+          console.log(`  Deprecated ${pair.a.slug}`);
+          deprecatedCount++;
+        } else if (choice === "deprecate_b") {
+          await deprecateToken(db, pair.b.slug);
+          console.log(`  Deprecated ${pair.b.slug}`);
+          deprecatedCount++;
+        }
+      }
+      console.log(
+        `
+Duplicates scan complete. Deprecated ${deprecatedCount} token(s).`
+      );
+    }
+  },
+  {
+    name: "domains",
+    description: "Help rename/unify domains into / hierarchy (slugs untouched).",
+    run: async (db, opts) => {
+      const tokens = await listTokens(db, {});
+      const domains = Array.from(
+        new Set(tokens.map((t2) => t2.domain).filter(Boolean))
+      ).sort();
+      console.log(`Current domains (${domains.length}):`);
+      for (const d of domains) {
+        const count2 = tokens.filter((t2) => t2.domain === d).length;
+        const status = d.includes("/") ? "(hierarchical)" : "(flat, valid)";
+        console.log(`  ${d} \u2014 ${count2} token(s) ${status}`);
+      }
+      if (!shouldApplyFixes(opts)) {
+        console.log("\nUse --fix to interactively rename/unify domains.");
+        return;
+      }
+      if (!canRunInteractiveChoices(opts, "domain renames")) return;
+      const { confirm: confirm5, input: input8 } = await import("@inquirer/prompts");
+      const changes = [];
+      for (const d of domains) {
+        const count2 = tokens.filter((t2) => t2.domain === d).length;
+        const wantRename = await confirm5({
+          message: `Rename domain "${d}" (${count2} tokens)?`,
+          default: false
+        });
+        if (wantRename) {
+          const newDomain = await input8({
+            message: `Enter new domain name for "${d}":`,
+            validate: (val) => val.trim().length > 0 ? true : "Domain name cannot be empty"
+          });
+          const trimmed = newDomain.trim();
+          if (trimmed === d) {
+            console.log("  New name matches old name. Skipped.");
+            continue;
+          }
+          changes.push({ oldDomain: d, newDomain: trimmed });
+        }
+      }
+      if (changes.length > 0) {
+        await db.transaction(async (tx) => {
+          const now = (/* @__PURE__ */ new Date()).toISOString();
+          const stmt = tx.prepare(
+            "UPDATE tokens SET domain = ?, updated_at = ? WHERE domain = ?"
+          );
+          for (const change of changes) {
+            const res = await stmt.run(change.newDomain, now, change.oldDomain);
+            console.log(
+              `  Renamed "${change.oldDomain}" to "${change.newDomain}" for ${res.changes} token(s).`
+            );
+          }
+        });
+      }
+      console.log(
+        `Domains rename complete. Renamed ${changes.length} domain(s).`
+      );
+    }
+  }
+];
+function parseDoctorTimeout(value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error("--timeout must be a positive integer in milliseconds");
+  }
+  return parsed;
+}
+var doctorCommand = new Command5("doctor").description(
+  "Diagnose and repair the knowledge base (titles, legacy data, duplicates, domains)."
+).option("--fix", "Apply changes (default is dry-run)").option("--dry-run", "Explicit dry run (default)").option(
+  "--yes",
+  "Auto-confirm deterministic title/text fixes (duplicate/domain choices remain interactive)"
+).option("--no-llm", "Skip LLM calls, use heuristic fallback only").option(
+  "--timeout <ms>",
+  "LLM timeout in ms per call (default: 20000)",
+  "20000"
+).argument("[task]", "Specific task: titles, texts, duplicates, domains").action(async (taskName, opts) => {
+  await withDb(async (db) => {
+    const fix = !!opts.fix;
+    const dryRun = !fix || !!opts.dryRun;
+    const yes = !!opts.yes;
+    const noLlm = opts.llm === false;
+    const timeoutMs = parseDoctorTimeout(opts.timeout);
+    if (!taskName) {
+      console.log("Available doctor tasks:");
+      for (const t2 of doctorTasks) {
+        console.log(`  ${t2.name} \u2014 ${t2.description}`);
+      }
+      console.log("\nRun with a task name, e.g. `zam doctor titles --fix`");
+      return;
+    }
+    const task = doctorTasks.find((t2) => t2.name === taskName);
+    if (!task) {
+      console.error(`Unknown task: ${taskName}`);
+      process.exit(1);
+    }
+    console.log(
+      `Running doctor task: ${task.name} (fix=${fix}, dryRun=${dryRun}${noLlm ? ", noLlm=true" : ""})`
+    );
+    await task.run(db, { fix, dryRun, yes, noLlm, timeoutMs });
+  });
+});
+
 // src/cli/commands/git-sync.ts
 import { execSync as execSync5 } from "child_process";
 import { chmodSync as chmodSync2, existsSync as existsSync18, writeFileSync as writeFileSync8 } from "fs";
 import { join as join19 } from "path";
-import { Command as Command5 } from "commander";
+import { Command as Command6 } from "commander";
 function installHook2() {
   const gitDir = join19(process.cwd(), ".git");
   if (!existsSync18(gitDir)) {
@@ -14963,7 +15726,7 @@ zam git-sync --commit HEAD --quiet
     process.exit(1);
   }
 }
-var gitSyncCommand = new Command5("git-sync").description("Sync learning cards with recent Git file modifications").option("--commit <hash>", "Git commit hash to check", "HEAD").option("--user <id>", "User ID (default: whoami)").option("--install", "Install git post-commit hook in current repo").option("--quiet", "Suppress verbose output").action(async (opts) => {
+var gitSyncCommand = new Command6("git-sync").description("Sync learning cards with recent Git file modifications").option("--commit <hash>", "Git commit hash to check", "HEAD").option("--user <id>", "User ID (default: whoami)").option("--install", "Install git post-commit hook in current repo").option("--quiet", "Suppress verbose output").action(async (opts) => {
   if (opts.install) {
     installHook2();
     return;
@@ -15055,7 +15818,7 @@ ZAM Auto-Stale Complete: Scanned ${changedFiles.length} file(s).`
 import { existsSync as existsSync19, mkdirSync as mkdirSync11 } from "fs";
 import { resolve as resolve5 } from "path";
 import { input as input2 } from "@inquirer/prompts";
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 async function resolveGoalsDir() {
   let goalsDir;
   let db;
@@ -15068,7 +15831,7 @@ async function resolveGoalsDir() {
   }
   return goalsDir ? resolve5(goalsDir) : resolve5("goals");
 }
-var goalCommand = new Command6("goal").description(
+var goalCommand = new Command7("goal").description(
   "Manage learning goals (markdown files)"
 );
 goalCommand.command("list").description("List all goals").option(
@@ -15241,7 +16004,7 @@ import { existsSync as existsSync20, mkdirSync as mkdirSync12, writeFileSync as
 import { homedir as homedir11 } from "os";
 import { join as join20, resolve as resolve6 } from "path";
 import { confirm, input as input3 } from "@inquirer/prompts";
-import { Command as Command7 } from "commander";
+import { Command as Command8 } from "commander";
 var HOME2 = homedir11();
 function printLine(char = "\u2550", len = 60, color = "\x1B[36m") {
   console.log(`${color}${char.repeat(len)}\x1B[0m`);
@@ -15278,7 +16041,7 @@ Here, I declare the core concepts and principles I want to master.
     );
   }
 }
-var initCommand = new Command7("init").description("Launch the guided interactive onboarding wizard").action(async () => {
+var initCommand = new Command8("init").description("Launch the guided interactive onboarding wizard").action(async () => {
   printLine();
   console.log(
     "\x1B[1m\x1B[32m          ZAM \u2014 The Symbiotic Learning Agent Onboarding\x1B[0m"
@@ -15455,7 +16218,7 @@ var initCommand = new Command7("init").description("Launch the guided interactiv
 
 // src/cli/commands/learn.ts
 import { input as input5 } from "@inquirer/prompts";
-import { Command as Command8 } from "commander";
+import { Command as Command9 } from "commander";
 
 // src/cli/learn-format.ts
 var BLOOM_VERBS3 = {
@@ -15471,16 +16234,22 @@ function clampBloom(n) {
 function formatHeader(input8) {
   const lvl = clampBloom(input8.bloomLevel);
   const parts = [`${BLOOM_VERBS3[lvl]} (Bloom ${lvl})`];
-  if (input8.domain?.trim()) {
+  const name = input8.title || input8.slug;
+  if (name) {
+    parts.push(name);
+  } else if (input8.domain?.trim()) {
     parts.push(input8.domain.trim());
   }
   return parts.join(" \xB7 ");
 }
 function formatReveal(input8) {
   const lines = [
-    `Token: #${input8.slug}`,
+    `Token: ${input8.title || input8.slug}`,
     `Concept: ${input8.concept}`
   ];
+  if (input8.title) {
+    lines.push(`ID: #${input8.slug}`);
+  }
   if (input8.context?.trim()) {
     lines.push("", `Context: ${input8.context.trim()}`);
   }
@@ -15793,7 +16562,7 @@ var STOP_WORDS = /* @__PURE__ */ new Set(["q", ":q", "quit", "stop"]);
 function isExitPrompt(err) {
   return err instanceof Error && err.name === "ExitPromptError";
 }
-var learnCommand = new Command8("learn").description(
+var learnCommand = new Command9("learn").description(
   "Run a spoiler-free, in-process learning session (recall \u2192 reveal \u2192 self-rate)"
 ).option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into the revealed answer").action(async (opts) => {
   let db;
@@ -15867,7 +16636,7 @@ ${t(locale, "welcome", { count: queue.items.length })}`);
       console.log(`
 ${"\u2500".repeat(50)}`);
       console.log(
-        `[${index + 1}/${queue.items.length}] ${formatHeader(item)}`
+        `[${index + 1}/${queue.items.length}] ${formatHeader({ bloomLevel: item.bloomLevel, domain: item.domain })}`
       );
       console.log(`
   ${prompt.question}`);
@@ -15931,6 +16700,7 @@ ${t(locale, "eval_skipped", { reason: err.message })}`
       );
       const reveal = formatReveal({
         slug: item.slug,
+        title: item.title,
         concept: item.concept,
         context: token?.context,
         resolved
@@ -16038,8 +16808,8 @@ learnCommand.command("open").description("Open a new terminal window running zam
 });
 
 // src/cli/commands/monitor.ts
-import { Command as Command9 } from "commander";
-var monitorCommand = new Command9("monitor").description(
+import { Command as Command10 } from "commander";
+var monitorCommand = new Command10("monitor").description(
   "Shell observation for real-time task monitoring"
 );
 monitorCommand.command("start").description("Output shell hook code to install monitoring").requiredOption("--session <id>", "Session ID to monitor").option(
@@ -16221,8 +16991,8 @@ monitorCommand.command("open").description("Open a new monitored terminal window
 });
 
 // src/cli/commands/observer.ts
-import { Command as Command10 } from "commander";
-var observerCommand = new Command10("observer").description(
+import { Command as Command11 } from "commander";
+var observerCommand = new Command11("observer").description(
   "Configure what the UI observer may capture (Layer 2 policy)"
 );
 function applyObserverListChange(current, entry, op) {
@@ -16285,7 +17055,7 @@ observerCommand.command("revoke <process>").description("Remove a process from o
 
 // src/cli/commands/profile.ts
 import { dirname as dirname6, resolve as resolve7 } from "path";
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 var C2 = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -16302,7 +17072,7 @@ function render(profile) {
   console.log(`  data dir:      ${C2.cyan}${profile.dataDir}${C2.reset}`);
   console.log(`  database:      ${C2.cyan}${profile.dbPath}${C2.reset}`);
 }
-var profileCommand = new Command11("profile").description("Show or change this machine's ZAM install profile").option("--mode <mode>", "Set install mode: developer | default").option("--dir <path>", "Set the personal-content folder").option("--json", "Output as JSON").action(async (opts) => {
+var profileCommand = new Command12("profile").description("Show or change this machine's ZAM install profile").option("--mode <mode>", "Set install mode: developer | default").option("--dir <path>", "Set the personal-content folder").option("--json", "Output as JSON").action(async (opts) => {
   if (opts.mode && opts.mode !== "developer" && opts.mode !== "default") {
     console.error(`Invalid --mode: ${opts.mode}. Use developer or default.`);
     process.exit(1);
@@ -16342,8 +17112,8 @@ var profileCommand = new Command11("profile").description("Show or change this m
 
 // src/cli/commands/provider.ts
 import { password as password2 } from "@inquirer/prompts";
-import { Command as Command12 } from "commander";
-var providerCommand = new Command12("provider").description(
+import { Command as Command13 } from "commander";
+var providerCommand = new Command13("provider").description(
   "Configure role-based AI providers (url/model/flavor/key, per role)"
 );
 providerCommand.command("list").description("Show configured providers, role bindings, and key status").option("--json", "Output as JSON").option("--machine", "Read machine-local providers from ~/.zam/config.json").action(async (opts) => {
@@ -16578,8 +17348,8 @@ providerCommand.command("clear-key <ref>").description("Remove a stored API key"
 });
 
 // src/cli/commands/review.ts
-import { Command as Command13 } from "commander";
-var reviewCommand = new Command13("review").description("Start an interactive review session").option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into inline context").action(async (opts) => {
+import { Command as Command14 } from "commander";
+var reviewCommand = new Command14("review").description("Start an interactive review session").option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into inline context").action(async (opts) => {
   let db;
   try {
     db = await openDatabase();
@@ -16617,9 +17387,8 @@ Review session: ${queue.items.length} card(s)`);
       });
       console.log(
         `
-[${index + 1}/${queue.items.length}] ${prompt.bloomVerb} (Bloom ${prompt.bloomLevel})`
+[${index + 1}/${queue.items.length}] ${formatHeader({ bloomLevel: item.bloomLevel, domain: item.domain })}`
       );
-      console.log(`Domain: ${prompt.domain || "(none)"}`);
       if (prompt.sourceLink) {
         console.log(`Source: ${prompt.sourceLink}`);
         if (opts.resolve !== false) {
@@ -16694,8 +17463,8 @@ ${"\u2550".repeat(50)}`);
 // src/cli/commands/session.ts
 import { readFileSync as readFileSync13 } from "fs";
 import { input as input6, select as select2 } from "@inquirer/prompts";
-import { Command as Command14 } from "commander";
-var sessionCommand = new Command14("session").description(
+import { Command as Command15 } from "commander";
+var sessionCommand = new Command15("session").description(
   "Manage learning sessions"
 );
 sessionCommand.command("start").description("Start a new learning session (review \u2192 task)").option("--user <id>", "User ID (default: whoami)").option("--task <description>", "Task description (interactive if omitted)").option(
@@ -16819,9 +17588,8 @@ Time limit reached (${maxMinutes} min). Moving to task selection.`
     });
     const elapsed = Math.round((Date.now() - startTime) / 6e4);
     console.log(
-      `[${index + 1}/${queue.items.length}] ${prompt.bloomVerb} (Bloom ${prompt.bloomLevel}) \u2014 ${elapsed}/${maxMinutes} min`
+      `[${index + 1}/${queue.items.length}] ${formatHeader({ bloomLevel: item.bloomLevel, domain: item.domain })} (${elapsed}/${maxMinutes} min)`
     );
-    console.log(`Domain: ${prompt.domain || "(none)"}`);
     console.log(`
   ${prompt.question}
 `);
@@ -17075,8 +17843,8 @@ sessionCommand.command("end").description("End a session and show summary").requ
 
 // src/cli/commands/settings.ts
 import { existsSync as existsSync21 } from "fs";
-import { Command as Command15 } from "commander";
-var settingsCommand = new Command15("settings").description(
+import { Command as Command16 } from "commander";
+var settingsCommand = new Command16("settings").description(
   "Manage user settings"
 );
 var BOOLEAN_SETTING_KEYS = /* @__PURE__ */ new Set(["llm.enabled", "llm.vision.enabled"]);
@@ -17252,7 +18020,7 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
 
 // src/cli/commands/setup.ts
 import { resolve as resolve8 } from "path";
-import { Command as Command16 } from "commander";
+import { Command as Command17 } from "commander";
 function formatDatabaseInitTarget(target) {
   switch (target.kind) {
     case "local":
@@ -17293,7 +18061,7 @@ async function activateMachineProviderConfig(db) {
     `  activate  ${providerCount} machine-local provider(s) from ~/.zam/config.json`
   );
 }
-var setupCommand = new Command16("setup").description(
+var setupCommand = new Command17("setup").description(
   "Link ZAM skill directories into this workspace and initialize the database"
 ).option("--force", "replace an unmanaged existing ZAM skill directory", false).option("--skip-init", "skip database initialization", false).option("--skip-claude-md", "skip CLAUDE.md generation", false).option("--skip-agents-md", "skip AGENTS.md generation", false).option("--target <path>", "repository/workspace directory to set up").option(
   "--agents <list>",
@@ -17347,8 +18115,8 @@ var setupCommand = new Command16("setup").description(
 );
 
 // src/cli/commands/skill.ts
-import { Command as Command17 } from "commander";
-var skillCommand = new Command17("skill").description(
+import { Command as Command18 } from "commander";
+var skillCommand = new Command18("skill").description(
   "Manage agent skill entries (task recipes)"
 );
 skillCommand.command("list").description("List all agent skills").option("--json", "Output as JSON").action(async (opts) => {
@@ -17435,7 +18203,7 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 // src/cli/commands/snapshot.ts
 import { existsSync as existsSync22, mkdirSync as mkdirSync13, readFileSync as readFileSync14, writeFileSync as writeFileSync10 } from "fs";
 import { dirname as dirname7, join as join21 } from "path";
-import { Command as Command18 } from "commander";
+import { Command as Command19 } from "commander";
 function defaultOutName() {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
   return `zam-snapshot-${stamp}.sql`;
@@ -17449,7 +18217,7 @@ function summarize(tables) {
   }
   return { total, nonEmpty };
 }
-var exportCmd = new Command18("export").description("Write a portable SQL-text snapshot of the database").option("--out <file>", "Output file (use - for stdout)").action(async (opts) => {
+var exportCmd = new Command19("export").description("Write a portable SQL-text snapshot of the database").option("--out <file>", "Output file (use - for stdout)").action(async (opts) => {
   let db;
   try {
     db = await openDatabaseWithSync({ initialize: true });
@@ -17479,7 +18247,7 @@ var exportCmd = new Command18("export").description("Write a portable SQL-text s
     process.exit(1);
   }
 });
-var importCmd = new Command18("import").description("Restore a snapshot into the database").argument("<file>", "Snapshot file to restore").option("--force", "Overwrite a non-empty database", false).action(async (file, opts) => {
+var importCmd = new Command19("import").description("Restore a snapshot into the database").argument("<file>", "Snapshot file to restore").option("--force", "Overwrite a non-empty database", false).action(async (file, opts) => {
   let db;
   try {
     if (!existsSync22(file)) {
@@ -17502,7 +18270,7 @@ var importCmd = new Command18("import").description("Restore a snapshot into the
     process.exit(1);
   }
 });
-var verifyCmd = new Command18("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
+var verifyCmd = new Command19("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
   try {
     if (!existsSync22(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
@@ -17520,11 +18288,11 @@ var verifyCmd = new Command18("verify").description("Check a snapshot's manifest
     process.exit(1);
   }
 });
-var snapshotCommand = new Command18("snapshot").description("Export, import, or verify a portable database snapshot").addCommand(exportCmd).addCommand(importCmd).addCommand(verifyCmd);
+var snapshotCommand = new Command19("snapshot").description("Export, import, or verify a portable database snapshot").addCommand(exportCmd).addCommand(importCmd).addCommand(verifyCmd);
 
 // src/cli/commands/stats.ts
-import { Command as Command19 } from "commander";
-var statsCommand = new Command19("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
+import { Command as Command20 } from "commander";
+var statsCommand = new Command20("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
   await withDb(async (db) => {
     const userId = await resolveUser(opts, db);
     const stats = await getUserStats(db, userId);
@@ -17560,8 +18328,8 @@ var statsCommand = new Command19("stats").description("Show learning dashboard f
 });
 
 // src/cli/commands/token.ts
-import { Command as Command20 } from "commander";
-var tokenCommand = new Command20("token").description(
+import { Command as Command21 } from "commander";
+var tokenCommand = new Command21("token").description(
   "Manage knowledge tokens"
 );
 tokenCommand.command("register").description("Register a new knowledge token").requiredOption("--slug <slug>", "Unique token slug").requiredOption("--concept <concept>", "Concept description").option("--domain <domain>", "Knowledge domain", "").option("--bloom <level>", "Bloom taxonomy level (1-5)", "1").option("--source-link <link>", "Source file path or reference URL", "").option("--question <question>", "Specific question prompt for recall", "").option("--user <id>", "Owner of the personal card (default: whoami)").option("--no-card", "Register the token only; do not create a personal card").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
@@ -17612,7 +18380,11 @@ tokenCommand.command("register").description("Register a new knowledge token").r
         )
       );
     } else {
-      console.log(`Registered token: ${token.slug} (${token.id})`);
+      console.log(`Registered token: ${token.title || token.slug}`);
+      if (token.slug !== (token.title || token.slug)) {
+        console.log(`  Slug: ${token.slug}`);
+      }
+      console.log(`  ID:   ${token.id}`);
       console.log(`  Concept:  ${token.concept}`);
       console.log(`  Domain:   ${token.domain || "(none)"}`);
       console.log(`  Bloom:    ${token.bloom_level}`);
@@ -17631,8 +18403,9 @@ tokenCommand.command("register").description("Register a new knowledge token").r
         console.log(`
 WARNING: Possible duplicate tokens found:`);
         for (const dup of possibleDuplicates) {
+          const name = dup.title || dup.slug;
           console.log(
-            `  - ${dup.slug} (similarity: ${dup.similarity.toFixed(2)})`
+            `  - ${name} (slug: ${dup.slug}, similarity: ${dup.similarity.toFixed(2)})`
           );
         }
       }
@@ -17640,7 +18413,8 @@ WARNING: Possible duplicate tokens found:`);
         const queryText = embeddingContentForToken({
           concept: opts.concept,
           question: question ?? null,
-          domain: opts.domain ?? ""
+          domain: opts.domain ?? "",
+          title: opts.title ?? null
         });
         const q2 = await embedQuery(db, queryText);
         if (q2) {
@@ -17707,16 +18481,18 @@ tokenCommand.command("find").description("Fuzzy search for tokens").requiredOpti
     console.log(`Found ${results.length} token(s):
 `);
     console.log(
-      "Score  Sim  Slug                  Concept                         Domain      Bloom"
+      "Score  Sim  Title                         Concept                         Domain      Bloom"
     );
     console.log("\u2500".repeat(95));
     for (const t2 of results) {
       const scoreStr = t2.score.toFixed(3).padEnd(6);
       const simStr = (t2.similarity?.toFixed(2) ?? "-").padEnd(4);
+      const display = getDisplayTitle(t2);
       console.log(
-        `${scoreStr} ${simStr} ${t2.slug.padEnd(21)} ${t2.concept.slice(0, 31).padEnd(31)} ${(t2.domain || "-").padEnd(11)} ${t2.bloom_level}`
+        `${scoreStr} ${simStr} ${display.padEnd(28)} ${t2.concept.slice(0, 31).padEnd(31)} ${(t2.domain || "-").padEnd(11)} ${t2.bloom_level}`
       );
     }
+    console.log("\n(Use slug for CLI commands -- slugs are technical IDs)");
   });
 });
 tokenCommand.command("list").description("List all tokens").option("--domain <domain>", "Filter by domain").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
@@ -17735,16 +18511,20 @@ tokenCommand.command("list").description("List all tokens").option("--domain <do
       return;
     }
     console.log(
-      "Slug                  Concept                         Domain      Bloom"
+      "Title                         Concept                         Domain      Bloom"
     );
-    console.log("\u2500".repeat(80));
+    console.log("\u2500".repeat(85));
     for (const t2 of tokens) {
+      const display = getDisplayTitle(t2);
       console.log(
-        `${t2.slug.padEnd(21)} ${t2.concept.slice(0, 31).padEnd(31)} ${(t2.domain || "-").padEnd(11)} ${t2.bloom_level}`
+        `${display.padEnd(28)} ${t2.concept.slice(0, 31).padEnd(31)} ${(t2.domain || "-").padEnd(11)} ${t2.bloom_level}`
       );
     }
     console.log(`
 ${tokens.length} token(s) total.`);
+    console.log(
+      "(Use --slug <slug> for commands; slugs are technical identifiers)"
+    );
   });
 });
 tokenCommand.command("edit").description("Edit a token's mutable fields").requiredOption("--slug <slug>", "Token slug").option("--concept <concept>", "Updated concept text").option("--domain <domain>", "Updated domain (blank allowed)").option("--bloom <level>", "Updated Bloom taxonomy level (1-5)").option("--context <context>", "Updated context (blank allowed)").option(
@@ -17753,7 +18533,10 @@ tokenCommand.command("edit").description("Edit a token's mutable fields").requir
 ).option(
   "--source-link <link>",
   "Updated source file path or reference URL (blank allowed)"
-).option("--question <question>", "Updated question text (blank allowed)").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
+).option("--question <question>", "Updated question text (blank allowed)").option(
+  "--title <title>",
+  "Updated human-friendly title for graph display (blank allowed)"
+).option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
   await withDb(async (db) => {
     const updates = {};
     if (opts.concept !== void 0) updates.concept = opts.concept;
@@ -17767,6 +18550,9 @@ tokenCommand.command("edit").description("Edit a token's mutable fields").requir
     if (opts.question !== void 0) {
       updates.question = opts.question === "" ? null : opts.question;
     }
+    if (opts.title !== void 0) {
+      updates.title = opts.title === "" ? "" : opts.title;
+    }
     if (opts.mode !== void 0) {
       const validModes = ["shadowing", "copilot", "autonomy", "none"];
       if (!validModes.includes(opts.mode)) {
@@ -17781,11 +18567,15 @@ tokenCommand.command("edit").description("Edit a token's mutable fields").requir
       jsonOut(token);
       return;
     }
-    console.log(`Updated token: ${token.slug}`);
+    console.log(`Updated token: ${token.title || token.slug}`);
+    if (token.slug !== (token.title || token.slug)) {
+      console.log(`  Slug: ${token.slug}`);
+    }
     console.log(`  Concept:  ${token.concept}`);
     console.log(`  Domain:   ${token.domain || "(none)"}`);
     console.log(`  Bloom:    ${token.bloom_level}`);
     console.log(`  Question: ${token.question || "(none)"}`);
+    console.log(`  Title:    ${token.title || "(none)"}`);
     console.log(`  Context:  ${token.context || "(none)"}`);
     console.log(`  Mode:     ${token.symbiosis_mode ?? "none"}`);
     console.log(`  Source:   ${token.source_link || "(none)"}`);
@@ -17904,7 +18694,11 @@ tokenCommand.command("status").description("Show full status of a token for a us
       console.log(JSON.stringify(status, null, 2));
       return;
     }
-    console.log(`Token: ${token.slug} (${token.id})`);
+    console.log(`Token: ${token.title || token.slug}`);
+    if (token.slug !== (token.title || token.slug)) {
+      console.log(`  Slug:     ${token.slug}`);
+    }
+    console.log(`  ID:       ${token.id}`);
     console.log(`  Concept:  ${token.concept}`);
     console.log(`  Question: ${token.question || "(none)"}`);
     console.log(`  Domain:   ${token.domain || "(none)"}`);
@@ -17929,7 +18723,9 @@ tokenCommand.command("status").description("Show full status of a token for a us
     if (prereqs.length > 0) {
       console.log("Prerequisites:");
       for (const p of prereqs) {
-        console.log(`  - ${p.slug}: ${p.concept} (bloom ${p.bloom_level})`);
+        console.log(
+          `  - ${p.title || p.slug}: ${p.concept} (bloom ${p.bloom_level})`
+        );
       }
     } else {
       console.log("No prerequisites.");
@@ -17937,7 +18733,9 @@ tokenCommand.command("status").description("Show full status of a token for a us
     if (dependents.length > 0) {
       console.log("\nDependents:");
       for (const d of dependents) {
-        console.log(`  - ${d.slug}: ${d.concept} (bloom ${d.bloom_level})`);
+        console.log(
+          `  - ${d.title || d.slug}: ${d.concept} (bloom ${d.bloom_level})`
+        );
       }
     }
   });
@@ -17999,7 +18797,7 @@ import { existsSync as existsSync23 } from "fs";
 import { homedir as homedir12 } from "os";
 import { dirname as dirname8, join as join22 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import { Command as Command21 } from "commander";
+import { Command as Command22 } from "commander";
 var C3 = {
   reset: "\x1B[0m",
   red: "\x1B[31m",
@@ -18179,7 +18977,7 @@ function createShortcuts(appPath, repoRoot) {
     console.error(`${C3.red}\u2717 Could not create shortcuts.${C3.reset}`);
   }
 }
-var uiCommand = new Command21("ui").description("Launch the ZAM Desktop GUI (Active-Recall Studio)").option("--dev", "Run in hot-reload development mode (needs Rust)").option(
+var uiCommand = new Command22("ui").description("Launch the ZAM Desktop GUI (Active-Recall Studio)").option("--dev", "Run in hot-reload development mode (needs Rust)").option(
   "--build",
   "Build the native installer for your OS (needs Rust, one-time)"
 ).option("--shortcut", "Create Desktop + Start-menu shortcuts to the GUI").action((opts) => {
@@ -18287,7 +19085,7 @@ import { existsSync as existsSync24, readFileSync as readFileSync15, realpathSyn
 import { dirname as dirname9, join as join23 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { confirm as confirm3 } from "@inquirer/prompts";
-import { Command as Command22 } from "commander";
+import { Command as Command23 } from "commander";
 var GITHUB_REPO = "zam-os/zam";
 var CHANNELS = [
   "developer",
@@ -18365,7 +19163,7 @@ function render2(decision) {
     );
   }
 }
-var checkCmd = new Command22("check").description("Check whether a newer ZAM has been released").option(
+var checkCmd = new Command23("check").description("Check whether a newer ZAM has been released").option(
   "--latest <version>",
   "Compare against this version instead of fetching"
 ).option("--channel <channel>", "Override the detected install channel").option("--json", "Output as JSON").action(
@@ -18532,7 +19330,7 @@ ${C4.dim}This install updates through the desktop app's signed updater \u2014 op
     process.exit(1);
   }
 }
-var updateCommand = new Command22("update").description(
+var updateCommand = new Command23("update").description(
   "Update ZAM to the latest release (use `update check` to only check)"
 ).option("-y, --yes", "Apply without confirmation").option(
   "--force",
@@ -18542,8 +19340,8 @@ var updateCommand = new Command22("update").description(
 }).addCommand(checkCmd);
 
 // src/cli/commands/whoami.ts
-import { Command as Command23 } from "commander";
-var whoamiCommand = new Command23("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action(async (opts) => {
+import { Command as Command24 } from "commander";
+var whoamiCommand = new Command24("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action(async (opts) => {
   await withDb(async (db) => {
     if (opts.set) {
       await setSetting(db, "user.id", opts.set);
@@ -18584,7 +19382,7 @@ import { existsSync as existsSync25, writeFileSync as writeFileSync11 } from "fs
 import { homedir as homedir13 } from "os";
 import { join as join24, resolve as resolve9 } from "path";
 import { confirm as confirm4, input as input7 } from "@inquirer/prompts";
-import { Command as Command24 } from "commander";
+import { Command as Command25 } from "commander";
 function runGit2(cwd, args) {
   try {
     return execFileSync4("git", args, {
@@ -18602,7 +19400,7 @@ function ghRepoCreateArgs(repoName, repoVisibility) {
 function gitRemoteArgs(githubUrl, hasOrigin) {
   return hasOrigin ? ["remote", "set-url", "origin", githubUrl] : ["remote", "add", "origin", githubUrl];
 }
-var workspaceCommand = new Command24("workspace").description(
+var workspaceCommand = new Command25("workspace").description(
   "Manage your ZAM learning workspace"
 );
 var WORKSPACE_KINDS = [
@@ -18957,13 +19755,14 @@ var __dirname = dirname10(fileURLToPath5(import.meta.url));
 var pkg = JSON.parse(
   readFileSync16(join25(__dirname, "..", "..", "package.json"), "utf-8")
 );
-var program = new Command25();
+var program = new Command26();
 program.name("zam").description(
   "The Symbiotic Learning Kernel: Elevating Human Intelligence through AI Collaboration."
 ).version(pkg.version);
 program.addCommand(initCommand);
 program.addCommand(setupCommand);
 program.addCommand(tokenCommand);
+program.addCommand(doctorCommand);
 program.addCommand(cardCommand);
 program.addCommand(sessionCommand);
 program.addCommand(statsCommand);