@datacore-one/mcp 1.0.2 → 1.1.1

package/dist/index.js

@@ -68,11 +68,115 @@ function initCore(basePath) {
   }
   const configPath = path.join(basePath, "config.yaml");
   if (!fs.existsSync(configPath)) {
-    fs.writeFileSync(configPath, "# Datacore MCP configuration\nversion: 1\n");
+    fs.writeFileSync(configPath, "# Datacore MCP configuration\nversion: 2\n# engrams:\n#   auto_promote: false\n# packs:\n#   trusted_publishers: []\n# search:\n#   max_results: 20\n#   snippet_length: 500\n# hints:\n#   enabled: true\n");
   }
+  generateContextFiles(basePath);
   copyStarterPacks(basePath);
   return { isFirstRun: isFirstRun2 };
 }
+function generateContextFiles(basePath) {
+  const files = [
+    { rel: "CLAUDE.md", content: CONTEXT_CLAUDE },
+    { rel: "AGENTS.md", content: CONTEXT_AGENTS },
+    { rel: ".cursorrules", content: CONTEXT_CURSORRULES },
+    { rel: ".github/copilot-instructions.md", content: CONTEXT_COPILOT }
+  ];
+  for (const { rel, content } of files) {
+    const filePath = path.join(basePath, rel);
+    if (!fs.existsSync(filePath)) {
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, content);
+    }
+  }
+}
+var DATACORE_GUIDE = `Datacore gives AI assistants persistent memory through **engrams** \u2014 typed knowledge units
+that get injected into context when relevant.
+
+## Session Workflow
+
+1. **datacore.session.start** \u2014 Call this first. Gets relevant engrams + today's journal.
+2. Work on the task. Use **datacore.recall** to search everything.
+3. **datacore.feedback** \u2014 Rate which injected engrams were helpful.
+4. **datacore.session.end** \u2014 Capture summary + suggest new engrams.
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| session.start | Start here. Begin session with context injection. |
+| session.end | End session, capture journal + new engrams. |
+| learn | Record a reusable insight (creates candidate engram). |
+| promote | Activate candidate engrams. |
+| inject | Get relevant engrams for a specific task. |
+| recall | Search all sources (engrams + journal + knowledge). |
+| capture | Write a journal entry or knowledge note. |
+| search | Search journal and knowledge files. |
+| ingest | Import text and extract engram suggestions. |
+| feedback | Rate engrams: positive/negative/neutral. |
+| forget | Retire an engram permanently. |
+| status | System health + recommendations. |
+| packs.discover | Browse available engram packs. |
+| packs.install | Install a pack. |
+| packs.export | Export your engrams as a pack. |
+
+## Engram Lifecycle
+
+learn \u2192 candidate \u2192 promote \u2192 active \u2192 inject \u2192 feedback \u2192 stronger/weaker \u2192 forget (retire)
+
+- **candidate**: Created but not yet active. Won't appear in inject results.
+- **active**: Appears in inject results when relevant to the task.
+- **retired**: Permanently removed from injection.
+
+Positive feedback strengthens retrieval. Unused engrams naturally decay over time.
+
+## Data Storage
+
+All data is in this directory as plain text files:
+- \`engrams.yaml\` \u2014 Your learned knowledge
+- \`journal/\` \u2014 Daily session logs (YYYY-MM-DD.md)
+- \`knowledge/\` \u2014 Ingested reference material
+- \`packs/\` \u2014 Installed engram packs
+- \`config.yaml\` \u2014 Configuration (all fields optional)
+`;
+var CONTEXT_CLAUDE = `# Datacore
+
+This is a Datacore installation \u2014 persistent memory for AI assistants.
+
+${DATACORE_GUIDE}
+
+## MCP Tools
+
+All tools are prefixed with \`datacore.\` (e.g., \`datacore.session.start\`).
+Call \`datacore.session.start\` at the beginning of every conversation.
+`;
+var CONTEXT_AGENTS = `# AGENTS.md
+
+This directory is managed by [Datacore](https://github.com/datacore-one/mcp) \u2014 persistent memory for AI assistants.
+
+${DATACORE_GUIDE}
+
+## For AI Agents
+
+All tools are available via MCP under the \`datacore.\` namespace.
+Start every session by calling \`datacore.session.start\`.
+`;
+var CONTEXT_CURSORRULES = `# Datacore
+
+This directory is managed by Datacore \u2014 persistent memory for AI assistants.
+All tools are available via MCP under the \`datacore.\` namespace.
+
+${DATACORE_GUIDE}`;
+var CONTEXT_COPILOT = `# Datacore
+
+This directory is managed by [Datacore](https://github.com/datacore-one/mcp) \u2014 persistent memory for AI assistants.
+
+${DATACORE_GUIDE}
+
+## MCP Integration
+
+All tools are available via MCP under the \`datacore.\` namespace.
+Start every session by calling \`datacore.session.start\`.
+`;
 function copyStarterPacks(basePath) {
   const packsDir = path.join(basePath, "packs");
   const bundledPacksDir = path.join(
@@ -90,10 +194,50 @@ function copyStarterPacks(basePath) {
   }
 }
 
+// src/config.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import * as yaml from "js-yaml";
+import { z } from "zod";
+var ConfigSchema = z.object({
+  version: z.number().default(2),
+  engrams: z.object({
+    auto_promote: z.boolean().default(false)
+  }).default({}),
+  packs: z.object({
+    trusted_publishers: z.array(z.string()).default([])
+  }).default({}),
+  search: z.object({
+    max_results: z.number().default(20),
+    snippet_length: z.number().default(500)
+  }).default({}),
+  hints: z.object({
+    enabled: z.boolean().default(true)
+  }).default({})
+});
+var cachedConfig = null;
+function loadConfig(basePath, mode) {
+  const configPath = mode === "full" ? path2.join(basePath, ".datacore", "config.yaml") : path2.join(basePath, "config.yaml");
+  let raw = {};
+  if (fs2.existsSync(configPath)) {
+    try {
+      raw = yaml.load(fs2.readFileSync(configPath, "utf8")) ?? {};
+    } catch {
+      raw = {};
+    }
+  }
+  cachedConfig = ConfigSchema.parse(raw);
+  return cachedConfig;
+}
+function getConfig() {
+  if (!cachedConfig) return ConfigSchema.parse({});
+  return cachedConfig;
+}
+
 // package.json
 var package_default = {
   name: "@datacore-one/mcp",
-  version: "1.0.2",
+  version: "1.1.1",
   description: "Datacore MCP server \u2014 The Software of You",
   type: "module",
   bin: {
@@ -159,132 +303,177 @@ async function checkForUpdate() {
 }
 
 // src/tools/index.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 var TOOLS = [
   {
     name: "datacore.capture",
     description: "Capture a journal entry or knowledge note",
-    inputSchema: z.object({
-      type: z.enum(["journal", "knowledge"]),
-      content: z.string().describe("Content to capture"),
-      title: z.string().optional().describe("Title for knowledge notes"),
-      tags: z.array(z.string()).optional().describe("Tags to attach")
+    inputSchema: z2.object({
+      type: z2.enum(["journal", "knowledge"]),
+      content: z2.string().describe("Content to capture"),
+      title: z2.string().optional().describe("Title for knowledge notes"),
+      tags: z2.array(z2.string()).optional().describe("Tags to attach")
     })
   },
   {
     name: "datacore.learn",
     description: "Create an engram from a statement \u2014 record a reusable learning",
-    inputSchema: z.object({
-      statement: z.string().describe("The knowledge assertion"),
-      type: z.enum(["behavioral", "terminological", "procedural", "architectural"]).optional(),
-      scope: z.string().optional().describe("Scope: global | agent:X | command:X"),
-      tags: z.array(z.string()).optional(),
-      domain: z.string().optional().describe("Dot-notation domain: software.architecture"),
-      visibility: z.enum(["private", "public", "template"]).optional()
+    inputSchema: z2.object({
+      statement: z2.string().describe("The knowledge assertion"),
+      type: z2.enum(["behavioral", "terminological", "procedural", "architectural"]).optional(),
+      scope: z2.string().optional().describe("Scope: global | agent:X | command:X"),
+      tags: z2.array(z2.string()).optional(),
+      domain: z2.string().optional().describe("Dot-notation domain: software.architecture"),
+      visibility: z2.enum(["private", "public", "template"]).optional()
     })
   },
   {
     name: "datacore.inject",
     description: "Get relevant engrams for a task \u2014 returns directives and considerations",
-    inputSchema: z.object({
-      prompt: z.string().describe("The task or question to match against"),
-      scope: z.string().optional().describe("Filter by scope: global | agent:X | module:X | command:X"),
-      max_tokens: z.number().optional().describe("Token budget (default: 8000)"),
-      min_relevance: z.number().optional().describe("Minimum score threshold (default: 0.3)")
+    inputSchema: z2.object({
+      prompt: z2.string().describe("The task or question to match against"),
+      scope: z2.string().optional().describe("Filter by scope: global | agent:X | module:X | command:X"),
+      max_tokens: z2.number().optional().describe("Token budget (default: 8000)"),
+      min_relevance: z2.number().optional().describe("Minimum score threshold (default: 0.3)")
     })
   },
   {
     name: "datacore.search",
     description: "Search journal entries and knowledge notes by keyword",
-    inputSchema: z.object({
-      query: z.string().describe("Search query"),
-      scope: z.enum(["journal", "knowledge", "all"]).optional(),
-      method: z.enum(["keyword", "semantic"]).optional().describe("Search method (default: keyword)"),
-      limit: z.number().optional().describe("Max results (default: 20)")
+    inputSchema: z2.object({
+      query: z2.string().describe("Search query"),
+      scope: z2.enum(["journal", "knowledge", "all"]).optional(),
+      method: z2.enum(["keyword", "semantic"]).optional().describe("Search method (default: keyword)"),
+      limit: z2.number().optional().describe("Max results (default: 20)")
     })
   },
   {
     name: "datacore.ingest",
     description: "Ingest text content as a knowledge note, optionally extract engram suggestions",
-    inputSchema: z.object({
-      content: z.string().describe("Content to ingest"),
-      title: z.string().optional(),
-      tags: z.array(z.string()).optional()
+    inputSchema: z2.object({
+      content: z2.string().describe("Content to ingest"),
+      title: z2.string().optional(),
+      tags: z2.array(z2.string()).optional()
     })
   },
   {
     name: "datacore.status",
     description: "Show Datacore status: engram/pack/note counts, scaling hints, update info",
-    inputSchema: z.object({})
+    inputSchema: z2.object({})
   },
   {
     name: "datacore.packs.discover",
     description: "Browse available engram packs from the registry",
-    inputSchema: z.object({
-      query: z.string().optional().describe("Filter by name/description"),
-      tags: z.array(z.string()).optional().describe("Filter by tags")
+    inputSchema: z2.object({
+      query: z2.string().optional().describe("Filter by name/description"),
+      tags: z2.array(z2.string()).optional().describe("Filter by tags")
     })
   },
   {
     name: "datacore.packs.install",
     description: "Install or upgrade an engram pack",
-    inputSchema: z.object({
-      source: z.string().describe("Pack source: local path or pack ID from registry")
+    inputSchema: z2.object({
+      source: z2.string().describe("Pack source: local path or pack ID from registry")
     })
   },
   {
     name: "datacore.forget",
     description: "Retire an engram by ID or search term \u2014 marks it as retired so it is no longer injected",
-    inputSchema: z.object({
-      id: z.string().optional().describe("Exact engram ID to retire (e.g., ENG-2026-0219-001)"),
-      search: z.string().optional().describe("Search term to find engram by statement, tag, or ID fragment")
+    inputSchema: z2.object({
+      id: z2.string().optional().describe("Exact engram ID to retire (e.g., ENG-2026-0219-001)"),
+      search: z2.string().optional().describe("Search term to find engram by statement, tag, or ID fragment")
     })
   },
   {
     name: "datacore.feedback",
-    description: "Signal whether an injected engram was helpful (positive), unhelpful (negative), or seen but not acted on (neutral)",
-    inputSchema: z.object({
-      engram_id: z.string().describe("The engram ID to provide feedback on"),
-      signal: z.enum(["positive", "negative", "neutral"]).describe("Feedback signal"),
-      comment: z.string().optional().describe("Optional comment about why")
+    description: "Signal whether an injected engram was helpful (positive), unhelpful (negative), or seen but not acted on (neutral). Supports single or batch mode.",
+    inputSchema: z2.object({
+      engram_id: z2.string().optional().describe("The engram ID to provide feedback on (single mode)"),
+      signal: z2.enum(["positive", "negative", "neutral"]).optional().describe("Feedback signal (single mode)"),
+      signals: z2.array(z2.object({
+        engram_id: z2.string().describe("Engram ID"),
+        signal: z2.enum(["positive", "negative", "neutral"]).describe("Feedback signal")
+      })).optional().describe("Batch feedback signals"),
+      comment: z2.string().optional().describe("Optional comment about why")
+    }).refine((data) => data.engram_id && data.signal || data.signals && data.signals.length > 0, {
+      message: "Either (engram_id + signal) or signals array required"
     })
   },
   {
     name: "datacore.packs.export",
     description: "Export personal engrams as a shareable pack. Preview by default, set confirm=true to write.",
-    inputSchema: z.object({
-      name: z.string().describe("Pack name"),
-      description: z.string().describe("Pack description"),
-      engram_ids: z.array(z.string()).optional().describe("Specific engram IDs to export"),
-      filter_tags: z.array(z.string()).optional().describe("Filter by tags"),
-      filter_domain: z.string().optional().describe("Filter by domain prefix"),
-      confirm: z.boolean().optional().describe("Set true to write pack (default: preview only)")
+    inputSchema: z2.object({
+      name: z2.string().describe("Pack name"),
+      description: z2.string().describe("Pack description"),
+      engram_ids: z2.array(z2.string()).optional().describe("Specific engram IDs to export"),
+      filter_tags: z2.array(z2.string()).optional().describe("Filter by tags"),
+      filter_domain: z2.string().optional().describe("Filter by domain prefix"),
+      confirm: z2.boolean().optional().describe("Set true to write pack (default: preview only)")
+    })
+  },
+  {
+    name: "datacore.session.start",
+    description: "Start here. Call this at the beginning of every session to get relevant context, today's journal, and a guide to all available tools.",
+    inputSchema: z2.object({
+      task: z2.string().optional().describe("What you are working on (triggers engram injection)"),
+      tags: z2.array(z2.string()).optional().describe("Tags to filter injected engrams")
+    })
+  },
+  {
+    name: "datacore.session.end",
+    description: "End a session \u2014 captures journal summary and creates engrams from suggestions",
+    inputSchema: z2.object({
+      summary: z2.string().describe("Session summary for the journal"),
+      tags: z2.array(z2.string()).optional().describe("Tags for the journal entry"),
+      engram_suggestions: z2.array(z2.object({
+        statement: z2.string().describe("The knowledge assertion"),
+        type: z2.enum(["behavioral", "terminological", "procedural", "architectural"]).optional()
+      })).optional().describe("Engrams to create from this session")
+    })
+  },
+  {
+    name: "datacore.recall",
+    description: "Search all sources (engrams, journal, knowledge) for a topic \u2014 results grouped by source",
+    inputSchema: z2.object({
+      topic: z2.string().describe("What to search for"),
+      sources: z2.array(z2.enum(["engrams", "journal", "knowledge"])).optional().describe("Which sources to search (default: all)"),
+      limit: z2.number().optional().describe("Max results per source (default: 10)")
+    })
+  },
+  {
+    name: "datacore.promote",
+    description: "Activate candidate engrams so they appear in inject results",
+    inputSchema: z2.object({
+      id: z2.string().optional().describe("Single engram ID to promote"),
+      ids: z2.array(z2.string()).optional().describe("Multiple engram IDs to promote")
+    }).refine((data) => data.id || data.ids && data.ids.length > 0, {
+      message: "At least one engram ID required (id or ids)"
     })
   },
   {
     name: "datacore.modules.list",
     description: "List installed modules with scope, version, and capability counts",
-    inputSchema: z.object({})
+    inputSchema: z2.object({})
   },
   {
     name: "datacore.modules.info",
     description: "Get detailed info about a specific module: manifest, tools, skills, agents, engrams",
-    inputSchema: z.object({
-      module: z.string().describe('Module name (e.g., "gtd", "slides", "crm")')
+    inputSchema: z2.object({
+      module: z2.string().describe('Module name (e.g., "gtd", "slides", "crm")')
     })
   },
   {
     name: "datacore.modules.health",
     description: "Check module health: missing files, env vars, data separation issues",
-    inputSchema: z.object({
-      module: z.string().optional().describe("Module name (omit for all modules)")
+    inputSchema: z2.object({
+      module: z2.string().optional().describe("Module name (omit for all modules)")
     })
   }
 ];
 
 // src/tools/capture.ts
-import * as fs2 from "fs";
-import * as path2 from "path";
+import * as fs3 from "fs";
+import * as path3 from "path";
 
 // src/limits.ts
 var MAX_CONTENT_SIZE = 1e6;
@@ -324,17 +513,17 @@ function localDate(tz) {
 }
 function captureJournal(content, journalDir) {
   const { date: today, time } = localDate();
-  const filePath = path2.join(journalDir, `${today}.md`);
-  fs2.mkdirSync(path2.dirname(filePath), { recursive: true });
-  if (fs2.existsSync(filePath)) {
-    const existing = fs2.readFileSync(filePath, "utf8");
-    fs2.writeFileSync(filePath, `${existing}
+  const filePath = path3.join(journalDir, `${today}.md`);
+  fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
+  if (fs3.existsSync(filePath)) {
+    const existing = fs3.readFileSync(filePath, "utf8");
+    fs3.writeFileSync(filePath, `${existing}
 ## ${time}
 
 ${content}
 `);
   } else {
-    fs2.writeFileSync(filePath, `# ${today}
+    fs3.writeFileSync(filePath, `# ${today}
 
 ## ${time}
 
@@ -347,8 +536,8 @@ function captureKnowledge(content, title, tags, knowledgeDir) {
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
   const slug = (title ?? "note").toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 50);
   const fileName = `${timestamp}-${slug}.md`;
-  const filePath = path2.join(knowledgeDir, fileName);
-  fs2.mkdirSync(path2.dirname(filePath), { recursive: true });
+  const filePath = path3.join(knowledgeDir, fileName);
+  fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
   const frontmatter = `---
 title: "${title ?? "Untitled"}"
 created: "${(/* @__PURE__ */ new Date()).toISOString()}"
@@ -358,82 +547,82 @@ created: "${(/* @__PURE__ */ new Date()).toISOString()}"
   const tagLine = tags?.length ? `
 ${tags.map((t) => `#${t}`).join(" ")}
 ` : "";
-  fs2.writeFileSync(filePath, `${frontmatter}${content}
+  fs3.writeFileSync(filePath, `${frontmatter}${content}
 ${tagLine}`);
   return { success: true, path: filePath };
 }
 
 // src/engrams.ts
-import * as fs3 from "fs";
-import * as yaml from "js-yaml";
+import * as fs4 from "fs";
+import * as yaml2 from "js-yaml";
 
 // src/schemas/engram.ts
-import { z as z2 } from "zod";
-var ActivationSchema = z2.object({
-  retrieval_strength: z2.number().min(0).max(1),
-  storage_strength: z2.number().min(0).max(1),
-  frequency: z2.number().int().min(0),
-  last_accessed: z2.string()
+import { z as z3 } from "zod";
+var ActivationSchema = z3.object({
+  retrieval_strength: z3.number().min(0).max(1),
+  storage_strength: z3.number().min(0).max(1),
+  frequency: z3.number().int().min(0),
+  last_accessed: z3.string()
 });
-var KnowledgeTypeSchema = z2.object({
-  memory_class: z2.enum(["semantic", "episodic", "procedural", "metacognitive"]),
-  cognitive_level: z2.enum(["remember", "understand", "apply", "analyze", "evaluate", "create"])
+var KnowledgeTypeSchema = z3.object({
+  memory_class: z3.enum(["semantic", "episodic", "procedural", "metacognitive"]),
+  cognitive_level: z3.enum(["remember", "understand", "apply", "analyze", "evaluate", "create"])
 });
-var RelationsSchema = z2.object({
-  broader: z2.array(z2.string()).default([]),
-  narrower: z2.array(z2.string()).default([]),
-  related: z2.array(z2.string()).default([]),
-  conflicts: z2.array(z2.string()).default([])
+var RelationsSchema = z3.object({
+  broader: z3.array(z3.string()).default([]),
+  narrower: z3.array(z3.string()).default([]),
+  related: z3.array(z3.string()).default([]),
+  conflicts: z3.array(z3.string()).default([])
 });
-var ProvenanceSchema = z2.object({
-  origin: z2.string(),
-  chain: z2.array(z2.string()).default([]),
-  signature: z2.string().nullable().default(null),
-  license: z2.string().default("cc-by-sa-4.0")
+var ProvenanceSchema = z3.object({
+  origin: z3.string(),
+  chain: z3.array(z3.string()).default([]),
+  signature: z3.string().nullable().default(null),
+  license: z3.string().default("cc-by-sa-4.0")
 });
-var FeedbackSignalsSchema = z2.object({
-  positive: z2.number().int().default(0),
-  negative: z2.number().int().default(0),
-  neutral: z2.number().int().default(0)
+var FeedbackSignalsSchema = z3.object({
+  positive: z3.number().int().default(0),
+  negative: z3.number().int().default(0),
+  neutral: z3.number().int().default(0)
 });
-var EngramSchema = z2.object({
-  id: z2.string().regex(/^ENG-[A-Za-z0-9-]+$/),
-  version: z2.number().int().min(1),
-  status: z2.enum(["active", "dormant", "retired", "candidate"]),
-  consolidated: z2.boolean().default(false),
-  type: z2.enum(["behavioral", "terminological", "procedural", "architectural"]),
-  scope: z2.string(),
-  visibility: z2.enum(["private", "public", "template"]).default("private"),
-  statement: z2.string().min(1),
-  rationale: z2.string().optional(),
-  contraindications: z2.array(z2.string()).optional(),
-  source_patterns: z2.array(z2.string()).optional(),
-  derivation_count: z2.number().int().min(0).default(1),
+var EngramSchema = z3.object({
+  id: z3.string().regex(/^ENG-[A-Za-z0-9-]+$/),
+  version: z3.number().int().min(1),
+  status: z3.enum(["active", "dormant", "retired", "candidate"]),
+  consolidated: z3.boolean().default(false),
+  type: z3.enum(["behavioral", "terminological", "procedural", "architectural"]),
+  scope: z3.string(),
+  visibility: z3.enum(["private", "public", "template"]).default("private"),
+  statement: z3.string().min(1),
+  rationale: z3.string().optional(),
+  contraindications: z3.array(z3.string()).optional(),
+  source_patterns: z3.array(z3.string()).optional(),
+  derivation_count: z3.number().int().min(0).default(1),
   knowledge_type: KnowledgeTypeSchema.optional(),
-  domain: z2.string().optional(),
+  domain: z3.string().optional(),
   relations: RelationsSchema.optional(),
   activation: ActivationSchema,
   provenance: ProvenanceSchema.optional(),
   feedback_signals: FeedbackSignalsSchema.optional(),
-  tags: z2.array(z2.string()).default([]),
-  pack: z2.string().nullable().default(null),
-  abstract: z2.string().nullable().default(null),
-  derived_from: z2.string().nullable().default(null)
+  tags: z3.array(z3.string()).default([]),
+  pack: z3.string().nullable().default(null),
+  abstract: z3.string().nullable().default(null),
+  derived_from: z3.string().nullable().default(null)
 });
-var DatacoreExtensionSchema = z2.object({
-  id: z2.string(),
-  injection_policy: z2.enum(["on_match", "on_request"]),
-  match_terms: z2.array(z2.string()).default([]),
-  domain: z2.string().optional(),
-  engram_count: z2.number().int().min(0)
+var DatacoreExtensionSchema = z3.object({
+  id: z3.string(),
+  injection_policy: z3.enum(["on_match", "on_request"]),
+  match_terms: z3.array(z3.string()).default([]),
+  domain: z3.string().optional(),
+  engram_count: z3.number().int().min(0)
 });
-var PackManifestSchema = z2.object({
-  name: z2.string(),
-  description: z2.string(),
-  version: z2.string(),
-  creator: z2.string().optional(),
-  license: z2.string().optional(),
-  tags: z2.array(z2.string()).default([]),
+var PackManifestSchema = z3.object({
+  name: z3.string(),
+  description: z3.string(),
+  version: z3.string(),
+  creator: z3.string().optional(),
+  license: z3.string().optional(),
+  tags: z3.array(z3.string()).default([]),
   "x-datacore": DatacoreExtensionSchema
 });
 
@@ -491,9 +680,9 @@ var logger = new Logger();
 
 // src/engrams.ts
 function loadEngrams(filePath) {
-  if (!fs3.existsSync(filePath)) return [];
+  if (!fs4.existsSync(filePath)) return [];
   try {
-    const raw = yaml.load(fs3.readFileSync(filePath, "utf8"));
+    const raw = yaml2.load(fs4.readFileSync(filePath, "utf8"));
     if (!raw?.engrams || !Array.isArray(raw.engrams)) return [];
     const valid = [];
     let skipped = 0;
@@ -515,15 +704,15 @@ function loadEngrams(filePath) {
   }
 }
 function saveEngrams(filePath, engrams) {
-  const content = yaml.dump({ engrams }, { lineWidth: 120, noRefs: true, quotingType: '"' });
-  fs3.writeFileSync(filePath, content);
+  const content = yaml2.dump({ engrams }, { lineWidth: 120, noRefs: true, quotingType: '"' });
+  fs4.writeFileSync(filePath, content);
 }
 function parseSkillMdFrontmatter(filePath) {
-  const content = fs3.readFileSync(filePath, "utf8");
+  const content = fs4.readFileSync(filePath, "utf8");
   const match = content.match(/^---\n([\s\S]*?)\n---/);
   if (!match) throw new Error(`No frontmatter found in ${filePath}`);
   try {
-    return yaml.load(match[1]);
+    return yaml2.load(match[1]);
   } catch (err) {
     throw new Error(`Failed to parse YAML frontmatter in ${filePath}: ${err}`);
   }
@@ -537,12 +726,12 @@ function loadPack(packDir) {
   return { manifest, engrams };
 }
 function loadAllPacks(packsDir) {
-  if (!fs3.existsSync(packsDir)) return [];
+  if (!fs4.existsSync(packsDir)) return [];
   const packs = [];
-  for (const entry of fs3.readdirSync(packsDir)) {
+  for (const entry of fs4.readdirSync(packsDir)) {
     const packDir = `${packsDir}/${entry}`;
-    if (!fs3.statSync(packDir).isDirectory()) continue;
-    if (!fs3.existsSync(`${packDir}/SKILL.md`)) continue;
+    if (!fs4.statSync(packDir).isDirectory()) continue;
+    if (!fs4.existsSync(`${packDir}/SKILL.md`)) continue;
     try {
       packs.push(loadPack(packDir));
     } catch (err) {
@@ -552,6 +741,13 @@ function loadAllPacks(packsDir) {
   return packs;
 }
 
+// src/hints.ts
+function buildHints(hints) {
+  if (!getConfig().hints.enabled) return void 0;
+  if (!hints.next && !hints.related?.length && !hints.warning) return void 0;
+  return hints;
+}
+
 // src/tools/learn.ts
 function generateEngramId(existingEngrams) {
   const now = /* @__PURE__ */ new Date();
@@ -571,10 +767,11 @@ function generateEngramId(existingEngrams) {
 async function handleLearn(args2, engramsPath) {
   const engrams = loadEngrams(engramsPath);
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const autoPromote = getConfig().engrams.auto_promote;
   const engram = {
     id: generateEngramId(engrams),
     version: 2,
-    status: "candidate",
+    status: autoPromote ? "active" : "candidate",
     consolidated: false,
     type: args2.type ?? "behavioral",
     scope: args2.scope ?? "global",
@@ -585,8 +782,8 @@ async function handleLearn(args2, engramsPath) {
     domain: args2.domain,
     tags: args2.tags ?? [],
     activation: {
-      retrieval_strength: 0.5,
-      storage_strength: 0.3,
+      retrieval_strength: autoPromote ? 0.7 : 0.5,
+      storage_strength: autoPromote ? 1 : 0.3,
       frequency: 0,
       last_accessed: today
     },
@@ -596,12 +793,21 @@ async function handleLearn(args2, engramsPath) {
   };
   engrams.push(engram);
   saveEngrams(engramsPath, engrams);
-  return { success: true, engram };
+  const statusLabel = autoPromote ? "active" : "candidate";
+  const hints = autoPromote ? buildHints({
+    next: "Created as active (auto_promote on). Use datacore.inject to retrieve.",
+    related: ["datacore.inject"],
+    warning: "Auto-promotion enabled. Engrams are immediately active without review."
+  }) : buildHints({
+    next: "Created as candidate. Use datacore.promote to activate.",
+    related: ["datacore.promote", "datacore.inject"]
+  });
+  return { success: true, engram, _hints: hints };
 }
 
 // src/tools/inject-tool.ts
-import * as fs4 from "fs";
-import * as yaml2 from "js-yaml";
+import * as fs5 from "fs";
+import * as yaml3 from "js-yaml";
 
 // src/decay.ts
 var DECAY_RATE = 0.05;
@@ -727,7 +933,15 @@ async function handleInject(args2, paths) {
   const result = selectEngrams(ctx, personalEngrams, packs);
   const totalCount = result.directives.length + result.consider.length;
   if (totalCount === 0) {
-    return { text: "", count: 0, tokens_used: 0 };
+    return {
+      text: "",
+      count: 0,
+      tokens_used: 0,
+      _hints: buildHints({
+        next: "No engrams matched this task. Use datacore.recall to search all sources, or datacore.learn to record new knowledge.",
+        related: ["datacore.recall", "datacore.learn"]
+      })
+    };
   }
   const lines = [];
   if (result.directives.length > 0) {
@@ -747,7 +961,17 @@ async function handleInject(args2, paths) {
     personalEngrams,
     [...result.directives, ...result.consider]
   );
-  return { text: lines.join("\n"), count: totalCount, tokens_used: result.tokens_used };
+  const injectedIds = [...result.directives, ...result.consider].filter((e) => !e.pack).map((e) => e.id);
+  const idsList = injectedIds.length > 0 ? ` Injected IDs: ${injectedIds.join(", ")}` : "";
+  return {
+    text: lines.join("\n"),
+    count: totalCount,
+    tokens_used: result.tokens_used,
+    _hints: buildHints({
+      next: `After task, call datacore.feedback on helpful/unhelpful engrams.${idsList}`,
+      related: ["datacore.feedback", "datacore.session.end"]
+    })
+  };
 }
 function updateUsageTracking(engramsPath, allPersonal, selected) {
   const selectedPersonalIds = new Set(
@@ -768,10 +992,10 @@ function updateUsageTracking(engramsPath, allPersonal, selected) {
   }
 }
 function atomicWriteYaml(filePath, data) {
-  const content = yaml2.dump(data, { lineWidth: 120, noRefs: true, quotingType: '"' });
+  const content = yaml3.dump(data, { lineWidth: 120, noRefs: true, quotingType: '"' });
   const tmpPath = filePath + ".tmp." + process.pid;
-  fs4.writeFileSync(tmpPath, content);
-  fs4.renameSync(tmpPath, filePath);
+  fs5.writeFileSync(tmpPath, content);
+  fs5.renameSync(tmpPath, filePath);
 }
 function formatEngram(engram, totalCount) {
   if (totalCount < 10) {
@@ -792,15 +1016,15 @@ function formatEngram(engram, totalCount) {
 }
 
 // src/tools/search.ts
-import * as fs5 from "fs";
-import * as path3 from "path";
+import * as fs6 from "fs";
+import * as path4 from "path";
 var CONTENT_CACHE_MAX = 500;
 var contentCache = /* @__PURE__ */ new Map();
 function getCachedContent(filePath) {
   const entry = contentCache.get(filePath);
   if (!entry) return null;
   try {
-    const stat = fs5.statSync(filePath);
+    const stat = fs6.statSync(filePath);
     if (stat.mtimeMs === entry.mtime) return entry.content;
   } catch {
   }
@@ -809,7 +1033,7 @@ function getCachedContent(filePath) {
 }
 function setCachedContent(filePath, content) {
   try {
-    const mtime = fs5.statSync(filePath).mtimeMs;
+    const mtime = fs6.statSync(filePath).mtimeMs;
     if (contentCache.size >= CONTENT_CACHE_MAX) {
       const firstKey = contentCache.keys().next().value;
       if (firstKey) contentCache.delete(firstKey);
@@ -846,13 +1070,13 @@ async function keywordSearch(args2, paths) {
   return { results: results.slice(0, limit), method: "keyword" };
 }
 function searchDir(dirPath, query) {
-  if (!fs5.existsSync(dirPath)) return [];
+  if (!fs6.existsSync(dirPath)) return [];
   const results = [];
   const queryLower = query.toLowerCase();
   for (const file of walkDir(dirPath)) {
     if (!file.endsWith(".md")) continue;
     const content = getCachedContent(file) ?? (() => {
-      const c = fs5.readFileSync(file, "utf8");
+      const c = fs6.readFileSync(file, "utf8");
       setCachedContent(file, c);
       return c;
     })();
@@ -860,14 +1084,16 @@ function searchDir(dirPath, query) {
     const occurrences = countOccurrences(contentLower, queryLower);
     if (occurrences === 0) continue;
     const snippet = extractSnippet(content, query);
-    results.push({ path: file, snippet, score: occurrences });
+    const title = extractTitle(content, file);
+    const date = extractDate(file);
+    results.push({ path: file, snippet, score: occurrences, title, date });
   }
   return results;
 }
 function walkDir(dir) {
   const files = [];
-  for (const entry of fs5.readdirSync(dir, { withFileTypes: true })) {
-    const fullPath = path3.join(dir, entry.name);
+  for (const entry of fs6.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path4.join(dir, entry.name);
     if (entry.isDirectory()) files.push(...walkDir(fullPath));
     else files.push(fullPath);
   }
@@ -883,16 +1109,29 @@ function countOccurrences(text, query) {
   return count;
 }
 function extractSnippet(content, query) {
+  const snippetLength = getConfig().search.snippet_length;
+  if (content.length < 2e3) return content;
   const idx = content.toLowerCase().indexOf(query.toLowerCase());
-  if (idx === -1) return content.slice(0, 100);
-  const start2 = Math.max(0, idx - 50);
-  const end = Math.min(content.length, idx + query.length + 50);
+  if (idx === -1) return content.slice(0, snippetLength);
+  const half = Math.floor(snippetLength / 2);
+  const start2 = Math.max(0, idx - half);
+  const end = Math.min(content.length, idx + query.length + half);
   return (start2 > 0 ? "..." : "") + content.slice(start2, end) + (end < content.length ? "..." : "");
 }
+function extractTitle(content, filePath) {
+  const match = content.match(/^#\s+(.+)$/m);
+  if (match) return match[1].trim();
+  return path4.basename(filePath, path4.extname(filePath));
+}
+function extractDate(filePath) {
+  const match = path4.basename(filePath).match(/^(\d{4}-\d{2}-\d{2})/);
+  if (match) return match[1];
+  return void 0;
+}
 
 // src/tools/ingest.ts
-import * as fs6 from "fs";
-import * as path4 from "path";
+import * as fs7 from "fs";
+import * as path5 from "path";
 async function handleIngest(args2, paths) {
   const contentError = validateContent(args2.content);
   if (contentError) return { success: false, error: contentError };
@@ -903,8 +1142,8 @@ async function handleIngest(args2, paths) {
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
   const slug = (args2.title ?? "ingested").toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 50);
   const fileName = `${timestamp}-${slug}.md`;
-  const filePath = path4.join(paths.knowledgePath, fileName);
-  fs6.mkdirSync(path4.dirname(filePath), { recursive: true });
+  const filePath = path5.join(paths.knowledgePath, fileName);
+  fs7.mkdirSync(path5.dirname(filePath), { recursive: true });
   const frontmatter = `---
 title: "${args2.title ?? "Ingested Note"}"
 created: "${(/* @__PURE__ */ new Date()).toISOString()}"
@@ -915,13 +1154,17 @@ type: ingested
   const tagLine = args2.tags?.length ? `
 ${args2.tags.map((t) => `#${t}`).join(" ")}
 ` : "";
-  fs6.writeFileSync(filePath, `${frontmatter}${args2.content}
+  fs7.writeFileSync(filePath, `${frontmatter}${args2.content}
 ${tagLine}`);
   const suggestions = extractEngramSuggestions(args2.content);
   return {
     success: true,
     note_path: filePath,
-    engram_suggestions: suggestions.length > 0 ? suggestions : void 0
+    engram_suggestions: suggestions.length > 0 ? suggestions : void 0,
+    _hints: suggestions.length > 0 ? buildHints({
+      next: `Call datacore.learn for each suggestion to create engrams. Example: datacore.learn({statement: '${suggestions[0]}', type: 'behavioral'})`,
+      related: ["datacore.learn"]
+    }) : void 0
   };
 }
 function extractEngramSuggestions(content) {
@@ -945,21 +1188,21 @@ function extractEngramSuggestions(content) {
 }
 
 // src/tools/status.ts
-import * as fs8 from "fs";
-import * as path6 from "path";
+import * as fs9 from "fs";
+import * as path7 from "path";
 
 // src/trust.ts
-import * as fs7 from "fs";
-import * as path5 from "path";
+import * as fs8 from "fs";
+import * as path6 from "path";
 import * as crypto from "crypto";
 function computePackChecksum(packDir) {
   const files = ["SKILL.md", "engrams.yaml"];
   const hash = crypto.createHash("sha256");
   let hasContent = false;
   for (const file of files) {
-    const filePath = path5.join(packDir, file);
-    if (fs7.existsSync(filePath)) {
-      hash.update(fs7.readFileSync(filePath));
+    const filePath = path6.join(packDir, file);
+    if (fs8.existsSync(filePath)) {
+      hash.update(fs8.readFileSync(filePath));
       hasContent = true;
     }
   }
@@ -1029,12 +1272,31 @@ async function handleStatus(paths, updateAvailable2) {
   const packIntegrity = [];
   for (const regPack of packs_default.packs) {
     if (!regPack.checksum) continue;
-    const packDir = path6.join(paths.packsPath, regPack.id);
-    if (!fs8.existsSync(packDir)) continue;
-    const result2 = verifyPackChecksum(packDir, regPack.checksum);
-    packIntegrity.push({ name: regPack.id, valid: result2.valid });
+    const packDir = path7.join(paths.packsPath, regPack.id);
+    if (!fs9.existsSync(packDir)) continue;
+    const result = verifyPackChecksum(packDir, regPack.checksum);
+    packIntegrity.push({ name: regPack.id, valid: result.valid });
+  }
+  const recommendations = [];
+  const candidateCount = engrams.filter((e) => e.status === "candidate").length;
+  if (healthCounts.retirement_candidate > 0) {
+    recommendations.push(`${healthCounts.retirement_candidate} engrams are retirement candidates. Use datacore.forget to clean up.`);
+  }
+  if (healthCounts.fading > 0) {
+    recommendations.push(`${healthCounts.fading} engrams are fading. Use datacore.feedback with positive signal to reinforce.`);
   }
-  const result = {
+  if (candidateCount > 0) {
+    recommendations.push(`${candidateCount} candidate engrams awaiting review. Use datacore.promote or enable engrams.auto_promote in config.yaml.`);
+  }
+  const { date: today } = localDate();
+  const todayJournal = path7.join(paths.journalPath, `${today}.md`);
+  if (!fs9.existsSync(todayJournal)) {
+    recommendations.push("No journal entry today. Use datacore.capture to start one.");
+  }
+  if (updateAvailable2) {
+    recommendations.push(`Update available: ${updateAvailable2}. Run: npm update -g @datacore-one/mcp`);
+  }
+  const statusResult = {
     version: currentVersion,
     mode: paths.mode,
     engrams: engrams.length,
@@ -1042,42 +1304,47 @@ async function handleStatus(paths, updateAvailable2) {
     packs: packsCount,
     pack_integrity: packIntegrity.length > 0 ? packIntegrity : void 0,
     journal_entries: journalCount,
-    knowledge_notes: knowledgeCount
+    knowledge_notes: knowledgeCount,
+    _recommendations: recommendations.length > 0 ? recommendations : void 0,
+    _hints: buildHints({
+      next: recommendations.length > 0 ? recommendations[0] : "System healthy. Use datacore.session.start to begin working.",
+      related: ["datacore.promote", "datacore.forget"]
+    })
   };
   if (engrams.length >= 500) {
-    result.scaling_hint = `You have ${engrams.length} engrams. Consider migrating to full Datacore for SQLite-backed search.`;
+    statusResult.scaling_hint = `You have ${engrams.length} engrams. Consider migrating to full Datacore for SQLite-backed search.`;
   }
   if (updateAvailable2) {
-    result.update_available = updateAvailable2;
+    statusResult.update_available = updateAvailable2;
   }
-  return result;
+  return statusResult;
 }
 function countFiles(dir, ext) {
-  if (!fs8.existsSync(dir)) return 0;
+  if (!fs9.existsSync(dir)) return 0;
   let count = 0;
-  for (const entry of fs8.readdirSync(dir, { withFileTypes: true })) {
-    const fullPath = path6.join(dir, entry.name);
+  for (const entry of fs9.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path7.join(dir, entry.name);
     if (entry.isDirectory()) count += countFiles(fullPath, ext);
     else if (entry.name.endsWith(ext)) count++;
   }
   return count;
 }
 function countDirs(dir) {
-  if (!fs8.existsSync(dir)) return 0;
-  return fs8.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).length;
+  if (!fs9.existsSync(dir)) return 0;
+  return fs9.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).length;
 }
 
 // src/tools/discover.ts
-import * as fs9 from "fs";
-import * as path7 from "path";
+import * as fs10 from "fs";
+import * as path8 from "path";
 function handleDiscover(args2, packsDir) {
   let packs = packs_default.packs.map((p) => {
-    const localDir = path7.join(packsDir, p.id);
-    const installed = fs9.existsSync(path7.join(localDir, "SKILL.md"));
+    const localDir = path8.join(packsDir, p.id);
+    const installed = fs10.existsSync(path8.join(localDir, "SKILL.md"));
     let installedVersion;
     if (installed) {
       try {
-        const content = fs9.readFileSync(path7.join(localDir, "SKILL.md"), "utf8");
+        const content = fs10.readFileSync(path8.join(localDir, "SKILL.md"), "utf8");
         const match = content.match(/version:\s*["']?([^"'\n]+)/);
         installedVersion = match?.[1];
       } catch {
@@ -1101,13 +1368,21 @@ function handleDiscover(args2, packsDir) {
     const filterTags = new Set(args2.tags.map((t) => t.toLowerCase()));
     packs = packs.filter((p) => p.tags.some((t) => filterTags.has(t.toLowerCase())));
   }
-  return { packs };
+  const trusted = new Set(getConfig().packs.trusted_publishers);
+  const result = { packs };
+  if (trusted.size > 0) {
+    const autoInstallable = packs.filter((p) => trusted.has(p.author) && !p.installed && p.can_install).map((p) => p.id);
+    const autoUpgradeable = packs.filter((p) => trusted.has(p.author) && p.upgradeable).map((p) => p.id);
+    if (autoInstallable.length > 0) result.auto_installable = autoInstallable;
+    if (autoUpgradeable.length > 0) result.auto_upgradeable = autoUpgradeable;
+  }
+  return result;
 }
 
 // src/tools/install.ts
-import * as fs10 from "fs";
-import * as path8 from "path";
-import * as yaml3 from "js-yaml";
+import * as fs11 from "fs";
+import * as path9 from "path";
+import * as yaml4 from "js-yaml";
 import * as os2 from "os";
 import { execSync } from "child_process";
 async function handleInstall(args2, packsDir) {
@@ -1116,35 +1391,39 @@ async function handleInstall(args2, packsDir) {
     const downloaded = await downloadPack(srcDir);
     if (downloaded.error) return { success: false, error: downloaded.error };
     srcDir = downloaded.path;
+  } else if (!srcDir.includes("/") && !srcDir.includes("\\")) {
+    const resolved = resolvePackId(srcDir, packsDir);
+    if (resolved.error) return { success: false, error: resolved.error };
+    srcDir = resolved.path;
   }
-  const skillPath = path8.join(srcDir, "SKILL.md");
-  if (!fs10.existsSync(skillPath)) {
+  const skillPath = path9.join(srcDir, "SKILL.md");
+  if (!fs11.existsSync(skillPath)) {
     return { success: false, error: "No SKILL.md found in source directory" };
   }
-  const skillContent = fs10.readFileSync(skillPath, "utf8");
+  const skillContent = fs11.readFileSync(skillPath, "utf8");
   const frontmatterMatch = skillContent.match(/^---\n([\s\S]*?)\n---/);
   if (!frontmatterMatch) {
     return { success: false, error: "No YAML frontmatter in SKILL.md" };
   }
-  const manifest = yaml3.load(frontmatterMatch[1]);
+  const manifest = yaml4.load(frontmatterMatch[1]);
   const packId = manifest?.["x-datacore"]?.id;
   const newVersion = manifest?.version;
   if (!packId) {
     return { success: false, error: "Missing x-datacore.id in SKILL.md frontmatter" };
   }
-  const destDir = path8.join(packsDir, packId);
-  if (fs10.existsSync(path8.join(destDir, "SKILL.md"))) {
-    const existingContent = fs10.readFileSync(path8.join(destDir, "SKILL.md"), "utf8");
+  const destDir = path9.join(packsDir, packId);
+  if (fs11.existsSync(path9.join(destDir, "SKILL.md"))) {
+    const existingContent = fs11.readFileSync(path9.join(destDir, "SKILL.md"), "utf8");
     const existingMatch = existingContent.match(/version:\s*["']?([^"'\n]+)/);
     const existingVersion = existingMatch?.[1];
     if (existingVersion === newVersion) {
       return { success: true, pack_id: packId, already_current: true };
     }
-    fs10.rmSync(destDir, { recursive: true, force: true });
-    fs10.cpSync(srcDir, destDir, { recursive: true });
+    fs11.rmSync(destDir, { recursive: true, force: true });
+    fs11.cpSync(srcDir, destDir, { recursive: true });
     return { success: true, pack_id: packId, upgraded: true };
   }
-  fs10.cpSync(srcDir, destDir, { recursive: true });
+  fs11.cpSync(srcDir, destDir, { recursive: true });
   const checksumVerified = verifyInstalledChecksum(packId, destDir);
   return { success: true, pack_id: packId, checksum_verified: checksumVerified ?? void 0 };
 }
@@ -1155,15 +1434,15 @@ function verifyInstalledChecksum(packId, destDir) {
   return result.valid;
 }
 async function downloadPack(url) {
-  const tmpDir = fs10.mkdtempSync(path8.join(os2.tmpdir(), "datacore-pack-"));
+  const tmpDir = fs11.mkdtempSync(path9.join(os2.tmpdir(), "datacore-pack-"));
   try {
     const res = await fetch(url, { signal: AbortSignal.timeout(3e4) });
     if (!res.ok) return { error: `Download failed: HTTP ${res.status}` };
     const buffer = Buffer.from(await res.arrayBuffer());
-    const archivePath = path8.join(tmpDir, "pack.tar.gz");
-    fs10.writeFileSync(archivePath, buffer);
-    const extractDir = path8.join(tmpDir, "extracted");
-    fs10.mkdirSync(extractDir);
+    const archivePath = path9.join(tmpDir, "pack.tar.gz");
+    fs11.writeFileSync(archivePath, buffer);
+    const extractDir = path9.join(tmpDir, "extracted");
+    fs11.mkdirSync(extractDir);
     execSync(`tar xzf ${JSON.stringify(archivePath)} -C ${JSON.stringify(extractDir)}`, { timeout: 1e4 });
     const packRoot = findPackRoot(extractDir);
     if (!packRoot) return { error: "Downloaded archive does not contain SKILL.md" };
@@ -1173,20 +1452,43 @@ async function downloadPack(url) {
   }
 }
 function findPackRoot(dir) {
-  if (fs10.existsSync(path8.join(dir, "SKILL.md"))) return dir;
-  for (const entry of fs10.readdirSync(dir, { withFileTypes: true })) {
+  if (fs11.existsSync(path9.join(dir, "SKILL.md"))) return dir;
+  for (const entry of fs11.readdirSync(dir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
-      const found = findPackRoot(path8.join(dir, entry.name));
+      const found = findPackRoot(path9.join(dir, entry.name));
       if (found) return found;
     }
   }
   return null;
 }
+function resolvePackId(packId, packsDir) {
+  const registryPack = packs_default.packs.find((p) => p.id === packId);
+  if (!registryPack) {
+    return { error: `Pack "${packId}" not found in registry. Use datacore.packs.discover to browse available packs.` };
+  }
+  if (registryPack.download_url) {
+    return { error: `Pack "${packId}" must be installed via URL: ${registryPack.download_url}` };
+  }
+  const bundledDir = path9.join(
+    path9.dirname(new URL(import.meta.url).pathname),
+    "..",
+    "packs",
+    packId
+  );
+  if (fs11.existsSync(path9.join(bundledDir, "SKILL.md"))) {
+    return { path: bundledDir };
+  }
+  const localDir = path9.join(packsDir, packId);
+  if (fs11.existsSync(path9.join(localDir, "SKILL.md"))) {
+    return { path: localDir };
+  }
+  return { error: `Pack "${packId}" is registered but not available locally. It may need to be downloaded manually.` };
+}
 
 // src/tools/export.ts
-import * as fs11 from "fs";
-import * as path9 from "path";
-import * as yaml4 from "js-yaml";
+import * as fs12 from "fs";
+import * as path10 from "path";
+import * as yaml5 from "js-yaml";
 async function handleExport(args2, paths) {
   const allEngrams = loadEngrams(paths.engramsPath);
   let selected = allEngrams.filter((e) => e.status === "active");
@@ -1218,7 +1520,7 @@ async function handleExport(args2, paths) {
     return { success: false, error: "No engrams match the filter criteria" };
   }
   const packId = args2.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 50);
-  const packDir = path9.join(paths.packsPath, packId);
+  const packDir = path10.join(paths.packsPath, packId);
   if (!args2.confirm) {
     return {
       success: true,
@@ -1229,7 +1531,13 @@ async function handleExport(args2, paths) {
       }
     };
   }
-  fs11.mkdirSync(packDir, { recursive: true });
+  if (fs12.existsSync(packDir)) {
+    return {
+      success: false,
+      error: `Pack directory already exists at ${packDir}. Remove it first or use a different name.`
+    };
+  }
+  fs12.mkdirSync(packDir, { recursive: true });
   const skillContent = `---
 name: "${args2.name}"
 description: "${args2.description}"
@@ -1248,7 +1556,7 @@ ${args2.description}
 
 Exported ${selected.length} engrams.
 `;
-  fs11.writeFileSync(path9.join(packDir, "SKILL.md"), skillContent);
+  fs12.writeFileSync(path10.join(packDir, "SKILL.md"), skillContent);
   const exportEngrams = selected.map((e) => ({
     id: e.id,
     version: e.version,
@@ -1257,6 +1565,7 @@ Exported ${selected.length} engrams.
     visibility: e.visibility,
     statement: e.statement,
     rationale: e.rationale,
+    contraindications: e.contraindications,
     tags: e.tags,
     domain: e.domain,
     status: "active",
@@ -1268,27 +1577,27 @@ Exported ${selected.length} engrams.
     },
     feedback_signals: { positive: 0, negative: 0 }
   }));
-  fs11.writeFileSync(
-    path9.join(packDir, "engrams.yaml"),
-    yaml4.dump({ engrams: exportEngrams }, { lineWidth: 120, noRefs: true, quotingType: '"' })
+  fs12.writeFileSync(
+    path10.join(packDir, "engrams.yaml"),
+    yaml5.dump({ engrams: exportEngrams }, { lineWidth: 120, noRefs: true, quotingType: '"' })
   );
   return { success: true, pack_path: packDir };
 }
 
 // src/modules.ts
-import * as fs12 from "fs";
-import * as path10 from "path";
-import * as yaml5 from "js-yaml";
+import * as fs13 from "fs";
+import * as path11 from "path";
+import * as yaml6 from "js-yaml";
 function discoverModules(storage2) {
   const modules = [];
   if (storage2.mode !== "full") return modules;
-  const globalModulesDir = path10.join(storage2.basePath, ".datacore", "modules");
+  const globalModulesDir = path11.join(storage2.basePath, ".datacore", "modules");
   modules.push(...scanModulesDir(globalModulesDir, "global"));
   try {
-    const entries = fs12.readdirSync(storage2.basePath);
+    const entries = fs13.readdirSync(storage2.basePath);
     for (const entry of entries) {
       if (/^\d+-/.test(entry)) {
-        const spaceModulesDir = path10.join(storage2.basePath, entry, ".datacore", "modules");
+        const spaceModulesDir = path11.join(storage2.basePath, entry, ".datacore", "modules");
         modules.push(...scanModulesDir(spaceModulesDir, "space", entry));
       }
     }
@@ -1298,16 +1607,16 @@ function discoverModules(storage2) {
 }
 function scanModulesDir(modulesDir, scope, spaceName) {
   const modules = [];
-  if (!fs12.existsSync(modulesDir)) return modules;
+  if (!fs13.existsSync(modulesDir)) return modules;
   try {
-    const entries = fs12.readdirSync(modulesDir);
+    const entries = fs13.readdirSync(modulesDir);
     for (const entry of entries) {
-      const modulePath = path10.join(modulesDir, entry);
-      const manifestPath = path10.join(modulePath, "module.yaml");
-      if (!fs12.existsSync(manifestPath)) continue;
+      const modulePath = path11.join(modulesDir, entry);
+      const manifestPath = path11.join(modulePath, "module.yaml");
+      if (!fs13.existsSync(manifestPath)) continue;
       try {
-        const raw = fs12.readFileSync(manifestPath, "utf-8");
-        const manifest = yaml5.load(raw);
+        const raw = fs13.readFileSync(manifestPath, "utf-8");
+        const manifest = yaml6.load(raw);
         if (!manifest || !manifest.name) continue;
         modules.push({
           name: manifest.name,
@@ -1328,12 +1637,12 @@ async function loadModuleTools(modules, storage2) {
   for (const mod of modules) {
     const declaredTools = mod.manifest.provides?.tools;
     if (!declaredTools || declaredTools.length === 0) continue;
-    const toolsIndexPath = path10.join(mod.modulePath, "tools", "index.js");
-    if (!fs12.existsSync(toolsIndexPath)) continue;
+    const toolsIndexPath = path11.join(mod.modulePath, "tools", "index.js");
+    if (!fs13.existsSync(toolsIndexPath)) continue;
     try {
       const toolsModule = await import(toolsIndexPath);
       const moduleTools2 = toolsModule.tools || toolsModule.default?.tools || [];
-      const dataPath = mod.scope === "space" && mod.spaceName ? path10.join(storage2.basePath, mod.spaceName, ".datacore", "modules", mod.name, "data") : path10.join(storage2.basePath, "0-personal", ".datacore", "modules", mod.name, "data");
+      const dataPath = mod.scope === "space" && mod.spaceName ? path11.join(storage2.basePath, mod.spaceName, ".datacore", "modules", mod.name, "data") : path11.join(storage2.basePath, "0-personal", ".datacore", "modules", mod.name, "data");
       const context = {
         storage: storage2,
         modulePath: mod.modulePath,
@@ -1429,8 +1738,8 @@ async function handleModulesInfo(args2, storage2, cachedModules) {
 }
 
 // src/tools/modules-health.ts
-import * as fs13 from "fs";
-import * as path11 from "path";
+import * as fs14 from "fs";
+import * as path12 from "path";
 async function handleModulesHealth(args2, storage2, cachedModules) {
   const modules = cachedModules ?? discoverModules(storage2);
   if (args2.module) {
@@ -1452,10 +1761,10 @@ async function handleModulesHealth(args2, storage2, cachedModules) {
 async function checkModule(mod, storage2) {
   const issues = [];
   const manifest = mod.manifest;
-  if (!fs13.existsSync(path11.join(mod.modulePath, "SKILL.md"))) {
+  if (!fs14.existsSync(path12.join(mod.modulePath, "SKILL.md"))) {
     issues.push("Missing SKILL.md (ecosystem entry point)");
   }
-  if (!fs13.existsSync(path11.join(mod.modulePath, "CLAUDE.base.md"))) {
+  if (!fs14.existsSync(path12.join(mod.modulePath, "CLAUDE.base.md"))) {
     issues.push("Missing CLAUDE.base.md (AI context)");
   }
   if (!manifest.manifest_version || manifest.manifest_version < 2) {
@@ -1471,8 +1780,8 @@ async function checkModule(mod, storage2) {
   const provides = manifest.provides;
   const declaredTools = provides?.tools || [];
   if (declaredTools.length > 0) {
-    const toolsIndex = path11.join(mod.modulePath, "tools", "index.js");
-    if (!fs13.existsSync(toolsIndex)) {
+    const toolsIndex = path12.join(mod.modulePath, "tools", "index.js");
+    if (!fs14.existsSync(toolsIndex)) {
       issues.push(`Declares ${declaredTools.length} tools but tools/index.js not found`);
     } else {
       try {
@@ -1491,13 +1800,13 @@ async function checkModule(mod, storage2) {
   const suspectExts = [".db", ".sqlite", ".json"];
   const suspectDirs = ["output", "data", "state"];
   for (const dir of suspectDirs) {
-    const fullPath = path11.join(mod.modulePath, dir);
-    if (fs13.existsSync(fullPath) && fs13.statSync(fullPath).isDirectory()) {
+    const fullPath = path12.join(mod.modulePath, dir);
+    if (fs14.existsSync(fullPath) && fs14.statSync(fullPath).isDirectory()) {
       issues.push(`Data dir '${dir}/' found in module code (should be in space data path)`);
     }
   }
   try {
-    const entries = fs13.readdirSync(mod.modulePath);
+    const entries = fs14.readdirSync(mod.modulePath);
     for (const entry of entries) {
       if (suspectExts.some((ext) => entry.endsWith(ext))) {
         issues.push(`Data file '${entry}' found in module code dir`);
@@ -1530,9 +1839,10 @@ async function handleForget(args2, engramsPath) {
   }
   if (args2.search) {
     const searchLower = args2.search.toLowerCase();
-    const matches = engrams.filter((e) => e.status !== "retired").filter(
+    const allMatches = engrams.filter((e) => e.status !== "retired").filter(
       (e) => e.statement.toLowerCase().includes(searchLower) || e.id.toLowerCase().includes(searchLower) || e.tags.some((t) => t.toLowerCase().includes(searchLower))
-    ).slice(0, 10);
+    );
+    const matches = allMatches.slice(0, 100);
     if (matches.length === 0) {
       return { success: false, error: `No active engrams matching "${args2.search}"` };
     }
@@ -1543,36 +1853,347 @@ async function handleForget(args2, engramsPath) {
       saveEngrams(engramsPath, engrams);
       return { success: true, retired: { id: engram.id, statement: engram.statement } };
     }
+    const truncated = allMatches.length > 100;
     return {
       success: false,
       matches: matches.map((e) => ({ id: e.id, statement: e.statement })),
-      error: `Multiple matches found. Specify an exact ID to retire.`
+      total_matches: allMatches.length,
+      error: `${allMatches.length} matches found${truncated ? " (showing first 100)" : ""}. Specify an exact ID to retire.`
     };
   }
   return { success: false, error: "Provide either id or search parameter" };
 }
 
 // src/tools/feedback.ts
-async function handleFeedback(args2, engramsPath) {
-  const engrams = loadEngrams(engramsPath);
-  const engram = engrams.find((e) => e.id === args2.engram_id);
-  if (!engram) {
-    return { success: false, engram_id: args2.engram_id, signal: args2.signal, error: `Engram ${args2.engram_id} not found` };
+import * as path13 from "path";
+function findEngram(engramId, engramsPath, packsPath) {
+  const personal = loadEngrams(engramsPath);
+  const found = personal.find((e) => e.id === engramId);
+  if (found) return { engram: found, source: "personal", personalEngrams: personal };
+  const packs = loadAllPacks(packsPath);
+  for (const pack of packs) {
+    const packEngram = pack.engrams.find((e) => e.id === engramId);
+    if (packEngram) {
+      const packId = pack.manifest["x-datacore"]?.id;
+      const packEngramsPath = packId ? path13.join(packsPath, packId, "engrams.yaml") : void 0;
+      return { engram: packEngram, source: "pack", packEngrams: pack.engrams, packEngramsPath };
+    }
+  }
+  return null;
+}
+async function handleFeedback(args2, engramsPath, packsPath) {
+  const pPath = packsPath ?? path13.join(path13.dirname(engramsPath), "packs");
+  if (args2.signals && args2.signals.length > 0) {
+    return handleBatchFeedback(args2.signals, engramsPath, pPath);
+  }
+  return handleSingleFeedback(args2.engram_id, args2.signal, args2.comment, engramsPath, pPath);
+}
+async function handleSingleFeedback(engram_id, signal, comment, engramsPath, packsPath) {
+  const found = findEngram(engram_id, engramsPath, packsPath);
+  if (!found) {
+    return {
+      mode: "single",
+      success: false,
+      engram_id,
+      signal,
+      error: `Engram ${engram_id} not found`,
+      _hints: buildHints({
+        next: "Engram not found. Use datacore.search or datacore.status to find valid IDs.",
+        related: ["datacore.search", "datacore.status"]
+      })
+    };
   }
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  if (engram.activation.last_accessed === today) {
+  if (!found.engram.feedback_signals) {
+    found.engram.feedback_signals = { positive: 0, negative: 0, neutral: 0 };
   }
-  if (!engram.feedback_signals) {
-    engram.feedback_signals = { positive: 0, negative: 0, neutral: 0 };
+  found.engram.feedback_signals[signal] += 1;
+  found.engram.activation.last_accessed = today;
+  if (found.source === "personal" && found.personalEngrams) {
+    atomicWriteYaml(engramsPath, { engrams: found.personalEngrams });
+  } else if (found.source === "pack" && found.packEngrams && found.packEngramsPath) {
+    atomicWriteYaml(found.packEngramsPath, { engrams: found.packEngrams });
   }
-  engram.feedback_signals[args2.signal] += 1;
-  engram.activation.last_accessed = today;
-  atomicWriteYaml(engramsPath, { engrams });
   return {
+    mode: "single",
     success: true,
-    engram_id: args2.engram_id,
-    signal: args2.signal,
-    feedback_signals: { ...engram.feedback_signals }
+    engram_id,
+    signal,
+    source: found.source,
+    feedback_signals: { ...found.engram.feedback_signals }
+  };
+}
+async function handleBatchFeedback(signals, engramsPath, packsPath) {
+  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const results = [];
+  const summary = { positive: 0, negative: 0, neutral: 0 };
+  const personal = loadEngrams(engramsPath);
+  const packs = loadAllPacks(packsPath);
+  let personalDirty = false;
+  const dirtyPackFiles = /* @__PURE__ */ new Map();
+  for (const { engram_id, signal } of signals) {
+    let engram = personal.find((e) => e.id === engram_id);
+    let source;
+    if (engram) {
+      source = "personal";
+    } else {
+      for (const pack of packs) {
+        engram = pack.engrams.find((e) => e.id === engram_id);
+        if (engram) {
+          source = "pack";
+          const packId = pack.manifest["x-datacore"]?.id;
+          if (packId) {
+            dirtyPackFiles.set(
+              path13.join(packsPath, packId, "engrams.yaml"),
+              pack.engrams
+            );
+          }
+          break;
+        }
+      }
+    }
+    if (!engram || !source) {
+      results.push({ engram_id, signal, success: false, error: `Engram ${engram_id} not found` });
+      continue;
+    }
+    if (!engram.feedback_signals) {
+      engram.feedback_signals = { positive: 0, negative: 0, neutral: 0 };
+    }
+    engram.feedback_signals[signal] += 1;
+    engram.activation.last_accessed = today;
+    summary[signal]++;
+    if (source === "personal") personalDirty = true;
+    results.push({ engram_id, signal, success: true, source });
+  }
+  if (personalDirty) {
+    atomicWriteYaml(engramsPath, { engrams: personal });
+  }
+  for (const [filePath, engrams] of dirtyPackFiles) {
+    atomicWriteYaml(filePath, { engrams });
+  }
+  return {
+    mode: "batch",
+    results,
+    summary,
+    _hints: buildHints({
+      next: `Batch feedback recorded: ${summary.positive} positive, ${summary.negative} negative, ${summary.neutral} neutral.`,
+      related: ["datacore.session.end", "datacore.status"]
+    })
+  };
+}
+
+// src/tools/session-start.ts
+import * as fs15 from "fs";
+import * as path14 from "path";
+async function handleSessionStart(args2, storage2, bridge) {
+  let engrams = null;
+  if (args2.task) {
+    const injectResult = await handleInject(
+      { prompt: args2.task, scope: args2.tags?.length ? `tags:${args2.tags.join(",")}` : void 0 },
+      { engramsPath: storage2.engramsPath, packsPath: storage2.packsPath }
+    );
+    if (injectResult.count > 0) {
+      engrams = { text: injectResult.text, count: injectResult.count };
+    }
+  }
+  const { date: today } = localDate();
+  const journalFile = path14.join(storage2.journalPath, `${today}.md`);
+  const journal_today = fs15.existsSync(journalFile) ? fs15.readFileSync(journalFile, "utf8") : null;
+  const allEngrams = loadEngrams(storage2.engramsPath);
+  const pending_candidates = allEngrams.filter((e) => e.status === "candidate").length;
+  const recommendations = [];
+  if (pending_candidates > 0) {
+    recommendations.push(`${pending_candidates} candidate engram(s) awaiting review. Use datacore.promote to activate.`);
+  }
+  if (!journal_today) {
+    recommendations.push("No journal entry today. Use datacore.capture to start one.");
+  }
+  const hints = args2.task ? buildHints({
+    next: "Work on your task. End with datacore.session.end.",
+    related: ["datacore.session.end", "datacore.feedback"]
+  }) : buildHints({
+    next: "No task specified \u2014 showing journal and candidates only. Call datacore.inject when ready.",
+    related: ["datacore.inject", "datacore.session.end"]
+  });
+  const activeCount = allEngrams.filter((e) => e.status === "active").length;
+  const guide = activeCount === 0 ? SESSION_GUIDE_FULL : SESSION_GUIDE_SHORT;
+  return { engrams, journal_today, pending_candidates, recommendations, guide, _hints: hints };
+}
+var SESSION_GUIDE_FULL = `## Datacore Quick Start
+
+Datacore gives you persistent memory through **engrams** \u2014 knowledge that gets injected into context when relevant.
+
+### Session Workflow
+1. **session.start** (you just called this) \u2014 get context
+2. Work on your task. Use **recall** to search everything, **search** for files.
+3. **feedback** \u2014 rate which injected engrams helped (strengthens useful ones)
+4. **session.end** \u2014 capture summary + suggest new engrams
+
+### Key Tools
+- **learn** \u2014 record a reusable insight (creates candidate engram)
+- **promote** \u2014 activate candidate engrams so they appear in future sessions
+- **capture** \u2014 write a journal entry or knowledge note
+- **ingest** \u2014 import text and extract engram suggestions
+- **status** \u2014 system health and actionable recommendations
+- **forget** \u2014 retire an engram you no longer need
+
+### How Engrams Work
+learn \u2192 candidate \u2192 promote \u2192 active \u2192 inject \u2192 feedback \u2192 stronger/weaker
+Positive feedback strengthens engrams. Unused ones naturally decay.`;
+var SESSION_GUIDE_SHORT = `Session started. Workflow: work \u2192 feedback \u2192 session.end.`;
+
+// src/tools/session-end.ts
+async function handleSessionEnd(args2, storage2) {
+  const captureResult = await handleCapture(
+    { type: "journal", content: args2.summary, tags: args2.tags },
+    storage2
+  );
+  let engramsCreated = 0;
+  if (args2.engram_suggestions?.length) {
+    for (const suggestion of args2.engram_suggestions) {
+      await handleLearn(
+        { statement: suggestion.statement, type: suggestion.type },
+        storage2.engramsPath
+      );
+      engramsCreated++;
+    }
+  }
+  const autoPromote = getConfig().engrams.auto_promote;
+  const statusLabel = autoPromote ? "active" : "candidates";
+  return {
+    journal_path: captureResult.path ?? null,
+    engrams_created: engramsCreated,
+    _hints: buildHints({
+      next: engramsCreated > 0 ? `Session captured. ${engramsCreated} engram(s) created as ${statusLabel}.` : "Session captured.",
+      related: ["datacore.session.start", "datacore.status"]
+    })
+  };
+}
+
+// src/tools/recall.ts
+async function handleRecall(args2, storage2, bridge) {
+  const sources = args2.sources ?? ["engrams", "journal", "knowledge"];
+  const limit = args2.limit ?? 10;
+  const result = {};
+  let fallbackWarning;
+  if (sources.includes("engrams")) {
+    const engrams = loadEngrams(storage2.engramsPath);
+    const topicWords = args2.topic.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
+    const scored = [];
+    for (const e of engrams) {
+      if (e.status === "retired") continue;
+      const text = `${e.statement} ${e.tags.join(" ")}`.toLowerCase();
+      let score = 0;
+      for (const word of topicWords) {
+        if (text.includes(word)) score++;
+      }
+      if (score > 0) {
+        scored.push({ id: e.id, statement: e.statement, score });
+      }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    const engramResults = scored.slice(0, limit);
+    if (engramResults.length > 0) {
+      result.engrams = engramResults;
+    }
+  }
+  if (sources.includes("journal")) {
+    const searchResult = await handleSearch(
+      { query: args2.topic, scope: "journal", limit },
+      { journalPath: storage2.journalPath, knowledgePath: storage2.knowledgePath },
+      bridge
+    );
+    if (searchResult.results.length > 0) {
+      result.journal = searchResult.results.map((r) => ({
+        path: r.path,
+        snippet: r.snippet,
+        title: r.title,
+        date: r.date,
+        score: r.score
+      }));
+    }
+    if (searchResult.fallback_warning) {
+      fallbackWarning = searchResult.fallback_warning;
+    }
+  }
+  if (sources.includes("knowledge")) {
+    const searchResult = await handleSearch(
+      { query: args2.topic, scope: "knowledge", limit },
+      { journalPath: storage2.journalPath, knowledgePath: storage2.knowledgePath },
+      bridge
+    );
+    if (searchResult.results.length > 0) {
+      result.knowledge = searchResult.results.map((r) => ({
+        path: r.path,
+        snippet: r.snippet,
+        title: r.title,
+        date: r.date,
+        score: r.score
+      }));
+    }
+    if (searchResult.fallback_warning) {
+      fallbackWarning = searchResult.fallback_warning;
+    }
+  }
+  if (fallbackWarning) {
+    result.fallback_warning = fallbackWarning;
+  }
+  result._hints = buildHints({
+    next: "Use datacore.feedback on helpful engrams, or datacore.learn to create new ones.",
+    related: ["datacore.feedback", "datacore.learn"]
+  });
+  return result;
+}
+
+// src/tools/promote.ts
+async function handlePromote(args2, engramsPath) {
+  const targetIds = args2.ids ?? (args2.id ? [args2.id] : []);
+  if (targetIds.length === 0) {
+    return {
+      success: false,
+      promoted: [],
+      errors: [{ id: "", error: "At least one engram ID required (id or ids)" }],
+      _hints: buildHints({
+        next: "Provide an engram ID. Use datacore.search or datacore.status to find valid IDs.",
+        related: ["datacore.search", "datacore.status"]
+      })
+    };
+  }
+  const engrams = loadEngrams(engramsPath);
+  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const promoted = [];
+  const errors = [];
+  for (const id of targetIds) {
+    const engram = engrams.find((e) => e.id === id);
+    if (!engram) {
+      errors.push({ id, error: "Engram not found" });
+      continue;
+    }
+    if (engram.status === "active") {
+      errors.push({ id, error: "Already active" });
+      continue;
+    }
+    if (engram.status === "retired") {
+      errors.push({ id, error: "Cannot promote retired engram" });
+      continue;
+    }
+    engram.status = "active";
+    engram.activation.retrieval_strength = 0.7;
+    engram.activation.storage_strength = 1;
+    engram.activation.last_accessed = today;
+    promoted.push({ id: engram.id, statement: engram.statement });
+  }
+  if (promoted.length > 0) {
+    atomicWriteYaml(engramsPath, { engrams });
+  }
+  return {
+    success: errors.length === 0,
+    promoted,
+    errors,
+    _hints: buildHints({
+      next: promoted.length > 0 ? `Promoted ${promoted.length} engram(s). They will now appear in inject results.` : "No engrams were promoted. Check the errors above.",
+      related: ["datacore.inject", "datacore.status"]
+    })
   };
 }
 
@@ -1582,8 +2203,8 @@ import {
   ReadResourceRequestSchema,
   ListResourceTemplatesRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-import * as fs14 from "fs";
-import * as path12 from "path";
+import * as fs16 from "fs";
+import * as path15 from "path";
 function registerResources(server, storage2) {
   server.setRequestHandler(ListResourcesRequestSchema, async () => ({
     resources: [
@@ -1604,6 +2225,12 @@ function registerResources(server, storage2) {
         name: "Today's Journal",
         description: "Today's journal entry",
         mimeType: "text/markdown"
+      },
+      {
+        uri: "datacore://guide",
+        name: "Datacore Agent Guide",
+        description: "Workflow guide for AI agents: session lifecycle, engram lifecycle, tool reference",
+        mimeType: "text/markdown"
       }
     ]
   }));
@@ -1646,14 +2273,23 @@ function registerResources(server, storage2) {
         }]
       };
     }
+    if (uri === "datacore://guide") {
+      return {
+        contents: [{
+          uri,
+          mimeType: "text/markdown",
+          text: AGENT_GUIDE
+        }]
+      };
+    }
     const journalMatch = uri.match(/^datacore:\/\/journal\/(.+)$/);
     if (journalMatch) {
       const dateStr = journalMatch[1] === "today" ? localDate().date : journalMatch[1];
-      const filePath = path12.join(storage2.journalPath, `${dateStr}.md`);
-      if (!fs14.existsSync(filePath)) {
+      const filePath = path15.join(storage2.journalPath, `${dateStr}.md`);
+      if (!fs16.existsSync(filePath)) {
         return { contents: [{ uri, mimeType: "text/markdown", text: `No journal entry for ${dateStr}` }] };
       }
-      return { contents: [{ uri, mimeType: "text/markdown", text: fs14.readFileSync(filePath, "utf8") }] };
+      return { contents: [{ uri, mimeType: "text/markdown", text: fs16.readFileSync(filePath, "utf8") }] };
     }
     const engramMatch = uri.match(/^datacore:\/\/engrams\/(.+)$/);
     if (engramMatch) {
@@ -1673,6 +2309,40 @@ function registerResources(server, storage2) {
     throw new Error(`Unknown resource: ${uri}`);
   });
 }
+var AGENT_GUIDE = `# Datacore Agent Guide
+
+## Session Lifecycle
+1. datacore.session.start \u2014 Get relevant engrams + today's context
+2. Work on task, use datacore.recall or datacore.search as needed
+3. datacore.feedback \u2014 Rate which injected engrams helped (batch supported)
+4. datacore.session.end \u2014 Capture summary + engram suggestions
+
+## Engram Lifecycle
+- datacore.learn creates candidate engrams (or active if auto_promote enabled)
+- datacore.promote activates candidates so they appear in inject results
+- datacore.feedback with positive signals strengthens injection priority
+- datacore.forget retires engrams permanently
+- Unused engrams naturally decay over time
+
+## Quick Reference
+| Tool | Purpose |
+|------|---------|
+| session.start | Begin session with context injection |
+| session.end | End session with journal + engrams |
+| learn | Create engram from knowledge statement |
+| promote | Activate candidate engrams |
+| inject | Get relevant engrams for specific task |
+| recall | Search all sources (engrams + journal + knowledge) |
+| capture | Write journal entry or knowledge note |
+| search | Keyword/semantic file search |
+| ingest | Ingest text + extract engram suggestions |
+| feedback | Rate engrams (single or batch) |
+| forget | Retire an engram |
+| status | System health + actionable recommendations |
+| packs.discover | Browse available engram packs |
+| packs.install | Install or upgrade a pack |
+| packs.export | Export engrams as shareable pack |
+`;
 function notifyEngramsChanged(server) {
   try {
     server.sendResourceUpdated?.({ uri: "datacore://engrams/active" });
@@ -1680,10 +2350,178 @@ function notifyEngramsChanged(server) {
   }
 }
 
+// src/prompts.ts
+import {
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+var PROMPTS = [
+  {
+    name: "datacore-session",
+    title: "Start a Datacore session",
+    description: "Begin a working session with Datacore. Injects relevant context, shows today's journal, and guides you through the session lifecycle.",
+    arguments: [
+      { name: "task", description: "What you are working on (optional \u2014 triggers engram injection)", required: false }
+    ],
+    messages: (args2) => [{
+      role: "user",
+      content: {
+        type: "text",
+        text: `Start a new Datacore session.${args2.task ? ` Task: ${args2.task}` : ""}
+
+Call datacore.session.start${args2.task ? ` with task: "${args2.task}"` : ""} to begin. This will:
+- Inject relevant engrams (learned knowledge) for the task
+- Show today's journal entry if one exists
+- List any candidate engrams awaiting review
+
+When done working, call datacore.session.end with a summary and any new learnings.
+
+Session lifecycle:
+1. datacore.session.start \u2192 get context
+2. Work on task (use datacore.recall or datacore.search as needed)
+3. datacore.feedback \u2192 rate which injected engrams were helpful
+4. datacore.session.end \u2192 capture summary + new engrams`
+      }
+    }]
+  },
+  {
+    name: "datacore-learn",
+    title: "Teach Datacore something",
+    description: "Record a reusable learning as an engram. Covers the full engram lifecycle: create, review, activate, reinforce.",
+    arguments: [
+      { name: "statement", description: 'The knowledge to record (e.g., "Always run tests before deploying")', required: true }
+    ],
+    messages: (args2) => [{
+      role: "user",
+      content: {
+        type: "text",
+        text: `Record this learning in Datacore: "${args2.statement || "..."}"
+
+Call datacore.learn with the statement. This creates a candidate engram.
+
+Engram lifecycle:
+1. datacore.learn \u2192 creates candidate (not yet active)
+2. datacore.promote \u2192 activates it so it appears in future inject results
+3. datacore.inject \u2192 retrieves relevant engrams when working on tasks
+4. datacore.feedback \u2192 positive signals strengthen it, negative signals weaken it
+5. datacore.forget \u2192 retires it permanently if no longer useful
+
+Engrams that prove useful get reinforced over time. Unused ones naturally decay.`
+      }
+    }]
+  },
+  {
+    name: "datacore-guide",
+    title: "How to use Datacore",
+    description: "Complete guide to Datacore tools, workflows, and concepts. Read this to understand the system.",
+    messages: () => [{
+      role: "assistant",
+      content: {
+        type: "text",
+        text: `# Datacore \u2014 Persistent Memory for AI
+
+Datacore gives you persistent memory through **engrams** \u2014 typed knowledge units that get injected into context when relevant. You learn patterns, remember preferences, and build on previous work across sessions.
+
+## Core Concepts
+
+**Engrams** are reusable knowledge: "Always validate input at API boundaries", "User prefers tabs over spaces". They have activation dynamics \u2014 frequently useful ones get stronger, unused ones decay.
+
+**Journal** is your session log. Each session captures what happened, what was learned.
+
+**Knowledge** is ingested reference material \u2014 articles, notes, documents broken into searchable pieces.
+
+## Session Workflow
+
+Every session follows this pattern:
+
+1. **datacore.session.start** \u2014 Injects relevant engrams + shows today's journal
+2. **Work** \u2014 Use datacore.recall or datacore.search to find information
+3. **datacore.feedback** \u2014 Rate which engrams were helpful (strengthens good ones)
+4. **datacore.session.end** \u2014 Capture summary + suggest new engrams
+
+## Tool Reference
+
+### Session
+| Tool | What it does |
+|------|-------------|
+| **session.start** | Begin session, inject context, show journal |
+| **session.end** | End session, capture journal + new engrams |
+
+### Core
+| Tool | What it does |
+|------|-------------|
+| **capture** | Write a journal entry or knowledge note |
+| **learn** | Create an engram (starts as candidate) |
+| **promote** | Activate candidate engrams |
+| **inject** | Get relevant engrams for a specific task |
+| **recall** | Search everything (engrams + journal + knowledge) |
+| **search** | Search journal and knowledge files |
+| **ingest** | Ingest text, extract engram suggestions |
+| **status** | System health + actionable recommendations |
+
+### Engram Management
+| Tool | What it does |
+|------|-------------|
+| **feedback** | Rate engrams: positive/negative/neutral (single or batch) |
+| **forget** | Retire an engram permanently |
+
+### Packs (Shareable Knowledge)
+| Tool | What it does |
+|------|-------------|
+| **packs.discover** | Browse available engram packs |
+| **packs.install** | Install a pack |
+| **packs.export** | Export your engrams as a pack |
+
+## Engram Lifecycle
+
+\`\`\`
+learn \u2192 candidate \u2192 promote \u2192 active \u2192 inject \u2192 feedback \u2192 stronger/weaker
+                                                          \u2192 forget (retire)
+\`\`\`
+
+- **candidate**: Created but not yet active. Won't appear in inject results.
+- **active**: Appears in inject results when relevant.
+- **retired**: Permanently removed from injection.
+
+Feedback matters: positive signals increase retrieval strength, negative signals decrease it. Engrams that are never accessed naturally decay over time.
+
+## Tips
+
+- Start every session with **session.start** \u2014 it gives you relevant context
+- End every session with **session.end** \u2014 it captures what you learned
+- Use **feedback** after getting injected engrams \u2014 this is how Datacore learns what's useful
+- Use **recall** for broad searches across all sources, **search** for targeted file searches
+- Check **status** periodically \u2014 it shows actionable recommendations`
+      }
+    }]
+  }
+];
+function registerPrompts(server) {
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: PROMPTS.map((p) => ({
+      name: p.name,
+      title: p.title,
+      description: p.description,
+      arguments: p.arguments
+    }))
+  }));
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name, arguments: promptArgs } = request.params;
+    const prompt = PROMPTS.find((p) => p.name === name);
+    if (!prompt) {
+      throw new Error(`Unknown prompt: ${name}`);
+    }
+    return {
+      description: prompt.description,
+      messages: prompt.messages(promptArgs ?? {})
+    };
+  });
+}
+
 // src/datacortex.ts
 import { execFile } from "child_process";
-import * as fs15 from "fs";
-import * as path13 from "path";
+import * as fs17 from "fs";
+import * as path16 from "path";
 var DatacortexBridge = class {
   pythonPath;
   scriptPath;
@@ -1693,11 +2531,11 @@ var DatacortexBridge = class {
   }
   findBridgeScript(datacorePath) {
     const candidates = [
-      path13.join(datacorePath, ".datacore", "modules", "datacortex", "lib", "bridge.py"),
-      path13.join(datacorePath, ".datacore", "modules", "datacortex", "bridge.py")
+      path16.join(datacorePath, ".datacore", "modules", "datacortex", "lib", "bridge.py"),
+      path16.join(datacorePath, ".datacore", "modules", "datacortex", "bridge.py")
     ];
     for (const candidate of candidates) {
-      if (fs15.existsSync(candidate)) return candidate;
+      if (fs17.existsSync(candidate)) return candidate;
     }
     return null;
   }
@@ -1760,22 +2598,25 @@ var datacortexBridge = null;
 function createServer() {
   const server = new Server(
     { name: "datacore-mcp", version: currentVersion },
-    { capabilities: { tools: {}, logging: {}, resources: { subscribe: true } } }
+    { capabilities: { tools: {}, logging: {}, resources: { subscribe: true }, prompts: {} } }
   );
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [
-      ...TOOLS.map((t) => ({
-        name: t.name,
-        description: t.description,
-        inputSchema: zodToJsonSchema(t.inputSchema)
-      })),
-      ...moduleTools.map((t) => ({
-        name: t.fullName,
-        description: t.definition.description,
-        inputSchema: zodToJsonSchema(t.definition.inputSchema)
-      }))
-    ]
-  }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const coreTools = storage.mode === "core" ? TOOLS.filter((t) => !t.name.startsWith("datacore.modules.")) : TOOLS;
+    return {
+      tools: [
+        ...coreTools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          inputSchema: zodToJsonSchema(t.inputSchema)
+        })),
+        ...moduleTools.map((t) => ({
+          name: t.fullName,
+          description: t.definition.description,
+          inputSchema: zodToJsonSchema(t.definition.inputSchema)
+        }))
+      ]
+    };
+  });
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args2 } = request.params;
     try {
@@ -1795,10 +2636,11 @@ function createServer() {
   });
   logger.setServer(server);
   registerResources(server, storage);
+  registerPrompts(server);
   serverRef = server;
   return server;
 }
-var ENGRAM_MUTATING_TOOLS = /* @__PURE__ */ new Set(["datacore.learn", "datacore.forget", "datacore.feedback"]);
+var ENGRAM_MUTATING_TOOLS = /* @__PURE__ */ new Set(["datacore.learn", "datacore.forget", "datacore.feedback", "datacore.session.end", "datacore.promote"]);
 async function routeTool(name, args2) {
   const coreTool = TOOLS.find((t) => t.name === name);
   if (coreTool) {
@@ -1827,7 +2669,19 @@ async function routeTool(name, args2) {
         result = await handleForget(validated, storage.engramsPath);
         break;
       case "datacore.feedback":
-        result = await handleFeedback(validated, storage.engramsPath);
+        result = await handleFeedback(validated, storage.engramsPath, storage.packsPath);
+        break;
+      case "datacore.session.start":
+        result = await handleSessionStart(validated, storage, datacortexBridge);
+        break;
+      case "datacore.session.end":
+        result = await handleSessionEnd(validated, storage);
+        break;
+      case "datacore.recall":
+        result = await handleRecall(validated, { engramsPath: storage.engramsPath, journalPath: storage.journalPath, knowledgePath: storage.knowledgePath }, datacortexBridge);
+        break;
+      case "datacore.promote":
+        result = await handlePromote(validated, storage.engramsPath);
         break;
       case "datacore.packs.discover":
         result = handleDiscover(validated, storage.packsPath);
@@ -1890,6 +2744,7 @@ async function initStorage() {
     const result = initCore(storage.basePath);
     isFirstRun = result.isFirstRun;
   }
+  loadConfig(storage.basePath, storage.mode);
   if (storage.mode === "full") {
     discoveredModules = discoverModules(storage);
     moduleTools = await loadModuleTools(discoveredModules, storage);