@soleri/core 2.4.0 → 2.5.0

package/src/runtime/project-ops.ts

@@ -91,7 +91,9 @@ export function createProjectOps(runtime: AgentRuntime): OpDefinition[] {
       auth: 'write',
       schema: z.object({
         projectId: z.string().describe('Project ID to add the rule to'),
-        category: z.enum(['behavior', 'preference', 'restriction', 'convention']).describe('Rule category'),
+        category: z
+          .enum(['behavior', 'preference', 'restriction', 'convention'])
+          .describe('Rule category'),
         text: z.string().describe('Rule text'),
         priority: z.number().default(0).describe('Priority (higher = more important)'),
       }),
@@ -143,7 +145,10 @@ export function createProjectOps(runtime: AgentRuntime): OpDefinition[] {
       schema: z.object({
         sourceId: z.string().describe('Source project ID'),
         targetId: z.string().describe('Target project ID'),
-        linkType: z.enum(['related', 'parent', 'child', 'fork']).optional().describe('Specific link type to remove'),
+        linkType: z
+          .enum(['related', 'parent', 'child', 'fork'])
+          .optional()
+          .describe('Specific link type to remove'),
       }),
       handler: async (params) => {
         const count = projectRegistry.unlink(
@@ -168,7 +173,8 @@ export function createProjectOps(runtime: AgentRuntime): OpDefinition[] {
     },
     {
       name: 'project_linked_projects',
-      description: 'Get linked projects with full details — project info, link type, and direction.',
+      description:
+        'Get linked projects with full details — project info, link type, and direction.',
       auth: 'read',
       schema: z.object({
         projectId: z.string().describe('Project ID'),

package/src/runtime/runtime.ts

@@ -22,8 +22,12 @@ import { IntentRouter } from '../control/intent-router.js';
 import { KeyPool, loadKeyPoolConfig } from '../llm/key-pool.js';
 import { loadIntelligenceData } from '../intelligence/loader.js';
 import { LLMClient } from '../llm/llm-client.js';
+import { CogneeSyncManager } from '../cognee/sync-manager.js';
+import { IntakePipeline } from '../intake/intake-pipeline.js';
 import { Telemetry } from '../telemetry/telemetry.js';
 import { ProjectRegistry } from '../project/project-registry.js';
+import { TemplateManager } from '../prompts/template-manager.js';
+import { existsSync } from 'node:fs';
 import { createLogger } from '../logging/logger.js';
 import type { AgentRuntimeConfig, AgentRuntime } from './types.js';
 
@@ -58,25 +62,25 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   // Planner — multi-step task tracking
   const planner = new Planner(plansPath);
 
+  // Cognee — vector search client (graceful degradation if Cognee is down)
+  const cogneePartial: Partial<import('../cognee/types.js').CogneeConfig> = { dataset: agentId };
+  if (process.env.COGNEE_BASE_URL) cogneePartial.baseUrl = process.env.COGNEE_BASE_URL;
+  if (process.env.COGNEE_API_TOKEN) cogneePartial.apiToken = process.env.COGNEE_API_TOKEN;
+  if (process.env.COGNEE_DATASET) cogneePartial.dataset = process.env.COGNEE_DATASET;
+  const cognee = new CogneeClient(cogneePartial);
+
   // Brain — intelligence layer (TF-IDF scoring, auto-tagging, dedup)
-  const brain = new Brain(vault);
+  const brain = new Brain(vault, cognee);
 
   // Brain Intelligence — pattern strengths, session knowledge, intelligence pipeline
   const brainIntelligence = new BrainIntelligence(vault, brain);
 
   // Curator — vault self-maintenance (dedup, contradictions, grooming, health)
-  const curator = new Curator(vault);
+  const curator = new Curator(vault, cognee);
 
   // Governance — policy engine + proposal tracker for gated knowledge capture
   const governance = new Governance(vault);
 
-  // Cognee — vector search client (graceful degradation if Cognee is down)
-  const cogneePartial: Partial<import('../cognee/types.js').CogneeConfig> = { dataset: agentId };
-  if (process.env.COGNEE_BASE_URL) cogneePartial.baseUrl = process.env.COGNEE_BASE_URL;
-  if (process.env.COGNEE_API_TOKEN) cogneePartial.apiToken = process.env.COGNEE_API_TOKEN;
-  if (process.env.COGNEE_DATASET) cogneePartial.dataset = process.env.COGNEE_DATASET;
-  const cognee = new CogneeClient(cogneePartial);
-
   // Loop Manager — iterative validation loop tracking (in-memory, session-scoped)
   const loop = new LoopManager();
 
@@ -92,12 +96,30 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   // Project Registry — multi-project tracking with rules and links
   const projectRegistry = new ProjectRegistry(vault.getDb());
 
+  // Template Manager — prompt templates with variable substitution
+  const templatesDir = config.templatesDir ?? join(agentHome, 'templates');
+  const templateManager = new TemplateManager(templatesDir);
+  if (existsSync(templatesDir)) {
+    templateManager.load();
+  }
+
   // LLM key pools and client
   const keyPoolFiles = loadKeyPoolConfig(agentId);
   const openaiKeyPool = new KeyPool(keyPoolFiles.openai);
   const anthropicKeyPool = new KeyPool(keyPoolFiles.anthropic);
   const llmClient = new LLMClient(openaiKeyPool, anthropicKeyPool, agentId);
 
+  // Cognee Sync Manager — queue-based dirty tracking with offline resilience
+  const syncManager = new CogneeSyncManager(
+    vault.getProvider(),
+    cognee,
+    cogneePartial.dataset ?? agentId,
+  );
+  vault.setSyncManager(syncManager);
+
+  // Intake Pipeline — PDF/book ingestion with LLM classification
+  const intakePipeline = new IntakePipeline(vault.getProvider(), vault, llmClient);
+
   return {
     config,
     logger,
@@ -115,8 +137,12 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     llmClient,
     telemetry,
     projectRegistry,
+    templateManager,
+    syncManager,
+    intakePipeline,
     createdAt: Date.now(),
     close: () => {
+      syncManager.close();
       cognee.resetPendingCognify();
       vault.close();
     },

package/src/runtime/types.ts

@@ -12,6 +12,9 @@ import type { IntentRouter } from '../control/intent-router.js';
 import type { LoopManager } from '../loop/loop-manager.js';
 import type { Telemetry } from '../telemetry/telemetry.js';
 import type { ProjectRegistry } from '../project/project-registry.js';
+import type { TemplateManager } from '../prompts/template-manager.js';
+import type { CogneeSyncManager } from '../cognee/sync-manager.js';
+import type { IntakePipeline } from '../intake/intake-pipeline.js';
 import type { Logger } from '../logging/logger.js';
 import type { LogLevel } from '../logging/types.js';
 
@@ -28,6 +31,8 @@ export interface AgentRuntimeConfig {
   plansPath?: string;
   /** Intelligence data directory to seed vault from. Optional. */
   dataDir?: string;
+  /** Path to prompt templates directory. Default: ~/.{agentId}/templates */
+  templatesDir?: string;
   /** Minimum log level. Default: 'info' (or SOLERI_LOG_LEVEL env var). */
   logLevel?: LogLevel;
 }
@@ -53,6 +58,9 @@ export interface AgentRuntime {
   llmClient: LLMClient;
   telemetry: Telemetry;
   projectRegistry: ProjectRegistry;
+  templateManager: TemplateManager;
+  syncManager: CogneeSyncManager;
+  intakePipeline: IntakePipeline;
   /** Timestamp (ms since epoch) when this runtime was created. */
   createdAt: number;
   /** Close the vault database connection. Call on shutdown. */

package/src/runtime/vault-extra-ops.ts

@@ -1,17 +1,20 @@
 /**
- * Extra vault operations — 12 ops that extend the 4 base vault ops in core-ops.ts.
+ * Extra vault operations — 20 ops that extend the 4 base vault ops in core-ops.ts.
  *
- * Groups: single-entry CRUD (3), bulk (2), discovery (3), import/export (3), analytics (1).
+ * Groups: single-entry CRUD (3), bulk (2), discovery (3), import/export (3),
+ *         analytics (1), seed canonical (1), knowledge lifecycle (4), temporal (3).
  */
 
 import { z } from 'zod';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
 import type { OpDefinition } from '../facades/types.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 import type { AgentRuntime } from './types.js';
 
 const entrySchema = z.object({
   id: z.string(),
-  type: z.enum(['pattern', 'anti-pattern', 'rule']),
+  type: z.enum(['pattern', 'anti-pattern', 'rule', 'playbook']),
   domain: z.string(),
   title: z.string(),
   severity: z.enum(['critical', 'warning', 'suggestion']),
@@ -56,7 +59,7 @@ export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
         tags: z.array(z.string()).optional(),
         appliesTo: z.array(z.string()).optional(),
         severity: z.enum(['critical', 'warning', 'suggestion']).optional(),
-        type: z.enum(['pattern', 'anti-pattern', 'rule']).optional(),
+        type: z.enum(['pattern', 'anti-pattern', 'rule', 'playbook']).optional(),
         domain: z.string().optional(),
       }),
       handler: async (params) => {
@@ -221,5 +224,383 @@ export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
         return vault.getAgeReport();
       },
     },
+
+    // ─── Seed Canonical (#153) ───────────────────────────────────
+    {
+      name: 'vault_seed_canonical',
+      description:
+        'Seed vault knowledge from structured markdown files with YAML frontmatter. ' +
+        'Reads .md files from a directory, parses them into IntelligenceEntry objects, and upserts. Idempotent.',
+      auth: 'write',
+      schema: z.object({
+        directory: z
+          .string()
+          .describe('Path to directory containing .md files with YAML frontmatter'),
+        domain: z
+          .string()
+          .optional()
+          .describe('Override domain for all entries (default: from frontmatter or filename)'),
+      }),
+      handler: async (params) => {
+        try {
+          const dir = params.directory as string;
+          const domainOverride = params.domain as string | undefined;
+
+          if (!existsSync(dir)) {
+            return { error: `Directory not found: ${dir}` };
+          }
+
+          const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+          const entries: IntelligenceEntry[] = [];
+          const errors: Array<{ file: string; error: string }> = [];
+
+          for (const file of files) {
+            try {
+              const content = readFileSync(join(dir, file), 'utf-8');
+              const entry = parseMarkdownEntry(content, file, domainOverride);
+              if (entry) entries.push(entry);
+            } catch (err) {
+              errors.push({ file, error: (err as Error).message });
+            }
+          }
+
+          const seeded = entries.length > 0 ? vault.seed(entries) : 0;
+
+          return {
+            seeded,
+            filesProcessed: files.length,
+            errors: errors.length > 0 ? errors : undefined,
+            total: vault.stats().totalEntries,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Knowledge Audit (#155) ──────────────────────────────────
+    {
+      name: 'knowledge_audit',
+      description:
+        'Audit vault quality — coverage gaps, stale entries, tag health, and recommendations.',
+      auth: 'read',
+      handler: async () => {
+        try {
+          const stats = vault.stats();
+          const tags = vault.getTags();
+          const domains = vault.getDomains();
+          const ageReport = vault.getAgeReport();
+
+          // Check coverage
+          const entriesWithoutTags = tags.length === 0 ? stats.totalEntries : 0;
+          const singletonTags = tags.filter((t) => t.count === 1).length;
+
+          // Staleness: entries older than 90 days
+          const staleCount = ageReport.buckets.find((b) => b.label === 'older')?.count ?? 0;
+
+          const recommendations: string[] = [];
+          if (stats.totalEntries < 10)
+            recommendations.push('Vault has few entries — capture more knowledge');
+          if (singletonTags > tags.length * 0.5)
+            recommendations.push('Many singleton tags — consolidate tagging');
+          if (staleCount > stats.totalEntries * 0.3)
+            recommendations.push('>30% entries are stale — review and update');
+          if (domains.length === 1)
+            recommendations.push('Only one domain — consider categorizing by domain');
+
+          return {
+            totalEntries: stats.totalEntries,
+            domainCount: domains.length,
+            tagCount: tags.length,
+            singletonTags,
+            staleEntries: staleCount,
+            entriesWithoutTags,
+            recommendations,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Knowledge Health (#155) ─────────────────────────────────
+    {
+      name: 'knowledge_health',
+      description:
+        'Knowledge base health metrics — entry counts, freshness, staleness, contradiction signals.',
+      auth: 'read',
+      handler: async () => {
+        try {
+          const stats = vault.stats();
+          const ageReport = vault.getAgeReport();
+          const domains = vault.getDomains();
+          const tags = vault.getTags();
+
+          // Detect potential contradictions: entries with same tags but different types (pattern vs anti-pattern)
+          const db = vault.getDb();
+          const contradictionSignals = db
+            .prepare(
+              `SELECT t.value as tag, COUNT(DISTINCT e.type) as type_count
+               FROM entries e, json_each(e.tags) t
+               GROUP BY t.value HAVING type_count > 1 LIMIT 10`,
+            )
+            .all() as Array<{ tag: string; type_count: number }>;
+
+          return {
+            totalEntries: stats.totalEntries,
+            freshEntries:
+              (ageReport.buckets.find((b) => b.label === 'today')?.count ?? 0) +
+              (ageReport.buckets.find((b) => b.label === 'this_week')?.count ?? 0),
+            staleEntries: ageReport.buckets.find((b) => b.label === 'older')?.count ?? 0,
+            domainCount: domains.length,
+            tagCount: tags.length,
+            contradictionSignals: contradictionSignals.length,
+            contradictionTags: contradictionSignals.map((c) => c.tag),
+            oldestTimestamp: ageReport.oldestTimestamp,
+            newestTimestamp: ageReport.newestTimestamp,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Merge Patterns (#155) ───────────────────────────────────
+    {
+      name: 'knowledge_merge',
+      description:
+        'Merge two similar patterns into one — keeps the best metadata from both, removes the duplicate.',
+      auth: 'write',
+      schema: z.object({
+        keepId: z.string().describe('ID of the entry to keep (will receive merged data)'),
+        removeId: z.string().describe('ID of the duplicate entry to remove after merge'),
+      }),
+      handler: async (params) => {
+        try {
+          const keep = vault.get(params.keepId as string);
+          const remove = vault.get(params.removeId as string);
+          if (!keep) return { error: `Entry not found: ${params.keepId}` };
+          if (!remove) return { error: `Entry not found: ${params.removeId}` };
+
+          // Merge tags (deduplicated union)
+          const mergedTags = [...new Set([...(keep.tags ?? []), ...(remove.tags ?? [])])];
+
+          // Merge fields — prefer non-empty from either side
+          const updates: Partial<IntelligenceEntry> = {
+            tags: mergedTags,
+            description: keep.description || remove.description,
+            context: keep.context || remove.context,
+            example: keep.example || remove.example,
+            counterExample: keep.counterExample || remove.counterExample,
+            why: keep.why || remove.why,
+            appliesTo: keep.appliesTo?.length ? keep.appliesTo : remove.appliesTo,
+          };
+
+          vault.update(keep.id, updates);
+          vault.remove(remove.id);
+
+          return {
+            merged: true,
+            keptId: keep.id,
+            removedId: remove.id,
+            mergedTags,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Knowledge Reorganize (#155) ─────────────────────────────
+    {
+      name: 'knowledge_reorganize',
+      description:
+        'Re-categorize vault entries — reassign domains, clean up tags, deduplicate. Dry-run by default.',
+      auth: 'write',
+      schema: z.object({
+        dryRun: z
+          .boolean()
+          .optional()
+          .describe('If true, only report what would change (default true)'),
+        retagRules: z
+          .array(
+            z.object({
+              from: z.string().describe('Tag to rename/remove'),
+              to: z.string().optional().describe('New tag (omit to remove the tag)'),
+            }),
+          )
+          .optional()
+          .describe('Tag rename/removal rules'),
+        domainRules: z
+          .array(
+            z.object({
+              from: z.string().describe('Old domain name'),
+              to: z.string().describe('New domain name'),
+            }),
+          )
+          .optional()
+          .describe('Domain rename rules'),
+      }),
+      handler: async (params) => {
+        try {
+          const dryRun = (params.dryRun as boolean | undefined) ?? true;
+          const retagRules = (params.retagRules as Array<{ from: string; to?: string }>) ?? [];
+          const domainRules = (params.domainRules as Array<{ from: string; to: string }>) ?? [];
+          const changes: Array<{ id: string; field: string; from: string; to: string }> = [];
+
+          const allEntries = vault.list({});
+
+          for (const entry of allEntries) {
+            // Apply domain rules
+            for (const rule of domainRules) {
+              if (entry.domain === rule.from) {
+                changes.push({ id: entry.id, field: 'domain', from: rule.from, to: rule.to });
+                if (!dryRun) vault.update(entry.id, { domain: rule.to });
+              }
+            }
+
+            // Apply retag rules
+            if (entry.tags) {
+              let tagsChanged = false;
+              const newTags = [...entry.tags];
+              for (const rule of retagRules) {
+                const idx = newTags.indexOf(rule.from);
+                if (idx !== -1) {
+                  if (rule.to) {
+                    changes.push({ id: entry.id, field: 'tag', from: rule.from, to: rule.to });
+                    newTags[idx] = rule.to;
+                  } else {
+                    changes.push({ id: entry.id, field: 'tag', from: rule.from, to: '(removed)' });
+                    newTags.splice(idx, 1);
+                  }
+                  tagsChanged = true;
+                }
+              }
+              if (tagsChanged && !dryRun) {
+                vault.update(entry.id, { tags: [...new Set(newTags)] });
+              }
+            }
+          }
+
+          return {
+            dryRun,
+            changesFound: changes.length,
+            changes: changes.slice(0, 100), // cap output
+            entriesScanned: allEntries.length,
+          };
+        } catch (err) {
+          return { error: (err as Error).message };
+        }
+      },
+    },
+
+    // ─── Temporal (#89) ──────────────────────────────────────────────
+    {
+      name: 'vault_set_temporal',
+      description:
+        'Set valid_from and/or valid_until timestamps on a vault entry for bi-temporal validity windows.',
+      auth: 'write',
+      schema: z.object({
+        id: z.string().describe('Entry ID'),
+        validFrom: z.number().optional().describe('Unix epoch — when entry becomes active'),
+        validUntil: z.number().optional().describe('Unix epoch — when entry expires'),
+      }),
+      handler: async (params) => {
+        const updated = vault.setTemporal(
+          params.id as string,
+          params.validFrom as number | undefined,
+          params.validUntil as number | undefined,
+        );
+        if (!updated) return { error: 'Entry not found or no fields to update' };
+        const entry = vault.get(params.id as string);
+        return {
+          updated: true,
+          id: params.id,
+          validFrom: entry?.validFrom ?? null,
+          validUntil: entry?.validUntil ?? null,
+        };
+      },
+    },
+    {
+      name: 'vault_find_expiring',
+      description:
+        'Find vault entries expiring within a given number of days. Useful for proactive knowledge maintenance.',
+      auth: 'read',
+      schema: z.object({
+        withinDays: z.number().describe('Number of days to look ahead'),
+      }),
+      handler: async (params) => {
+        const entries = vault.findExpiring(params.withinDays as number);
+        return { entries, count: entries.length };
+      },
+    },
+    {
+      name: 'vault_find_expired',
+      description: 'List expired vault entries (valid_until in the past). Useful for cleanup.',
+      auth: 'read',
+      schema: z.object({
+        limit: z.number().optional().describe('Max results (default 50)'),
+      }),
+      handler: async (params) => {
+        const entries = vault.findExpired((params.limit as number | undefined) ?? 50);
+        return { entries, count: entries.length };
+      },
+    },
   ];
 }
+
+/**
+ * Parse a markdown file with YAML frontmatter into an IntelligenceEntry.
+ * Expected frontmatter fields: id, type, domain, severity, title, tags.
+ */
+function parseMarkdownEntry(
+  content: string,
+  filename: string,
+  domainOverride?: string,
+): IntelligenceEntry | null {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return null;
+
+  const frontmatter = match[1];
+  const body = match[2].trim();
+
+  // Simple YAML parser for flat key-value pairs
+  const meta: Record<string, string | string[]> = {};
+  for (const line of frontmatter.split('\n')) {
+    const kvMatch = line.match(/^(\w+):\s*(.+)$/);
+    if (kvMatch) {
+      const key = kvMatch[1];
+      let value = kvMatch[2].trim();
+      // Handle quoted strings
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+      // Handle arrays: [a, b, c]
+      if (value.startsWith('[') && value.endsWith(']')) {
+        meta[key] = value
+          .slice(1, -1)
+          .split(',')
+          .map((s) => s.trim().replace(/^["']|["']$/g, ''));
+      } else {
+        meta[key] = value;
+      }
+    }
+  }
+
+  const id = (meta.id as string) || basename(filename, '.md');
+  const tags = Array.isArray(meta.tags) ? meta.tags : meta.tags ? [meta.tags as string] : [];
+
+  return {
+    id,
+    type: (meta.type as IntelligenceEntry['type']) || 'pattern',
+    domain: domainOverride || (meta.domain as string) || 'general',
+    title: (meta.title as string) || basename(filename, '.md'),
+    severity: (meta.severity as IntelligenceEntry['severity']) || 'suggestion',
+    description: body || (meta.description as string) || '',
+    context: meta.context as string | undefined,
+    tags,
+  };
+}

package/src/vault/playbook.ts

@@ -0,0 +1,87 @@
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+export interface PlaybookStep {
+  order: number;
+  title: string;
+  description: string;
+  validation?: string;
+}
+
+export interface Playbook {
+  id: string;
+  title: string;
+  domain: string;
+  description: string;
+  steps: PlaybookStep[];
+  tags: string[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PlaybookValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate a playbook's structure.
+ * Checks: title non-empty, steps.length > 0, each step has order/title/description,
+ * orders are sequential starting from 1.
+ */
+export function validatePlaybook(playbook: Playbook): PlaybookValidationResult {
+  const errors: string[] = [];
+
+  if (!playbook.title || playbook.title.trim() === '') {
+    errors.push('Playbook title must not be empty');
+  }
+
+  if (!playbook.steps || playbook.steps.length === 0) {
+    errors.push('Playbook must have at least one step');
+  } else {
+    for (let i = 0; i < playbook.steps.length; i++) {
+      const step = playbook.steps[i];
+      const expectedOrder = i + 1;
+
+      if (step.order !== expectedOrder) {
+        errors.push(`Step ${i + 1} has order ${step.order}, expected ${expectedOrder}`);
+      }
+      if (!step.title || step.title.trim() === '') {
+        errors.push(`Step ${expectedOrder} title must not be empty`);
+      }
+      if (!step.description || step.description.trim() === '') {
+        errors.push(`Step ${expectedOrder} description must not be empty`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Parse a Playbook from a vault IntelligenceEntry.
+ * Returns null if the entry is not a playbook type or if the context is not valid
+ * JSON with a steps array.
+ */
+export function parsePlaybookFromEntry(entry: IntelligenceEntry): Playbook | null {
+  if (entry.type !== 'playbook') return null;
+
+  let steps: PlaybookStep[];
+  try {
+    const parsed = JSON.parse(entry.context ?? '');
+    if (!Array.isArray(parsed?.steps)) return null;
+    steps = parsed.steps;
+  } catch {
+    return null;
+  }
+
+  return {
+    id: entry.id,
+    title: entry.title,
+    domain: entry.domain,
+    description: entry.description,
+    steps,
+    tags: entry.tags,
+    createdAt: 0, // not available from entry directly
+    updatedAt: 0,
+  };
+}