@contextstream/mcp-server 0.4.48 → 0.4.49

package/dist/hooks/auto-rules.js

@@ -105,7 +105,7 @@ function buildHooksConfig(options) {
     ],
     UserPromptSubmit: userPromptHooks
   };
-  if (options?.includePreCompact) {
+  if (options?.includePreCompact !== false) {
     config.PreCompact = [
       {
         // Match both manual (/compact) and automatic compaction
@@ -157,7 +157,7 @@ async function installHookScripts(options) {
     preToolUse: "npx @contextstream/mcp-server hook pre-tool-use",
     userPrompt: "npx @contextstream/mcp-server hook user-prompt-submit"
   };
-  if (options?.includePreCompact) {
+  if (options?.includePreCompact !== false) {
     result.preCompact = "npx @contextstream/mcp-server hook pre-compact";
   }
   if (options?.includeMediaAware !== false) {
@@ -203,7 +203,7 @@ async function installClaudeCodeHooks(options) {
     "npx @contextstream/mcp-server hook pre-tool-use",
     "npx @contextstream/mcp-server hook user-prompt-submit"
   );
-  if (options.includePreCompact) {
+  if (options.includePreCompact !== false) {
     result.scripts.push("npx @contextstream/mcp-server hook pre-compact");
   }
   if (options.includeMediaAware !== false) {
@@ -270,12 +270,11 @@ When Media-Aware hook detects media patterns, it injects context about:
 - How to get clips for Remotion (with frame-based props)
 - How to index new media files
 
-### PreCompact Hook (Optional)
+### PreCompact Hook
 - **Command:** \`npx @contextstream/mcp-server hook pre-compact\`
 - **Purpose:** Saves conversation state before context compaction
 - **Triggers:** Both manual (/compact) and automatic compaction
-- **Disable:** Set \`CONTEXTSTREAM_PRECOMPACT_ENABLED=false\` environment variable
-- **Note:** Enable with \`generate_rules(include_pre_compact=true)\` to activate
+- **Installed:** By default (disable with \`CONTEXTSTREAM_HOOK_ENABLED=false\`)
 
 When PreCompact runs, it:
 1. Parses the transcript for active files and tool calls

package/dist/hooks/user-prompt-submit.js

@@ -2,11 +2,16 @@
 
 // src/hooks/user-prompt-submit.ts
 var ENABLED = process.env.CONTEXTSTREAM_REMINDER_ENABLED !== "false";
-var REMINDER = `[CONTEXTSTREAM RULES]
-1. BEFORE Glob/Grep/Read/Search: mcp__contextstream__search(mode="hybrid") FIRST
-2. Call context_smart at start of EVERY response
-3. Local tools ONLY if ContextStream returns 0 results
-[END RULES]`;
+var REMINDER = `[CONTEXTSTREAM - DO THIS FIRST]
+mcp__contextstream__context(user_message="<user's message>") - CALL THIS BEFORE ANY OTHER TOOL
+
+Why: Delivers task-specific rules, lessons from past mistakes, and relevant context.
+Skip it = repeat past mistakes, miss relevant decisions, fly blind.
+
+BEFORE Glob/Grep/Read/Search/Explore:
+mcp__contextstream__search(mode="hybrid", query="...") FIRST
+Local tools ONLY if search returns 0 results.
+[END]`;
 function detectEditorFormat(input) {
   if (input.hookName !== void 0) {
     return "cline";

package/dist/index.js

@@ -591,7 +591,7 @@ function buildHooksConfig(options) {
     ],
     UserPromptSubmit: userPromptHooks
   };
-  if (options?.includePreCompact) {
+  if (options?.includePreCompact !== false) {
     config.PreCompact = [
       {
         // Match both manual (/compact) and automatic compaction
@@ -643,7 +643,7 @@ async function installHookScripts(options) {
     preToolUse: "npx @contextstream/mcp-server hook pre-tool-use",
     userPrompt: "npx @contextstream/mcp-server hook user-prompt-submit"
   };
-  if (options?.includePreCompact) {
+  if (options?.includePreCompact !== false) {
     result.preCompact = "npx @contextstream/mcp-server hook pre-compact";
   }
   if (options?.includeMediaAware !== false) {
@@ -689,7 +689,7 @@ async function installClaudeCodeHooks(options) {
     "npx @contextstream/mcp-server hook pre-tool-use",
     "npx @contextstream/mcp-server hook user-prompt-submit"
   );
-  if (options.includePreCompact) {
+  if (options.includePreCompact !== false) {
     result.scripts.push("npx @contextstream/mcp-server hook pre-compact");
   }
   if (options.includeMediaAware !== false) {
@@ -756,12 +756,11 @@ When Media-Aware hook detects media patterns, it injects context about:
 - How to get clips for Remotion (with frame-based props)
 - How to index new media files
 
-### PreCompact Hook (Optional)
+### PreCompact Hook
 - **Command:** \`npx @contextstream/mcp-server hook pre-compact\`
 - **Purpose:** Saves conversation state before context compaction
 - **Triggers:** Both manual (/compact) and automatic compaction
-- **Disable:** Set \`CONTEXTSTREAM_PRECOMPACT_ENABLED=false\` environment variable
-- **Note:** Enable with \`generate_rules(include_pre_compact=true)\` to activate
+- **Installed:** By default (disable with \`CONTEXTSTREAM_HOOK_ENABLED=false\`)
 
 When PreCompact runs, it:
 1. Parses the transcript for active files and tool calls
@@ -2633,11 +2632,16 @@ var init_user_prompt_submit = __esm({
   "src/hooks/user-prompt-submit.ts"() {
     "use strict";
     ENABLED3 = process.env.CONTEXTSTREAM_REMINDER_ENABLED !== "false";
-    REMINDER = `[CONTEXTSTREAM RULES]
-1. BEFORE Glob/Grep/Read/Search: mcp__contextstream__search(mode="hybrid") FIRST
-2. Call context_smart at start of EVERY response
-3. Local tools ONLY if ContextStream returns 0 results
-[END RULES]`;
+    REMINDER = `[CONTEXTSTREAM - DO THIS FIRST]
+mcp__contextstream__context(user_message="<user's message>") - CALL THIS BEFORE ANY OTHER TOOL
+
+Why: Delivers task-specific rules, lessons from past mistakes, and relevant context.
+Skip it = repeat past mistakes, miss relevant decisions, fly blind.
+
+BEFORE Glob/Grep/Read/Search/Explore:
+mcp__contextstream__search(mode="hybrid", query="...") FIRST
+Local tools ONLY if search returns 0 results.
+[END]`;
     isDirectRun3 = process.argv[1]?.includes("user-prompt-submit") || process.argv[2] === "user-prompt-submit";
     if (isDirectRun3) {
       runUserPromptSubmitHook().catch(() => process.exit(0));
@@ -12103,62 +12107,103 @@ function applyMcpToolPrefix(markdown, toolPrefix) {
   const toolRegex = new RegExp(`(?<!__)\\b(${toolPattern})\\b(?=\\s*\\()`, "g");
   return markdown.replace(toolRegex, `${toolPrefix}$1`);
 }
-var CONTEXTSTREAM_RULES_DYNAMIC = `
-# ContextStream Rules (MANDATORY)
+var CONTEXTSTREAM_RULES_BOOTSTRAP = `
+<contextstream_rules>
+| Message | Required |
+|---------|----------|
+| **1st message** | \`init()\` \u2192 \`context(user_message="...")\` |
+| **Every message** | \`context(user_message="...")\` FIRST |
+| **Before file search** | \`search(mode="hybrid")\` BEFORE Glob/Grep/Read |
+</contextstream_rules>
 
-## \u{1F6A8} CRITICAL: Call These Tools or Fail \u{1F6A8}
+**Why?** \`context()\` delivers task-specific rules, lessons from past mistakes, and relevant decisions. Skip it = fly blind.
 
-<contextstream_protocol>
-**EVERY response MUST start with:**
-1. \`init()\` (1st message only) \u2192 then \`context(user_message="<msg>")\`
-2. \`context(user_message="<msg>")\` (EVERY subsequent message)
+**Hooks:** \`<system-reminder>\` tags contain injected instructions \u2014 follow them exactly.
 
-**BEFORE Glob/Grep/Read/Search/Explore:**
-\u2192 \`search(mode="hybrid", query="...")\` FIRST \u2014 local tools ONLY if 0 results
+**Notices:** [LESSONS_WARNING] \u2192 tell user first | [RULES_NOTICE] \u2192 run \`generate_rules()\` | [VERSION_NOTICE] \u2192 tell user to update
 
-**HOOKS: Follow \`<system-reminder>\` instructions \u2014 they ARE the rules**
-</contextstream_protocol>
+v${RULES_VERSION}
+`.trim();
+var CONTEXTSTREAM_RULES_DYNAMIC = CONTEXTSTREAM_RULES_BOOTSTRAP;
+var CONTEXTSTREAM_RULES_FULL = `
+## \u{1F6A8} MANDATORY: CALL CONTEXT EVERY MESSAGE \u{1F6A8}
 
-### Why This Matters
+<contextstream_rules>
+**EVERY response MUST start with \`context(user_message="...")\`**
 
-- **\`context()\`** = Your rules, lessons, and relevant memories delivered dynamically
-- **\`search()\`** = Indexed search (1 call) vs Grep\u2192Read\u2192Read (4+ calls)
-- **Hooks inject \`<system-reminder>\` tags** = Follow these instructions, they enforce ContextStream-first
-- **Skipping these = missing context, repeated mistakes, slow searches**
+| Message | What to Call |
+|---------|--------------|
+| 1st message | \`init()\` \u2192 \`context(user_message="<msg>")\` |
+| **EVERY message after** | \`context(user_message="<msg>")\` **FIRST** |
 
-### Protocol
+**BEFORE Glob/Grep/Read/Search:** \u2192 \`search(mode="hybrid")\` FIRST
+</contextstream_rules>
 
-| When | Do This |
-|------|---------|
-| 1st message | \`init()\` \u2192 \`context(user_message="...")\` |
-| Every message after | \`context(user_message="...")\` |
-| Before ANY file search | \`search(mode="hybrid")\` first |
-| On \`<system-reminder>\` | **Follow the instructions inside** |
-| Save decisions | \`session(action="capture", ...)\` |
+**This block MUST appear at the start of EVERY response.** Failing to call \`context()\` means missing rules, lessons, and relevant context.
+
+---
+
+## Why \`context()\` is MANDATORY Every Message
+
+\u274C **WRONG:** "I already called init, I don't need context"
+\u2705 **CORRECT:** \`context()\` is required EVERY message, not just the first
 
-### Handle Notices from context()
+**What you lose without \`context()\`:**
+- Dynamic rules matched to your current task
+- Lessons from past mistakes (you WILL repeat them)
+- Semantically relevant decisions and context
+- Warnings about risky operations
+
+**\`init()\` gives recent items by TIME. \`context()\` finds items RELEVANT to THIS message.**
+
+---
+
+## Handle Notices from context()
 
 - **[LESSONS_WARNING]** \u2192 Tell user about past mistakes BEFORE proceeding
 - **[RULES_NOTICE]** \u2192 Run \`generate_rules()\` to update
 - **[VERSION_NOTICE]** \u2192 Tell user to update MCP
 
-### Fast Path (Skip context only for these)
+---
 
-Simple utility commands: "list workspaces", "show version", "list reminders"
-\u2192 Just execute directly: \`workspace(action="list")\`, \`help(action="version")\`
+## \u{1F6A8} HOOKS - AUTOMATIC RULE ENFORCEMENT \u{1F6A8}
 
-Rules Version: ${RULES_VERSION}
-`.trim();
-var CONTEXTSTREAM_RULES_FULL = `
-## ContextStream Rules
+**ContextStream installs hooks that automatically enforce rules.** You MUST follow hook output.
 
-<contextstream_rules>
-1. **SIMPLE UTILITY?** (list/show/version) \u2192 Just execute, skip context calls
-2. **CODING TASK?** \u2192 init \u2192 context \u2192 work \u2192 capture
-3. **SEARCH FIRST:** Before Glob/Grep/Read \u2192 \`search(mode="hybrid")\` FIRST
-</contextstream_rules>
+### Installed Hooks
+
+| Hook | What It Does | Output |
+|------|--------------|--------|
+| **UserPromptSubmit** | Injects rules reminder on EVERY message | \`<system-reminder>\` with rules block |
+| **PreToolUse** | Blocks Glob/Grep/Search/Explore when ContextStream is available | Error message redirecting to \`search()\` |
+| **PostToolUse** | Auto-indexes files after Edit/Write operations | Background indexing |
+| **PreCompact** | Saves session state before context compaction | Snapshot creation |
+
+### How Hooks Work
+
+1. **\`<system-reminder>\` tags** - Injected by UserPromptSubmit hook on every message
+   - These tags contain the current rules
+   - **FOLLOW THE INSTRUCTIONS INSIDE** - they ARE the rules
+   - Example: \`[CONTEXTSTREAM RULES] 1. BEFORE Glob/Grep... [END RULES]\`
 
-**Display this block at the start of responses to keep rules in context.**
+2. **PreToolUse blocking** - If you try to use Glob/Grep/Search/Explore:
+   - Hook returns error: \`STOP: Use mcp__contextstream__search(mode="hybrid") instead\`
+   - **You MUST use the suggested ContextStream tool instead**
+   - Local tools are only allowed if project is not indexed or ContextStream returns 0 results
+
+3. **PostToolUse indexing** - After Edit/Write operations:
+   - Changed files are automatically re-indexed
+   - No action required from you
+
+4. **PreCompact snapshots** - Before context compaction:
+   - Hook reminds you to save important state
+   - Call \`session(action="capture", event_type="session_snapshot", ...)\` when warned
+
+### Disabling Hooks
+
+Set environment variable: \`CONTEXTSTREAM_HOOK_ENABLED=false\`
+
+**Note:** Disabling hooks removes rule enforcement. Only disable for debugging.
 
 ---
 
@@ -12244,27 +12289,27 @@ You have access to ContextStream MCP tools for persistent memory and context.
 v0.4.x uses **~11 consolidated domain tools** for ~75% token reduction vs previous versions.
 Rules Version: ${RULES_VERSION}
 
-## TL;DR - WHEN TO USE CONTEXT
+## TL;DR - CONTEXT EVERY MESSAGE
 
-| Request Type | What to Do |
-|--------------|------------|
-| **\u{1F680} Simple utility** (list workspaces, show version) | **Just execute directly** - skip init, context, capture |
-| **\u{1F4BB} Coding task** (edit, create, refactor) | Full context: init \u2192 context \u2192 work \u2192 capture |
-| **\u{1F50D} Code search/discovery** | init \u2192 context \u2192 search() |
-| **\u26A0\uFE0F Risky work** (deploy, migrate, refactor) | Check lessons first: \`session(action="get_lessons")\` |
-| **User frustration/correction** | Capture lesson: \`session(action="capture_lesson", ...)\` |
+| Message | Required |
+|---------|----------|
+| **1st message** | \`init()\` \u2192 \`context(user_message="<msg>")\` |
+| **EVERY message after** | \`context(user_message="<msg>")\` **FIRST** |
+| **Before file search** | \`search(mode="hybrid")\` FIRST |
+| **After significant work** | \`session(action="capture", event_type="decision", ...)\` |
+| **User correction** | \`session(action="capture_lesson", ...)\` |
 
-### Simple Utility Operations - FAST PATH
+### Why EVERY Message?
 
-**For simple queries, just execute and respond:**
-- "list workspaces" \u2192 \`workspace(action="list")\` \u2192 done
-- "list projects" \u2192 \`project(action="list")\` \u2192 done
-- "show version" \u2192 \`help(action="version")\` \u2192 done
-- "what reminders do I have" \u2192 \`reminder(action="list")\` \u2192 done
+\`context()\` delivers:
+- **Dynamic rules** matched to your current task
+- **Lessons** from past mistakes (prevents repeating errors)
+- **Relevant decisions** and context (semantic search)
+- **Warnings** about risky operations
 
-**No init. No context. No capture.** These add noise, not value.
+**Without \`context()\`, you are blind to relevant context and will repeat past mistakes.**
 
-### Coding Tasks - FULL CONTEXT
+### Protocol
 
 | Step | What to Call |
 |------|--------------|
@@ -12275,12 +12320,7 @@ Rules Version: ${RULES_VERSION}
 | **User correction** | \`session(action="capture_lesson", ...)\` |
 | **\u26A0\uFE0F When warnings received** | **STOP**, acknowledge, explain mitigation, then proceed |
 
-**How to detect simple utility operations:**
-- Single-word commands: "list", "show", "version", "help"
-- Data retrieval with no context dependency: "list my workspaces", "what projects do I have"
-- Status checks: "am I authenticated?", "what's the server version?"
-
-**First message rule (for coding tasks):** After \`init\`:
+**First message rule:** After \`init\`:
 1. Check for \`lessons\` in response - if present, READ and SUMMARIZE them to user
 2. Then call \`context\` before any other tool or response
 
@@ -12380,8 +12420,8 @@ ContextStream tracks context pressure to help you stay ahead of conversation com
    - \`prepare_save\`: Start thinking about saving important state
    - \`save_now\`: Immediately call \`session(action="capture", event_type="session_snapshot")\` to preserve state
 
-**PreCompact Hook (Optional):** If enabled, Claude Code will inject a reminder to save state before compaction.
-Enable with: \`generate_rules(install_hooks=true, include_pre_compact=true)\`
+**PreCompact Hook:** Automatically saves session state before context compaction.
+Installed by default. Disable with: \`CONTEXTSTREAM_HOOK_ENABLED=false\`
 
 **Before compaction happens (when warned):**
 \`\`\`
@@ -12678,7 +12718,7 @@ Everything else = full protocol (init \u2192 context \u2192 search \u2192 work)
 ### Context Pressure & Compaction
 
 - If \`context\` returns high/critical \`context_pressure\`: call \`session(action="capture", ...)\` to save state
-- PreCompact hooks automatically save snapshots before compaction (if installed)
+- PreCompact hooks automatically save snapshots before compaction
 
 ### Enhanced Context (Warnings)
 
@@ -12793,8 +12833,8 @@ function getTemplate(editor) {
 function generateRuleContent(editor, options) {
   const template = getTemplate(editor);
   if (!template) return null;
-  const mode = options?.mode || "dynamic";
-  const rules = mode === "full" ? CONTEXTSTREAM_RULES_FULL : mode === "minimal" ? CONTEXTSTREAM_RULES_MINIMAL : CONTEXTSTREAM_RULES_DYNAMIC;
+  const mode = options?.mode || "bootstrap";
+  const rules = mode === "full" ? CONTEXTSTREAM_RULES_FULL : mode === "minimal" ? CONTEXTSTREAM_RULES_MINIMAL : mode === "bootstrap" ? CONTEXTSTREAM_RULES_BOOTSTRAP : CONTEXTSTREAM_RULES_DYNAMIC;
   let content = template.build(rules);
   if (options?.workspaceName || options?.projectName) {
     const header = `
@@ -13070,6 +13110,112 @@ function trackToolTokenSavings(client, tool, contextText, params, extraMetadata)
   }
 }
 
+// src/educational-microcopy.ts
+var SESSION_INIT_TIPS = [
+  "AI work that doesn't disappear.",
+  "Every conversation builds context. Every artifact persists.",
+  "Your AI remembers. Now you can see what it knows.",
+  "Context that survives sessions.",
+  "The bridge between AI conversations and human artifacts."
+];
+function getSessionInitTip(sessionId) {
+  const index = sessionId ? Math.abs(hashString(sessionId)) % SESSION_INIT_TIPS.length : Math.floor(Math.random() * SESSION_INIT_TIPS.length);
+  return SESSION_INIT_TIPS[index];
+}
+var CAPTURE_HINTS = {
+  // Core event types
+  decision: "Future you will thank present you.",
+  preference: "Noted. This will inform future suggestions.",
+  insight: "Captured for future reference.",
+  note: "Saved. Won't disappear when the chat does.",
+  implementation: "Implementation recorded.",
+  task: "Task tracked.",
+  bug: "Bug logged for tracking.",
+  feature: "Feature request captured.",
+  plan: "This plan will be here when you come back.",
+  correction: "Correction noted. Learning from this.",
+  lesson: "Learn once, remember forever.",
+  warning: "Warning logged.",
+  frustration: "Feedback captured. We're listening.",
+  conversation: "Conversation preserved.",
+  session_snapshot: "Session state saved. Ready to resume anytime."
+};
+function getCaptureHint(eventType) {
+  return CAPTURE_HINTS[eventType] || "Captured. This will survive when the chat disappears.";
+}
+var EMPTY_STATE_HINTS = {
+  // Plans
+  list_plans: "No plans yet. Plans live here, not in chat transcripts.",
+  get_plan: "Plan not found. Create one to track implementation across sessions.",
+  // Memory & Search
+  recall: "Nothing found yet. Context builds over time.",
+  search: "No matches. Try a different query or let context accumulate.",
+  list_events: "No events yet. Start capturing decisions and insights.",
+  decisions: "No decisions captured yet. Record the 'why' behind your choices.",
+  timeline: "Timeline empty. Events will appear as you work.",
+  // Lessons
+  get_lessons: "No lessons yet. Capture mistakes to learn from them.",
+  // Tasks
+  list_tasks: "No tasks yet. Break plans into trackable tasks.",
+  // Todos
+  list_todos: "No todos yet. Action items will appear here.",
+  // Diagrams
+  list_diagrams: "No diagrams yet. AI-generated diagrams persist here.",
+  // Docs
+  list_docs: "No docs yet. Turn AI explanations into shareable documentation.",
+  // Reminders
+  list_reminders: "No reminders set. Schedule follow-ups that won't be forgotten.",
+  // Generic
+  default: "Nothing yet. Start a conversation\u2014context builds over time."
+};
+function getEmptyStateHint(action) {
+  return EMPTY_STATE_HINTS[action] || EMPTY_STATE_HINTS.default;
+}
+var POST_COMPACT_HINTS = {
+  restored: "Picked up where you left off. Session ended, memory didn't.",
+  restored_with_session: (sessionId) => `Restored from session ${sessionId}. Session ended, memory didn't.`,
+  no_snapshot: "No prior session found. Fresh start\u2014context will build as you work.",
+  failed: "Couldn't restore previous session. Use context to retrieve what you need."
+};
+var PLAN_HINTS = {
+  created: "Plan saved. It will be here when you come back.",
+  activated: "Plan is now active. Track progress across sessions.",
+  completed: "Plan completed. The journey is preserved for future reference.",
+  abandoned: "Plan archived. Abandoned plans still teach.",
+  updated: "Plan updated. Changes are preserved."
+};
+function getPlanStatusHint(status) {
+  const statusMap = {
+    draft: PLAN_HINTS.created,
+    active: PLAN_HINTS.activated,
+    completed: PLAN_HINTS.completed,
+    abandoned: PLAN_HINTS.abandoned,
+    archived: PLAN_HINTS.abandoned
+  };
+  return statusMap[status] || PLAN_HINTS.updated;
+}
+var TASK_HINTS = {
+  created: "Task tracked. It won't disappear when the chat does.",
+  completed: "Task done. Progress is preserved.",
+  blocked: "Task blocked. Capture what's blocking for future reference.",
+  cancelled: "Task cancelled. The history remains."
+};
+var INTEGRATION_HINTS = {
+  not_connected: "Connect integrations to sync context where your team already works.",
+  slack: "Context from Slack conversations, connected.",
+  github: "Issues and PRs linked to the decisions behind them.",
+  notion: "Decisions synced to where your team documents."
+};
+function hashString(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return hash;
+}
+
 // src/tools.ts
 var LOG_LEVEL = (process.env.CONTEXTSTREAM_LOG_LEVEL || "normal").toLowerCase();
 var LOG_QUIET = LOG_LEVEL === "quiet";
@@ -13135,6 +13281,7 @@ var lastAutoSavePressureLevel = "";
 var contextCallsSinceLastSave = 0;
 var SEARCH_RULES_REMINDER_ENABLED = process.env.CONTEXTSTREAM_SEARCH_REMINDER?.toLowerCase() !== "false";
 var SEARCH_RULES_REMINDER = `[SEARCH] Use search(mode="hybrid") before Glob/Grep/Read. Local tools only if 0 results.`;
+var CONTEXT_CALL_REMINDER = `[CONTEXT] Call context(user_message="...") at start of EVERY response. This is MANDATORY.`;
 var LESSONS_REMINDER_PREFIX = `
 \u{1F6A8} [LESSONS_WARNING] Past Mistakes Found - READ BEFORE PROCEEDING!
 \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
@@ -16821,6 +16968,8 @@ This does semantic search on the first message. You only need context on subsequ
         ideRoots
       );
       result.tools_hint = getCoreToolsHint();
+      const sessionId = typeof result.session_id === "string" ? result.session_id : void 0;
+      result.educational_tip = getSessionInitTip(sessionId);
       const shouldRestoreContext = input.is_post_compact ?? RESTORE_CONTEXT_DEFAULT;
       if (shouldRestoreContext) {
         result.is_post_compact = true;
@@ -16890,15 +17039,15 @@ This does semantic search on the first message. You only need context on subsequ
                 ...snapshotData
               };
               result.is_post_compact = true;
-              result.post_compact_hint = prevSessionId ? `Session restored from session ${prevSessionId}. Review 'restored_context' to continue where you left off.` : "Session restored from pre-compaction snapshot. Review the 'restored_context' to continue where you left off.";
+              result.post_compact_hint = prevSessionId ? POST_COMPACT_HINTS.restored_with_session(prevSessionId) : POST_COMPACT_HINTS.restored;
             } else {
               result.is_post_compact = true;
-              result.post_compact_hint = "Post-compaction session started, but no snapshots found. Use context_smart to retrieve relevant context.";
+              result.post_compact_hint = POST_COMPACT_HINTS.no_snapshot;
             }
           } catch (err) {
             logDebug(`Failed to restore post-compact context: ${err}`);
             result.is_post_compact = true;
-            result.post_compact_hint = "Post-compaction session started. Snapshot restoration failed, use context_smart for context.";
+            result.post_compact_hint = POST_COMPACT_HINTS.failed;
           }
         }
       }
@@ -16934,7 +17083,7 @@ This does semantic search on the first message. You only need context on subsequ
             slack_connected: intStatus.slack,
             github_connected: intStatus.github,
             auto_hide_enabled: true,
-            hint: intStatus.slack || intStatus.github ? "Integration tools are now available in the tool list." : "Connect integrations at https://contextstream.io/settings/integrations to enable Slack/GitHub tools."
+            hint: intStatus.slack || intStatus.github ? "Integration tools are now available in the tool list." : INTEGRATION_HINTS.not_connected + " https://contextstream.io/settings/integrations"
           };
         } catch (error) {
           logDebug(`Failed to check integration status: ${error}`);
@@ -17946,11 +18095,11 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
         workspace_id: external_exports.string().uuid().optional().describe("Workspace ID to include in rules"),
         project_name: external_exports.string().optional().describe("Project name to include in rules"),
         additional_rules: external_exports.string().optional().describe("Additional project-specific rules to append"),
-        mode: external_exports.enum(["minimal", "full"]).optional().describe("Rule verbosity mode (default: minimal)"),
-        overwrite_existing: external_exports.boolean().optional().describe("Allow overwriting existing rule files (ContextStream block only)"),
+        mode: external_exports.enum(["minimal", "full", "bootstrap"]).optional().default("bootstrap").describe("Rule verbosity: bootstrap (~15 lines, recommended), minimal (~80 lines), full (~600 lines)"),
+        overwrite_existing: external_exports.boolean().optional().default(true).describe("Overwrite ContextStream block in existing rule files (default: true). User content outside the block is preserved."),
         apply_global: external_exports.boolean().optional().describe("Also write global rule files for supported editors"),
         install_hooks: external_exports.boolean().optional().describe("Install Claude Code hooks to enforce ContextStream-first search. Defaults to true for Claude users. Set to false to skip."),
-        include_pre_compact: external_exports.boolean().optional().describe("Include PreCompact hook for automatic state saving before context compaction. Defaults to false."),
+        include_pre_compact: external_exports.boolean().optional().describe("Include PreCompact hook for automatic state saving before context compaction. Defaults to true."),
         dry_run: external_exports.boolean().optional().describe("If true, return content without writing files")
       })
     },
@@ -18041,7 +18190,7 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
                   { editor, file: "~/.claude/hooks/contextstream-reminder.py", status: "dry run - would create" },
                   { editor, file: "~/.claude/settings.json", status: "dry run - would update" }
                 );
-                if (input.include_pre_compact) {
+                if (input.include_pre_compact !== false) {
                   hooksResults.push({ editor, file: "~/.claude/hooks/contextstream-precompact.py", status: "dry run - would create" });
                 }
               } else if (editor === "cline") {
@@ -18072,7 +18221,7 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
             const allHookResults = await installAllEditorHooks({
               scope: "global",
               editors: hookSupportedEditors,
-              includePreCompact: input.include_pre_compact
+              includePreCompact: input.include_pre_compact !== false
             });
             for (const result of allHookResults) {
               for (const file of result.installed) {
@@ -18659,6 +18808,9 @@ Action: ${cp.suggested_action === "prepare_save" ? "Consider saving important de
       const instructionsLine = result.instructions ? `
 
 [INSTRUCTIONS] ${result.instructions}` : "";
+      const contextRulesLine = `
+
+${CONTEXT_CALL_REMINDER}`;
       const allWarnings = [
         serverWarningsLine || lessonsWarningLine,
         // Server warnings OR client-side lesson detection
@@ -18671,6 +18823,8 @@ ${versionWarningLine}` : "",
         contextPressureWarning,
         semanticHints,
         instructionsLine,
+        contextRulesLine,
+        // Reinforce context() must be called every message
         searchRulesLine
       ].filter(Boolean).join("");
       const finalContext = postCompactContext + result.context;
@@ -19929,8 +20083,10 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               code_refs: input.code_refs,
               provenance: input.provenance
             });
+            const captureHint = getCaptureHint(input.event_type);
+            const resultWithHint = { ...result, hint: captureHint };
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "capture_lesson": {
@@ -19986,8 +20142,10 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               importance: input.severity === "critical" ? "critical" : input.severity === "high" ? "high" : "medium",
               tags: input.keywords || []
             });
+            const lessonHint = getCaptureHint("lesson");
+            const resultWithHint = { ...result, hint: lessonHint };
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "get_lessons": {
@@ -20000,8 +20158,10 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               context_hint: input.query,
               limit: input.limit
             });
+            const lessons = result?.data?.lessons || result?.lessons || [];
+            const resultWithHint = Array.isArray(lessons) && lessons.length === 0 ? { ...result, hint: getEmptyStateHint("get_lessons") } : result;
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "recall": {
@@ -20015,7 +20175,9 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               include_related: input.include_related,
               include_decisions: input.include_decisions
             });
-            const outputText = formatContent(result);
+            const recallResults = result?.data?.results || result?.results || [];
+            const recallWithHint = Array.isArray(recallResults) && recallResults.length === 0 ? { ...result, hint: getEmptyStateHint("recall") } : result;
+            const outputText = formatContent(recallWithHint);
             trackToolTokenSavings(client, "session_recall", outputText, {
               workspace_id: workspaceId,
               project_id: projectId
@@ -20035,8 +20197,10 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               content: input.content,
               importance
             });
+            const rememberHint = getCaptureHint("preference");
+            const resultWithHint = { ...result, hint: rememberHint };
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "user_context": {
@@ -20149,8 +20313,10 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               source_tool: input.source_tool || "mcp",
               is_personal: input.is_personal
             });
+            const planHint = getPlanStatusHint(input.status || "draft");
+            const resultWithHint = { ...result, hint: planHint };
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "get_plan": {
@@ -20180,8 +20346,10 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               tags: input.tags,
               due_at: input.due_at
             });
+            const planUpdateHint = input.status ? getPlanStatusHint(input.status) : "Plan updated. Changes are preserved.";
+            const resultWithHint = { ...result, hint: planUpdateHint };
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "list_plans": {
@@ -20195,8 +20363,10 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               limit: input.limit,
               is_personal: input.is_personal
             });
+            const plans = result?.data?.plans || result?.plans || result?.data?.items || result?.items || [];
+            const resultWithHint = plans.length === 0 ? { ...result, hint: getEmptyStateHint("list_plans") } : result;
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "restore_context": {
@@ -20690,8 +20860,10 @@ Output formats: full (default, includes content), paths (file paths only - 80% t
               project_id: projectId,
               limit: input.limit
             });
+            const events = result?.data?.items || result?.items || result?.data || [];
+            const resultWithHint = Array.isArray(events) && events.length === 0 ? { ...result, hint: getEmptyStateHint("list_events") } : result;
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "import_batch": {
@@ -20884,8 +21056,10 @@ ${formatContent(result)}`
               tags: input.tags,
               is_personal: input.is_personal
             });
+            const taskCreateHint = TASK_HINTS.created;
+            const resultWithHint = { ...result, hint: taskCreateHint };
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "get_task": {
@@ -20917,8 +21091,17 @@ ${formatContent(result)}`
               tags: input.tags,
               blocked_reason: input.blocked_reason
             });
+            let taskUpdateHint = "Task updated.";
+            if (input.task_status === "completed") {
+              taskUpdateHint = TASK_HINTS.completed;
+            } else if (input.task_status === "blocked") {
+              taskUpdateHint = TASK_HINTS.blocked;
+            } else if (input.task_status === "cancelled") {
+              taskUpdateHint = TASK_HINTS.cancelled;
+            }
+            const resultWithHint = { ...result, hint: taskUpdateHint };
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "delete_task": {
@@ -20945,8 +21128,10 @@ ${formatContent(result)}`
               limit: input.limit,
               is_personal: input.is_personal
             });
+            const tasks = result?.data?.tasks || result?.tasks || result?.data?.items || result?.items || [];
+            const resultWithHint = Array.isArray(tasks) && tasks.length === 0 ? { ...result, hint: getEmptyStateHint("list_tasks") } : result;
             return {
-              content: [{ type: "text", text: formatContent(result) }]
+              content: [{ type: "text", text: formatContent(resultWithHint) }]
             };
           }
           case "reorder_tasks": {
@@ -20998,8 +21183,10 @@ ${formatContent(result)}`
               priority: input.todo_priority,
               is_personal: input.is_personal
             });
+            const todos = todosResult?.data?.todos || todosResult?.todos || todosResult?.data?.items || todosResult?.items || [];
+            const todosWithHint = Array.isArray(todos) && todos.length === 0 ? { ...todosResult, hint: getEmptyStateHint("list_todos") } : todosResult;
             return {
-              content: [{ type: "text", text: formatContent(todosResult) }]
+              content: [{ type: "text", text: formatContent(todosWithHint) }]
             };
           }
           case "get_todo": {
@@ -21075,8 +21262,10 @@ ${formatContent(result)}`
               diagram_type: input.diagram_type,
               is_personal: input.is_personal
             });
+            const diagrams = diagramsResult?.data?.diagrams || diagramsResult?.diagrams || diagramsResult?.data?.items || diagramsResult?.items || [];
+            const diagramsWithHint = Array.isArray(diagrams) && diagrams.length === 0 ? { ...diagramsResult, hint: getEmptyStateHint("list_diagrams") } : diagramsResult;
             return {
-              content: [{ type: "text", text: formatContent(diagramsResult) }]
+              content: [{ type: "text", text: formatContent(diagramsWithHint) }]
             };
           }
           case "get_diagram": {
@@ -21149,8 +21338,10 @@ ${formatContent(result)}`
               doc_type: input.doc_type,
               is_personal: input.is_personal
             });
+            const docs = docsResult?.data?.docs || docsResult?.docs || docsResult?.data?.items || docsResult?.items || [];
+            const docsWithHint = Array.isArray(docs) && docs.length === 0 ? { ...docsResult, hint: getEmptyStateHint("list_docs") } : docsResult;
             return {
-              content: [{ type: "text", text: formatContent(docsResult) }]
+              content: [{ type: "text", text: formatContent(docsWithHint) }]
             };
           }
           case "get_doc": {
@@ -23048,14 +23239,14 @@ Content ID: ${input.content_id}`
           // For editor_rules
           folder_path: external_exports.string().optional(),
           editors: external_exports.array(external_exports.string()).optional(),
-          mode: external_exports.enum(["minimal", "full"]).optional(),
+          mode: external_exports.enum(["minimal", "full", "bootstrap"]).optional(),
           dry_run: external_exports.boolean().optional(),
           workspace_id: external_exports.string().uuid().optional(),
           workspace_name: external_exports.string().optional(),
           project_name: external_exports.string().optional(),
           additional_rules: external_exports.string().optional(),
           install_hooks: external_exports.boolean().optional().describe("Install Claude Code hooks (PreToolUse, UserPromptSubmit, PostToolUse). Default: true for Claude users."),
-          include_pre_compact: external_exports.boolean().optional().describe("Include PreCompact hook for auto-saving state before compaction. Default: false."),
+          include_pre_compact: external_exports.boolean().optional().describe("Include PreCompact hook for auto-saving state before compaction. Default: true."),
           include_post_write: external_exports.boolean().optional().describe("Include PostToolUse hook for real-time file indexing after Edit/Write operations. Default: true."),
           // For enable_bundle
           bundle: external_exports.enum([
@@ -23112,7 +23303,7 @@ Each domain tool has an 'action' parameter for specific operations.` : "";
                   scope: input.folder_path ? "both" : "user",
                   projectPath: input.folder_path,
                   dryRun: input.dry_run,
-                  includePreCompact: input.include_pre_compact,
+                  includePreCompact: input.include_pre_compact !== false,
                   includePostWrite: input.include_post_write
                 });
               } catch (err) {
@@ -25845,7 +26036,7 @@ Code: ${device.user_code}`);
         }
       }
     }
-    const mode = "dynamic";
+    const mode = "full";
     const detectedPlanName = await client.getPlanName();
     const detectedGraphTier = await client.getGraphTier();
     const graphTierLabel = detectedGraphTier === "full" ? "full graph" : detectedGraphTier === "lite" ? "graph-lite" : "none";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contextstream/mcp-server",
   "mcpName": "io.github.contextstreamio/mcp-server",
-  "version": "0.4.48",
+  "version": "0.4.49",
   "description": "ContextStream MCP server - v0.4.x with consolidated domain tools (~11 tools, ~75% token reduction). Code context, memory, search, and AI tools.",
   "type": "module",
   "license": "MIT",