zam-core 0.7.0 → 0.7.2

package/dist/index.d.ts

@@ -562,16 +562,23 @@ interface Prerequisite {
 /** A prerequisite row joined with the token it points to. */
 interface PrerequisiteWithToken extends Prerequisite {
     slug: string;
+    title: string;
     concept: string;
     domain: string;
     bloom_level: number;
 }
+/**
+ * Collect all prerequisite edges as an adjacency map: child → parent set.
+ * Only used for cycle detection; the full graph is loaded once per
+ * addPrerequisite call (small N in practice).
+ */
+declare function buildAncestorMap(db: Database): Promise<Map<string, Set<string>>>;
 /**
  * Returns true if adding edge (tokenId → requiresId) would create a cycle.
  * Uses BFS from requiresId: if tokenId is reachable, adding the edge closes
  * a loop.
  */
-declare function wouldCreateCycle(db: Database, tokenId: string, requiresId: string): Promise<boolean>;
+declare function wouldCreateCycle(db: Database, tokenId: string, requiresId: string, ancestors?: Map<string, Set<string>>): Promise<boolean>;
 /**
  * Add a prerequisite edge: tokenId requires requiresId.
  *
@@ -597,6 +604,7 @@ declare function getDependents(db: Database, tokenId: string): Promise<Prerequis
 interface NeighborhoodToken {
     id: string;
     slug: string;
+    title: string;
     concept: string;
     domain: string;
     bloom_level: number;
@@ -796,6 +804,7 @@ type SymbiosisMode = "shadowing" | "copilot" | "autonomy";
 interface Token {
     id: string;
     slug: string;
+    title: string;
     concept: string;
     domain: string;
     bloom_level: BloomLevel$1;
@@ -811,6 +820,7 @@ interface Token {
 }
 interface CreateTokenInput {
     slug: string;
+    title?: string;
     concept: string;
     domain?: string;
     bloom_level?: BloomLevel$1;
@@ -822,6 +832,7 @@ interface CreateTokenInput {
     topic_id?: string | null;
 }
 interface UpdateTokenInput {
+    title?: string | null;
     concept?: string;
     domain?: string;
     bloom_level?: BloomLevel$1;
@@ -834,6 +845,11 @@ interface UpdateTokenInput {
 }
 interface ListTokensOptions {
     domain?: string;
+    /**
+     * Filter by domain prefix using `/` as separator (e.g. "docuware-cops").
+     * Matches exact or startsWith(prefix + "/").
+     */
+    domainPrefix?: string;
 }
 interface TokenDeleteImpact {
     cards: number;
@@ -909,6 +925,7 @@ declare function listTokens(db: Database, options?: ListTokensOptions): Promise<
 interface PersonalCard {
     tokenId: string;
     slug: string;
+    title: string;
     concept: string;
     domain: string;
     bloomLevel: BloomLevel$1;
@@ -932,6 +949,18 @@ interface PersonalCard {
     topicId: string | null;
 }
 declare function slugify(text: string): string;
+/**
+ * Strip domain prefix (using / separator) from slug for display.
+ */
+declare function getShortSlug(slug: string, domainPrefix?: string | null): string;
+/**
+ * Primary display name for a token: human title if present, else short slug.
+ * Never falls back to concept (which is a spoiler).
+ */
+declare function getDisplayTitle(t: {
+    title?: string | null;
+    slug: string;
+}, activeDomainScope?: string | null): string;
 declare function generateTokenSlug(db: Database, domain: string, concept: string, question?: string | null): Promise<string>;
 declare function listPersonalCards(db: Database, userId: string, options?: {
     query?: string;
@@ -940,6 +969,7 @@ declare function listPersonalCards(db: Database, userId: string, options?: {
 interface CurriculumCardInput {
     question: string;
     concept: string;
+    title?: string;
     domain: string;
     source_link?: string | null;
     context?: string;
@@ -976,6 +1006,7 @@ interface FoundationProposalInput {
     question: string;
     concept: string;
     domain: string;
+    title?: string;
     context?: string;
     bloom_level?: number;
     symbiosis_mode?: string | null;
@@ -996,6 +1027,7 @@ interface SourceProposalInput {
     question: string;
     concept: string;
     domain: string;
+    title?: string;
     bloom_level: number;
     symbiosis_mode: string;
     excerpt: string;
@@ -1048,7 +1080,9 @@ interface EmbeddedTokenRow {
  * vector derives from exactly this string — never the slug, which is an
  * identifier, not meaning.
  */
-declare function embeddingContentForToken(t: Pick<Token, "concept" | "question" | "domain">): string;
+declare function embeddingContentForToken(t: Pick<Token, "concept" | "question" | "domain"> & {
+    title?: string | null;
+}): string;
 declare function computeContentHash(text: string): string;
 /**
  * Encode a vector as a little-endian float32 BLOB. Builds a fresh buffer (no
@@ -1849,6 +1883,7 @@ interface ReviewQueueItem {
     cardId: string;
     tokenId: string;
     slug: string;
+    title: string;
     concept: string;
     domain: string;
     bloomLevel: number;
@@ -1910,6 +1945,39 @@ declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
  */
 declare function searchTokensHybrid(db: Database, query: string, opts?: HybridSearchOptions): Promise<HybridScoredToken[]>;
 
+/**
+ * Foundation suggestions for tokens.
+ * Suggests existing tokens that are semantically related as prerequisite candidates.
+ *
+ * This module is pure math + database queries — zero LLM dependencies, no HTTP.
+ */
+
+interface FoundationSuggestion {
+    token: Token;
+    similarity: number;
+    alreadyPrerequisite: boolean;
+    wouldCreateCycle: boolean;
+    /** Candidate's bloom_level is higher than the target's — unusual for a foundation. */
+    bloomAboveTarget: boolean;
+}
+interface SuggestFoundationsOptions {
+    queryEmbedding: ArrayLike<number>;
+    /** Canonical embedding model id the stored vectors must match. */
+    model: string;
+    /** Set when the target token already exists (register-after / rating-1 flow). */
+    targetTokenId?: string;
+    /** Used for the bloomAboveTarget flag; defaults to 5 (nothing flagged). */
+    targetBloomLevel?: BloomLevel$1;
+    limit?: number;
+    minSimilarity?: number;
+    maxSimilarity?: number;
+}
+/**
+ * Suggests existing tokens that are semantically related as prerequisite candidates.
+ * Filters by similarity range and ranks descending by similarity.
+ */
+declare function suggestFoundations(db: Database, opts: SuggestFoundationsOptions): Promise<FoundationSuggestion[]>;
+
 /**
  * Get the path to ZAM's internal package SKILL.md.
  */
@@ -2194,4 +2262,4 @@ declare function resolveAllBeliefPaths(db: Database): Promise<string[]>;
  */
 declare function resolveAllGoalPaths(db: Database): Promise<string[]>;
 
-export { type ADOConfig, type ADOCredentials, type AgentSkill, type AnalysisResult, type ApplySessionSynthesisInput, type ApplySessionSynthesisResult, BUILT_IN_SENSITIVE_MATCHERS, type BloomLevel$1 as BloomLevel, type CaptureDecision, type CaptureDenialReason, type CaptureRequest, type Card, type CardDeletionImpact, type CardState$1 as CardState, type CascadeBlockResult, type CommandRecord, type CommandSequence, type ConfirmFoundationsResult, type ConnectionOptions, type CreateAgentSkillInput, type CreateGoalInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type Credentials, type CurriculumCardInput, DEFAULT_OBSERVER_POLICY, DEFAULT_REVIEW_CONTEXT_MAX_CHARS, type Database, type DatabaseProvider, type DatabaseTargetInfo, type DatabaseValue, type DeleteCardResult, type DeleteTokenResult, type DiscoveryOptions, type DomainCompetence, type EmbeddedTokenRow, type EmbeddingCoverage, type EmbeddingStaleness, type EvaluateInput, type EvaluateResult, type ExecuteReviewActionInput, type ExecutionContext, type FSRSParameters, type FoundationProposalInput, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, HOMEBREW_CASK, type HybridScoredToken, type HybridSearchOptions, type ImportCurriculumResult, type ImportResult, type InstallChannel, type InstallConfig, type InstallMode, type InstallPlan, type InstallResult, type LocalLLMRunner, type LogStepInput, type MachineAiConfig, type MachineProviderRecord, type MachineRoleBinding, type MonitorEvent, type Neighborhood, type NeighborhoodToken, OBSERVER_POLICY_UNSET_HINT, OBSERVER_POLICY_VERSION, type ObservationRating, type ObserverConsent, type ObserverPolicy, type ObserverRetention, type ObserverScope, type ObserverSettingKey, type OllamaDetectionOptions, type PersonalCard, type PrepareSessionSynthesisInput, type Prerequisite, type PrerequisiteWithToken, type PromptInput, REVIEW_CONTEXT_CACHE_TTL_MS, type Rating, type RecallPrompt, type RemoteDatabaseOptions, type RepoPaths, type ResolvedCaptureTarget, type ResolvedReference, type ReviewActionResult, type ReviewActionType, type ReviewContext, type ReviewLog, type ReviewQueue, type ReviewQueueItem, type ReviewQueueOptions, type RunResult, SIDECAR_POLICY_FILE, SNAPSHOT_VERSION, type SchedulingCard, type Session, type SessionStep, type SessionSummary, type SessionSynthesisCandidate, type SessionSynthesisEvidence, type SessionSynthesisPreview, type SessionSynthesisRecord, type SidecarPrivacyPolicy, type SkillProposal, type SkillSource, type SnapshotManifest, type SourceProposalInput, type SplitProposalInput, type Statement, type SupportedLocale, type SymbiosisMode, type SynthesisConfidence, type SystemProfile, type Token, type TokenDeleteImpact, type TokenEmbedding, type TokenNeedingEmbedding, type TokenPattern, type TranslationKey, type TursoCredentials, UI_OBSERVATION_PROTOCOL_VERSION, type UiActionType, type UiApplicationContext, type UiCandidateToken, type UiEvidenceRef, type UiEvidenceType, type UiObservationKind, type UiObservationReport, type UiObservedAction, type UnblockResult, type UpdateActionKind, type UpdateCardInput, type UpdateDecision, type UpdateStep, type UpdateStepKind, type UpdateTokenInput, type UserSetting, type UserStats, WINGET_PACKAGE_ID, type WorkItem, type WorkspaceConfig, type WorkspaceKind, type WorkspaceSourceControl, addPrerequisite, analyzeObservation, appendUiObservationReport, applySessionSynthesis, buildReviewQueue, buildUiSynthesisCandidates, cascadeBlock, clearADOCredentials, clearProviderApiKey, clearReviewContextCache, clearTursoCredentials, compareVersions, computeContentHash, confirmCardSplit, confirmFoundations, confirmSourceImport, cosineSimilarity, createAgentSkill, createFSRS, createGoal, createToken, decidePostCapture, decidePreCapture, decideUpdate, decodeEmbedding, deleteCardForUser, deleteSetting, deleteToken, deprecateToken, detectSyncProvider, detectSystemLocale, discoverSkills, distributeGlobalSkills, embeddingContentForToken, encodeEmbedding, endSession, ensureCard, ensureMonitorDir, ensureUiObserverDir, evaluateRating, executeReviewAction, exportSnapshot, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generateConceptFreeCue, generatePowerShellHooks, generatePowerShellUnhooks, generatePrompt, generateTokenSlug, generateZshHooks, generateZshUnhooks, getADOCredentials, getActiveWorkspace, getActiveWorkspaceId, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getCardById, getCardDeletionImpact, getConfiguredWorkspaces, getDatabaseTargetInfo, getDefaultDbPath, getDependents, getDomainCompetence, getDueCards, getEmbeddingCoverage, getGoal, getGoalTree, getInstallChannel, getInstallMode, getMachineAiConfig, getMonitorDir, getMonitorLogStats, getMonitorPath, getPackageSkillPath, getPrerequisites, getProviderApiKey, getRepoPaths, getReviewsForCard, getReviewsForUser, getSessionSummary, getSessionSynthesisRecords, getSetting, getSystemProfile, getTokenById, getTokenBySlug, getTokenDeleteImpact, getTokenEmbedding, getTokenNeighborhood, getTursoCredentials, getUiObservationPath, getUiObserverDir, getUserStats, hasCommand, importCurriculumCards, importSnapshot, injectShellHooks, installFastFlowLM, installOllama, installOpenCode, interleave, isObserverPolicyConfigured, isOllamaInstalled, isUiObservationReport, listAgentSkills, listEmbeddedTokens, listGoals, listPersonalCards, listProviderApiKeyRefs, listTokens, listTokensNeedingEmbedding, loadADOConfig, loadCredentials, loadInstallConfig, logReview, logStep, matchBuiltInSensitive, matchDenylist, matchesFilePath, monitorLogExists, normalizeLocale, normalizePath, openDatabase, openDatabaseWithSync, openRemoteDatabase, pairCommands, parseGoalFile, parseMonitorLog, parseObserverList, parseObserverPolicy, parseSnapshot, parseUiObservationLog, planOpenCodeInstall, planUpdate, prepareLocalModel, prepareSessionSynthesis, readMonitorLog, readUiObservationLog, removeConfiguredWorkspace, resolveAllBeliefPaths, resolveAllGoalPaths, resolveObserverPolicy, resolveOllamaCommand, resolveReference, resolveRepoPath, resolveReviewContext, saveConfiguredWorkspaces, saveCredentials, saveInstallConfig, saveMachineAiConfig, searchTokensHybrid, serializeGoal, setADOCredentials, setActiveWorkspaceId, setInstallChannel, setInstallMode, setProviderApiKey, setSetting, setTursoCredentials, slugify, startSession, syncObserverSidecarPolicy, t, toSidecarPrivacyPolicy, uiObservationLogExists, uiObservationTimeSpan, unblockReady, updateCard, updateGoalStatus, updateToken, upsertConfiguredWorkspace, upsertTokenEmbedding, verifySnapshot, wouldCreateCycle, writeMonitorEvent };
+export { type ADOConfig, type ADOCredentials, type AgentSkill, type AnalysisResult, type ApplySessionSynthesisInput, type ApplySessionSynthesisResult, BUILT_IN_SENSITIVE_MATCHERS, type BloomLevel$1 as BloomLevel, type CaptureDecision, type CaptureDenialReason, type CaptureRequest, type Card, type CardDeletionImpact, type CardState$1 as CardState, type CascadeBlockResult, type CommandRecord, type CommandSequence, type ConfirmFoundationsResult, type ConnectionOptions, type CreateAgentSkillInput, type CreateGoalInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type Credentials, type CurriculumCardInput, DEFAULT_OBSERVER_POLICY, DEFAULT_REVIEW_CONTEXT_MAX_CHARS, type Database, type DatabaseProvider, type DatabaseTargetInfo, type DatabaseValue, type DeleteCardResult, type DeleteTokenResult, type DiscoveryOptions, type DomainCompetence, type EmbeddedTokenRow, type EmbeddingCoverage, type EmbeddingStaleness, type EvaluateInput, type EvaluateResult, type ExecuteReviewActionInput, type ExecutionContext, type FSRSParameters, type FoundationProposalInput, type FoundationSuggestion, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, HOMEBREW_CASK, type HybridScoredToken, type HybridSearchOptions, type ImportCurriculumResult, type ImportResult, type InstallChannel, type InstallConfig, type InstallMode, type InstallPlan, type InstallResult, type ListTokensOptions, type LocalLLMRunner, type LogStepInput, type MachineAiConfig, type MachineProviderRecord, type MachineRoleBinding, type MonitorEvent, type Neighborhood, type NeighborhoodToken, OBSERVER_POLICY_UNSET_HINT, OBSERVER_POLICY_VERSION, type ObservationRating, type ObserverConsent, type ObserverPolicy, type ObserverRetention, type ObserverScope, type ObserverSettingKey, type OllamaDetectionOptions, type PersonalCard, type PrepareSessionSynthesisInput, type Prerequisite, type PrerequisiteWithToken, type PromptInput, REVIEW_CONTEXT_CACHE_TTL_MS, type Rating, type RecallPrompt, type RemoteDatabaseOptions, type RepoPaths, type ResolvedCaptureTarget, type ResolvedReference, type ReviewActionResult, type ReviewActionType, type ReviewContext, type ReviewLog, type ReviewQueue, type ReviewQueueItem, type ReviewQueueOptions, type RunResult, SIDECAR_POLICY_FILE, SNAPSHOT_VERSION, type SchedulingCard, type Session, type SessionStep, type SessionSummary, type SessionSynthesisCandidate, type SessionSynthesisEvidence, type SessionSynthesisPreview, type SessionSynthesisRecord, type SidecarPrivacyPolicy, type SkillProposal, type SkillSource, type SnapshotManifest, type SourceProposalInput, type SplitProposalInput, type Statement, type SuggestFoundationsOptions, type SupportedLocale, type SymbiosisMode, type SynthesisConfidence, type SystemProfile, type Token, type TokenDeleteImpact, type TokenEmbedding, type TokenNeedingEmbedding, type TokenPattern, type TranslationKey, type TursoCredentials, UI_OBSERVATION_PROTOCOL_VERSION, type UiActionType, type UiApplicationContext, type UiCandidateToken, type UiEvidenceRef, type UiEvidenceType, type UiObservationKind, type UiObservationReport, type UiObservedAction, type UnblockResult, type UpdateActionKind, type UpdateCardInput, type UpdateDecision, type UpdateStep, type UpdateStepKind, type UpdateTokenInput, type UserSetting, type UserStats, WINGET_PACKAGE_ID, type WorkItem, type WorkspaceConfig, type WorkspaceKind, type WorkspaceSourceControl, addPrerequisite, analyzeObservation, appendUiObservationReport, applySessionSynthesis, buildAncestorMap, buildReviewQueue, buildUiSynthesisCandidates, cascadeBlock, clearADOCredentials, clearProviderApiKey, clearReviewContextCache, clearTursoCredentials, compareVersions, computeContentHash, confirmCardSplit, confirmFoundations, confirmSourceImport, cosineSimilarity, createAgentSkill, createFSRS, createGoal, createToken, decidePostCapture, decidePreCapture, decideUpdate, decodeEmbedding, deleteCardForUser, deleteSetting, deleteToken, deprecateToken, detectSyncProvider, detectSystemLocale, discoverSkills, distributeGlobalSkills, embeddingContentForToken, encodeEmbedding, endSession, ensureCard, ensureMonitorDir, ensureUiObserverDir, evaluateRating, executeReviewAction, exportSnapshot, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generateConceptFreeCue, generatePowerShellHooks, generatePowerShellUnhooks, generatePrompt, generateTokenSlug, generateZshHooks, generateZshUnhooks, getADOCredentials, getActiveWorkspace, getActiveWorkspaceId, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getCardById, getCardDeletionImpact, getConfiguredWorkspaces, getDatabaseTargetInfo, getDefaultDbPath, getDependents, getDisplayTitle, getDomainCompetence, getDueCards, getEmbeddingCoverage, getGoal, getGoalTree, getInstallChannel, getInstallMode, getMachineAiConfig, getMonitorDir, getMonitorLogStats, getMonitorPath, getPackageSkillPath, getPrerequisites, getProviderApiKey, getRepoPaths, getReviewsForCard, getReviewsForUser, getSessionSummary, getSessionSynthesisRecords, getSetting, getShortSlug, getSystemProfile, getTokenById, getTokenBySlug, getTokenDeleteImpact, getTokenEmbedding, getTokenNeighborhood, getTursoCredentials, getUiObservationPath, getUiObserverDir, getUserStats, hasCommand, importCurriculumCards, importSnapshot, injectShellHooks, installFastFlowLM, installOllama, installOpenCode, interleave, isObserverPolicyConfigured, isOllamaInstalled, isUiObservationReport, listAgentSkills, listEmbeddedTokens, listGoals, listPersonalCards, listProviderApiKeyRefs, listTokens, listTokensNeedingEmbedding, loadADOConfig, loadCredentials, loadInstallConfig, logReview, logStep, matchBuiltInSensitive, matchDenylist, matchesFilePath, monitorLogExists, normalizeLocale, normalizePath, openDatabase, openDatabaseWithSync, openRemoteDatabase, pairCommands, parseGoalFile, parseMonitorLog, parseObserverList, parseObserverPolicy, parseSnapshot, parseUiObservationLog, planOpenCodeInstall, planUpdate, prepareLocalModel, prepareSessionSynthesis, readMonitorLog, readUiObservationLog, removeConfiguredWorkspace, resolveAllBeliefPaths, resolveAllGoalPaths, resolveObserverPolicy, resolveOllamaCommand, resolveReference, resolveRepoPath, resolveReviewContext, saveConfiguredWorkspaces, saveCredentials, saveInstallConfig, saveMachineAiConfig, searchTokensHybrid, serializeGoal, setADOCredentials, setActiveWorkspaceId, setInstallChannel, setInstallMode, setProviderApiKey, setSetting, setTursoCredentials, slugify, startSession, suggestFoundations, syncObserverSidecarPolicy, t, toSidecarPrivacyPolicy, uiObservationLogExists, uiObservationTimeSpan, unblockReady, updateCard, updateGoalStatus, updateToken, upsertConfiguredWorkspace, upsertTokenEmbedding, verifySnapshot, wouldCreateCycle, writeMonitorEvent };

package/dist/index.js

@@ -530,6 +530,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),
@@ -678,6 +679,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
@@ -1011,6 +1014,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
@@ -1512,12 +1524,14 @@ async function createToken(db, input) {
   if (bloom < 1 || bloom > 5) {
     throw new Error(`bloom_level must be between 1 and 5, got ${bloom}`);
   }
+  const title = input.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,
     input.slug,
+    title,
     input.concept,
     input.domain ?? "",
     bloom,
@@ -1560,6 +1574,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);
@@ -1665,13 +1683,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);
@@ -1685,10 +1704,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) {
@@ -1701,7 +1726,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) {
@@ -1735,6 +1760,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"
@@ -1746,7 +1776,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;
@@ -1776,6 +1819,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,
@@ -1877,6 +1921,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,
@@ -1994,23 +2039,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);
           }
         }
       }
@@ -2081,6 +2131,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,
@@ -2147,6 +2198,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,
@@ -2215,9 +2267,9 @@ async function buildAncestorMap(db) {
   }
   return map;
 }
-async function wouldCreateCycle(db, tokenId, requiresId) {
+async function wouldCreateCycle(db, tokenId, requiresId, ancestors) {
   if (tokenId === requiresId) return true;
-  const ancestors = await buildAncestorMap(db);
+  const map = ancestors ?? await buildAncestorMap(db);
   const visited = /* @__PURE__ */ new Set();
   const queue = [requiresId];
   while (queue.length > 0) {
@@ -2225,7 +2277,7 @@ async function wouldCreateCycle(db, tokenId, requiresId) {
     if (current === tokenId) return true;
     if (visited.has(current)) continue;
     visited.add(current);
-    const parents = ancestors.get(current);
+    const parents = map.get(current);
     if (parents) {
       for (const parent of parents) {
         if (!visited.has(parent)) queue.push(parent);
@@ -2249,7 +2301,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 = ?`
@@ -2257,7 +2309,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 = ?`
@@ -2288,6 +2340,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,
@@ -2307,6 +2360,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
@@ -2319,6 +2373,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
@@ -2478,7 +2533,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");
@@ -4662,6 +4718,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,
@@ -4683,6 +4740,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,
@@ -4742,6 +4800,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,
@@ -4850,6 +4909,71 @@ async function searchTokensHybrid(db, query, opts) {
   return results.slice(0, limit);
 }
 
+// src/kernel/search/suggestions.ts
+async function suggestFoundations(db, opts) {
+  const minSimilarity = opts.minSimilarity ?? 0.45;
+  const maxSimilarity = opts.maxSimilarity ?? 0.85;
+  const limit = opts.limit ?? 5;
+  const targetBloomLevel = opts.targetBloomLevel ?? 5;
+  if (minSimilarity >= maxSimilarity) {
+    return [];
+  }
+  const embedded = await listEmbeddedTokens(db, opts.model);
+  if (embedded.length === 0) {
+    return [];
+  }
+  const queryVec = Float32Array.from(opts.queryEmbedding);
+  const candidates = [];
+  for (const row of embedded) {
+    if (opts.targetTokenId && row.token.id === opts.targetTokenId) {
+      continue;
+    }
+    const similarity = cosineSimilarity(queryVec, row.embedding);
+    if (similarity >= minSimilarity && similarity < maxSimilarity) {
+      candidates.push({ token: row.token, similarity });
+    }
+  }
+  candidates.sort((a, b) => {
+    if (Math.abs(a.similarity - b.similarity) > 1e-9) {
+      return b.similarity - a.similarity;
+    }
+    return a.token.slug.localeCompare(b.token.slug);
+  });
+  const topCandidates = candidates.slice(0, limit);
+  const prereqIds = /* @__PURE__ */ new Set();
+  let ancestors;
+  if (opts.targetTokenId) {
+    const prereqs = await getPrerequisites(db, opts.targetTokenId);
+    for (const p of prereqs) {
+      prereqIds.add(p.requires_id);
+    }
+    ancestors = await buildAncestorMap(db);
+  }
+  const results = [];
+  for (const cand of topCandidates) {
+    let alreadyPrerequisite = false;
+    let wouldCreateCycleFlag = false;
+    const bloomAboveTarget = cand.token.bloom_level > targetBloomLevel;
+    if (opts.targetTokenId) {
+      alreadyPrerequisite = prereqIds.has(cand.token.id);
+      wouldCreateCycleFlag = await wouldCreateCycle(
+        db,
+        opts.targetTokenId,
+        cand.token.id,
+        ancestors
+      );
+    }
+    results.push({
+      token: cand.token,
+      similarity: cand.similarity,
+      alreadyPrerequisite,
+      wouldCreateCycle: wouldCreateCycleFlag,
+      bloomAboveTarget
+    });
+  }
+  return results;
+}
+
 // src/kernel/system/hooks.ts
 import {
   appendFileSync as appendFileSync3,
@@ -5874,6 +5998,7 @@ export {
   analyzeObservation,
   appendUiObservationReport,
   applySessionSynthesis,
+  buildAncestorMap,
   buildReviewQueue,
   buildUiSynthesisCandidates,
   cascadeBlock,
@@ -5939,6 +6064,7 @@ export {
   getDatabaseTargetInfo,
   getDefaultDbPath,
   getDependents,
+  getDisplayTitle,
   getDomainCompetence,
   getDueCards,
   getEmbeddingCoverage,
@@ -5959,6 +6085,7 @@ export {
   getSessionSummary,
   getSessionSynthesisRecords,
   getSetting,
+  getShortSlug,
   getSystemProfile,
   getTokenById,
   getTokenBySlug,
@@ -6037,6 +6164,7 @@ export {
   setTursoCredentials,
   slugify,
   startSession,
+  suggestFoundations,
   syncObserverSidecarPolicy,
   t,
   toSidecarPrivacyPolicy,