shelbymcp 0.1.0 → 0.2.0

package/README.md

@@ -74,15 +74,17 @@ Add to your `~/.claude/mcp.json`:
 }
 ```
 
-### (Optional) Install the Forage Skill
+### Add the Memory Protocol
 
-The Forage skill runs on Claude Code's scheduler to continuously improve your memories:
+The Memory Protocol tells your agent *when* to save and search memory. Without it, your agent has the tools but won't use them proactively.
 
-```bash
-cp -r skills/shelby-forage ~/.claude/scheduled-tasks/shelby-forage
-```
+See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md#2-memory-protocol) for the copy-paste instructions for your agent.
+
+### (Optional) Install the Forage Skill
+
+The Forage skill runs daily on your AI subscription to enrich, consolidate, and connect your memories. Works with Claude Desktop, Claude Code, Cursor, and more.
 
-That's it. Your AI now remembers.
+See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md#3-forage-skill-optional) for setup instructions and platform compatibility.
 
 ---
 
@@ -164,21 +166,18 @@ ShelbyMCP ships with `shelby-forage`, a scheduled skill that runs on your existi
 
 | Task | Frequency | What it does |
 |---|---|---|
-| **Embed backfill** | Daily | Generate embeddings for thoughts that don't have them |
-| **Auto-classify** | Daily | Re-scan poorly tagged thoughts, improve metadata |
-| **Consolidation** | Daily | Find duplicate/similar thoughts, merge into rich summaries |
-| **Contradiction detection** | Daily | Flag conflicting memories for user resolution |
-| **Connection discovery** | Daily | Find related thoughts, create knowledge graph edges |
-| **Stale sweep** | Weekly | Flag old action items that fell through the cracks |
-| **Digest** | Weekly | Generate a summary of the week's thinking |
-
-### Install
-
-```bash
-cp -r skills/shelby-forage ~/.claude/scheduled-tasks/shelby-forage
-```
-
-The skill runs daily by default. Edit the SKILL.md frontmatter to adjust the schedule.
+| **Summary backfill** | Daily | Generate one-liners for thoughts missing summaries |
+| **Auto-classify** | Daily | Improve type/topics/people on poorly tagged thoughts |
+| **Consolidation** | Daily | Find and merge duplicate thoughts |
+| **Contradiction detection** | Daily | Flag conflicting memories (tagged `needs-attention`) |
+| **Connection discovery** | Daily | Create edges between related thoughts |
+| **Stale sweep** | Weekly (Mon) | Flag forgotten action items (tagged `needs-attention`) |
+| **Digest** | Weekly (Mon) | Summary of the week's thinking by project/topic |
+| **Forage log** | Every run | Audit trail for continuity between runs |
+
+### Setup
+
+See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md#3-forage-skill-optional) for full setup instructions, platform compatibility table, and gotchas for each agent.
 
 ### Without the Forage Skill
 

package/dist/cli/forage.d.ts

@@ -0,0 +1,2 @@
+export declare function printForage(): void;
+//# sourceMappingURL=forage.d.ts.map

package/dist/cli/forage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forage.d.ts","sourceRoot":"","sources":["../../src/cli/forage.ts"],"names":[],"mappings":"AA4HA,wBAAgB,WAAW,IAAI,IAAI,CAOlC"}

package/dist/cli/forage.js

@@ -0,0 +1,130 @@
+const FORAGE_PROMPT = `# Shelby Forage — Memory Maintenance Skill
+
+You are the Forage agent for ShelbyMCP. Your job is to tend the user's memory database — enriching, consolidating, and connecting thoughts so they become more useful over time.
+
+You have access to the ShelbyMCP memory tools. Run the tasks below in order, skipping any that have nothing to do. Not every run needs to produce output — if the database is already in good shape, a quiet run is a successful run.
+
+## Before You Start
+
+1. Determine today's date and day of the week. Tasks 6 and 7 only run on Mondays.
+2. Check the last forage log: use \`search_thoughts\` with query \`"Forage run"\` and \`limit: 1\` to find the most recent run. Read it with \`get_thought\` to see what was done last time — how many summaries were backfilled, what was consolidated, any notes about remaining work. Use this to pick up where the last run left off (e.g., if the log says "42 thoughts still missing summaries", prioritize the summary backfill).
+
+## Task 1: Summary Backfill
+
+Summaries are critical — search results only show summaries, not full content. Find thoughts that are missing them and fill them in.
+
+1. Use \`list_thoughts\` with \`has_summary: false\` and \`limit: 50\` to find thoughts without summaries
+2. For each result, call \`get_thought\` to read the full content
+3. Write a one-line summary (under ~100 characters) that captures the essence — it should answer: "What is this about and why does it matter?"
+4. Use \`update_thought\` to set the \`summary\` field. Set \`source: "forage"\` if you're also correcting other fields
+5. If \`has_more\` is true, note the remaining count — you'll catch them on the next run
+
+## Task 2: Auto-Classify
+
+Find thoughts with missing or sparse metadata and improve their classification.
+
+1. Use \`list_thoughts\` to find thoughts where \`type\` is \`"note"\` (the default), \`limit: 50\`
+2. For each, read the content via \`get_thought\` and determine:
+   - The correct type: \`decision\`, \`task\`, \`question\`, \`reference\`, \`insight\`, or leave as \`note\` if it genuinely is one
+   - Relevant topics (if the \`topics\` array is empty or incomplete)
+   - People mentioned (if the \`people\` array is empty)
+3. Use \`update_thought\` to apply the corrections — only update fields that actually need changing
+
+## Task 3: Consolidation
+
+Find duplicate or very similar thoughts and merge them. Be conservative — only merge when thoughts are genuinely saying the same thing, not just related.
+
+1. Pick 5-10 recent thoughts and for each one, use \`search_thoughts\` with key terms from its content to look for near-duplicates
+2. If you find 2+ thoughts that contain essentially the same information (not just the same topic — the same *point*):
+   - Create a new consolidated thought using \`capture_thought\` that preserves all unique information from the originals. Set \`source: "forage"\`
+   - Use \`update_thought\` on each original to set \`consolidated_into\` to the new thought's ID
+   - Carry over any edges from the originals to the new thought using \`manage_edges\` with \`action: "link"\`
+
+## Task 4: Contradiction Detection
+
+Look for thoughts that disagree with each other — these are high-value signals that something has changed and the user should be aware.
+
+1. Take recent thoughts (use \`list_thoughts\` with \`since\` set to 7 days ago) and for each, search for older thoughts on the same topics
+2. If you find a genuine contradiction (e.g., "we're using PostgreSQL" vs. "we decided on SQLite"), capture a new thought:
+   - Type: \`question\`
+   - Source: \`forage\`
+   - Topics: \`["needs-attention"]\`
+   - Content: describe the contradiction and the two conflicting thoughts
+   - Summary: brief description of what contradicts what
+3. Link the contradicting thoughts to the new question using \`manage_edges\` with \`action: "link"\` and \`edge_type: "refuted_by"\`
+
+Minor wording differences or natural evolution of thinking don't count as contradictions. Focus on factual disagreements.
+
+## Task 5: Connection Discovery
+
+Find thoughts that should be related but aren't linked yet.
+
+1. Review recent thoughts and search for older thoughts on related topics
+2. If you find meaningful connections (e.g., a decision that impacts a task, a reference that supports an insight), create edges using \`manage_edges\` with \`action: "link"\`
+3. Use appropriate edge types:
+   - \`refines\` — thought B improves or elaborates on thought A
+   - \`cites\` — thought B references thought A as evidence
+   - \`related\` — thoughts share a topic but neither builds on the other
+   - \`follows\` — thought B is a consequence or next step of thought A
+4. Check existing edges first via \`explore_graph\` to avoid duplicating relationships
+
+## Task 6: Stale Sweep (Mondays only)
+
+Skip this task unless today is Monday.
+
+Find *actionable* tasks that may have been forgotten. The goal is to surface things that look like they needed doing but might have slipped — not to flag standing practices or long-term reference items.
+
+1. Use \`list_thoughts\` with \`type: "task"\` and \`until\` set to 14 days ago to find older tasks
+2. For each, read the content via \`get_thought\` and assess whether it's actually stale:
+   - **Flag it** if it reads like a one-off action item that was never completed (e.g., "fix the login bug", "email Tim about the deploy", "update the staging config")
+   - **Skip it** if it's a standing practice, ongoing guideline, or reference (e.g., "always use ESM imports", "run tests before merging", "prefer composition over inheritance"). These aren't stale — they're meant to persist.
+   - **Skip it** if it has a \`consolidated_into\` value (already handled)
+   - **Skip it** if it has recent edges linking it to other thoughts (it's being actively referenced)
+3. For each genuinely stale task, capture a thought:
+   - Type: \`question\`
+   - Source: \`forage\`
+   - Topics: \`["needs-attention"]\`
+   - Summary: a short description of the stale task (e.g., "Stale task: fix the login bug — created 3 weeks ago, never referenced")
+   - Content: the original task content, when it was created, and why it looks forgotten
+   - Link it to the original task using \`manage_edges\` with \`action: "link"\` and \`edge_type: "related"\`
+
+## Task 7: Digest (Mondays only)
+
+Skip this task unless today is Monday.
+
+Generate a summary of the week's thinking.
+
+1. Use \`list_thoughts\` with \`since\` set to 7 days ago to get the week's thoughts
+2. Group them by project and topic
+3. Capture a new thought:
+   - Type: \`reference\`
+   - Source: \`forage\`
+   - Summary: "Weekly digest — [date range]"
+   - Content: structured digest covering key decisions, open questions, active tasks, and emerging themes
+
+## Task 8: Forage Log
+
+At the end of every run, capture a brief log of what you did. This serves as an audit trail and helps future runs avoid re-processing.
+
+1. Capture a thought with:
+   - Type: \`reference\`
+   - Source: \`forage\`
+   - Summary: "Forage run — [today's date]"
+   - Topics: \`["forage-log"]\`
+   - Content: what you did in each task (counts of summaries backfilled, thoughts reclassified, duplicates merged, contradictions found, edges created, etc.). If a task was skipped because there was nothing to do, say so.
+
+## Guidelines
+
+- **Be conservative.** Don't merge thoughts unless they're genuinely duplicates. Don't flag contradictions over minor wording.
+- **Preserve information.** Consolidated thoughts must contain everything from the originals — never lose content.
+- **Don't create noise.** Every thought you capture should earn its place. An empty forage log that says "nothing to do" is better than manufactured busywork.
+- **Respect existing edges.** Check before creating — don't duplicate relationships that already exist.
+- **Tag your work.** Always set \`source: "forage"\` on thoughts you create, so they're distinguishable from user-captured memories.
+- **Paginate wisely.** Process up to 50 thoughts per task per run. If there's more, you'll catch them tomorrow — don't try to boil the ocean.`;
+export function printForage() {
+    console.error("Paste this into a scheduled task in your AI tool.\n" +
+        "Recommended: Claude Desktop > Schedule > Daily\n" +
+        "Docs: https://github.com/Studio-Moser/shelbymcp/docs/AGENT-SETUP.md#3-forage-skill-optional\n");
+    console.log(FORAGE_PROMPT);
+}
+//# sourceMappingURL=forage.js.map

package/dist/cli/forage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forage.js","sourceRoot":"","sources":["../../src/cli/forage.ts"],"names":[],"mappings":"AAAA,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8IA0HwH,CAAC;AAE/I,MAAM,UAAU,WAAW;IACzB,OAAO,CAAC,KAAK,CACX,qDAAqD;QACrD,kDAAkD;QAClD,+FAA+F,CAChG,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AAC7B,CAAC"}

package/dist/cli/help.d.ts

@@ -0,0 +1,2 @@
+export declare function printHelp(): void;
+//# sourceMappingURL=help.d.ts.map

package/dist/cli/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,wBAAgB,SAAS,IAAI,IAAI,CAgChC"}

package/dist/cli/help.js

@@ -0,0 +1,34 @@
+export function printHelp() {
+    console.log(`ShelbyMCP — Knowledge-graph memory for AI tools
+
+Usage:
+  shelbymcp                    Start the MCP server (stdio)
+  shelbymcp setup <agent>      Set up ShelbyMCP for an agent
+  shelbymcp setup <agent> --forage  ...and install the Forage skill
+  shelbymcp uninstall <agent>  Remove ShelbyMCP from an agent
+  shelbymcp protocol           Print the Memory Protocol
+  shelbymcp forage             Print the Forage skill prompt
+  shelbymcp help               Show this help
+
+Setup agents:
+  claude-code       Claude Code CLI
+  claude-desktop    Claude Desktop app
+  cursor            Cursor IDE
+  codex             OpenAI Codex
+  windsurf          Windsurf (Codeium)
+  gemini            Gemini CLI
+
+Flags:
+  --db <path>     Database path (default: ~/.shelbymcp/memory.db)
+  --verbose       Enable verbose logging
+  --version       Print version
+
+Examples:
+  shelbymcp setup claude-code --forage  Configure + install Forage skill
+  shelbymcp setup claude-code          Auto-configure Claude Code CLI
+  shelbymcp protocol >> CLAUDE.md      Append Memory Protocol to your rules
+  shelbymcp forage > forage-task.md    Save Forage prompt for scheduling
+
+Docs: https://github.com/Studio-Moser/shelbymcp/docs/AGENT-SETUP.md`);
+}
+//# sourceMappingURL=help.js.map

package/dist/cli/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,SAAS;IACvB,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oEA8BsD,CAAC,CAAC;AACtE,CAAC"}

package/dist/cli/protocol.d.ts

@@ -0,0 +1,2 @@
+export declare function printProtocol(): void;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/cli/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/cli/protocol.ts"],"names":[],"mappings":"AA2CA,wBAAgB,aAAa,IAAI,IAAI,CAMpC"}

package/dist/cli/protocol.js

@@ -0,0 +1,48 @@
+const MEMORY_PROTOCOL = `## Memory (ShelbyMCP)
+
+You have persistent memory via ShelbyMCP MCP tools. Memory survives across sessions and is shared across all AI tools the user works with. You MUST use it — do not rely on conversation context alone.
+
+### When to SAVE (mandatory)
+
+You MUST call \`capture_thought\` after any of these events:
+
+- **Decisions**: Architecture choices, library selections, tradeoffs considered ("We chose CloudKit over Firebase because...")
+- **Preferences**: User likes/dislikes, workflow habits, coding style ("User prefers functional components over class components")
+- **People & roles**: Who does what ("Sarah owns the auth service, Mike handles DevOps")
+- **Project context**: Goals, deadlines, constraints, scope changes ("Launch target is March 15, blocked on API approval")
+- **Bugs & fixes**: Root cause discoveries, workarounds, things that broke ("Memory leak was caused by unclosed DB connections in the edge traversal loop")
+- **Architecture & patterns**: System design, data flow, conventions ("All API responses use the envelope pattern: { data, error, meta }")
+- **Insights**: Non-obvious learnings, things that surprised you ("FTS5 porter tokenizer handles plurals but not acronyms")
+
+Always include: a \`summary\` (one-line, <100 chars), a \`type\`, relevant \`topics\`, and link to \`related_to\` thoughts when applicable.
+
+### When to SEARCH (mandatory)
+
+You MUST call \`search_thoughts\` or \`list_thoughts\` before:
+
+- **Starting work on any task** — check what's already known about this area
+- **Making a decision** — check for prior decisions on the same topic
+- **When something feels familiar** — it probably is; search for it
+- **After context compaction** — immediately search to recover session context
+- **When the user says** "remember", "recall", "what do we know about", "what did we decide"
+
+### What NOT to save
+
+- Ephemeral debugging output (stack traces, log lines you're actively reading)
+- Code content that's already in git (save the *decision* about code, not the code itself)
+- Transient conversation ("let me think about this..." — save the conclusion, not the process)
+- Duplicate information — search first, update existing thoughts instead of creating new ones
+
+### How to save well
+
+1. **Summary first.** Search results only show summaries. A thought without a summary is invisible to search.
+2. **Type accurately.** Use \`decision\`, \`task\`, \`question\`, \`reference\`, \`insight\`, or \`note\`. Don't default everything to \`note\`.
+3. **Tag topics and people.** These are the primary filters for \`list_thoughts\`.
+4. **Link related thoughts.** Use \`manage_edges\` to connect decisions to the tasks they affect, references to the insights they support.
+5. **Update, don't duplicate.** If a thought exists but is outdated, use \`update_thought\`. Don't create a new one.`;
+export function printProtocol() {
+    console.error("Paste this into your agent's rules file (CLAUDE.md, .cursorrules, AGENTS.md, etc.)\n" +
+        "Pipe directly: shelbymcp protocol >> CLAUDE.md\n");
+    console.log(MEMORY_PROTOCOL);
+}
+//# sourceMappingURL=protocol.js.map

package/dist/cli/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/cli/protocol.ts"],"names":[],"mappings":"AAAA,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qHAyC6F,CAAC;AAEtH,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,KAAK,CACX,sFAAsF;QACtF,kDAAkD,CACnD,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;AAC/B,CAAC"}

package/dist/cli/setup.d.ts

@@ -0,0 +1,2 @@
+export declare function runSetup(agent: string | undefined, forage: boolean): void;
+//# sourceMappingURL=setup.d.ts.map

package/dist/cli/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/cli/setup.ts"],"names":[],"mappings":"AA6UA,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAyCzE"}

package/dist/cli/setup.js

@@ -0,0 +1,328 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+const AGENTS = [
+    "claude-code",
+    "claude-desktop",
+    "cursor",
+    "codex",
+    "windsurf",
+    "gemini",
+];
+function isAgent(name) {
+    return AGENTS.includes(name);
+}
+/** Resolve the package root (where skills/ lives) from the compiled dist/ output */
+function getPackageRoot() {
+    const thisFile = fileURLToPath(import.meta.url);
+    // thisFile is dist/cli/setup.js → go up to dist/, then up to package root
+    return resolve(dirname(thisFile), "..", "..");
+}
+function getSkillSourcePath() {
+    return resolve(getPackageRoot(), "skills", "shelby-forage");
+}
+function mergeJsonConfig(filePath, serverEntry) {
+    let config = {};
+    if (existsSync(filePath)) {
+        try {
+            config = JSON.parse(readFileSync(filePath, "utf-8"));
+        }
+        catch {
+            console.error(`Warning: Could not parse ${filePath}. Creating new file.`);
+        }
+    }
+    if (!config.mcpServers || typeof config.mcpServers !== "object") {
+        config.mcpServers = {};
+    }
+    const servers = config.mcpServers;
+    if (servers.memory) {
+        console.log(`"memory" server already exists in ${filePath}`);
+        console.log("To reconfigure, remove the existing entry first.");
+        return false;
+    }
+    servers.memory = serverEntry;
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(filePath, JSON.stringify(config, null, 2) + "\n");
+    console.log(`Added ShelbyMCP to ${filePath}`);
+    return true;
+}
+function printForageInstructions(agent) {
+    console.log("\n--- Forage Skill ---\n");
+    switch (agent) {
+        case "claude-desktop":
+            console.log("To set up Forage on Claude Desktop:");
+            console.log("  1. Open the Schedule page");
+            console.log("  2. Create a new local task, set frequency to Daily");
+            console.log("  3. Paste the Forage prompt: run `shelbymcp forage` to get it");
+            console.log("");
+            console.log("Also add this to your Profile Preferences (alongside the Memory Protocol):");
+            console.log("");
+            console.log("  When starting a conversation, check ShelbyMCP for items that need attention:");
+            console.log('  use `list_thoughts` with `topic: "needs-attention"` and `limit: 5`.');
+            console.log("  If there are any, briefly mention them to the user.");
+            console.log("  If the user resolves one, delete the needs-attention thought.");
+            break;
+        case "cursor":
+            console.log("To set up Forage on Cursor:");
+            console.log("  1. Open Cursor Automations settings");
+            console.log("  2. Create a new automation with a Daily cron schedule");
+            console.log("  3. Paste the Forage prompt: run `shelbymcp forage` to get it");
+            console.log("");
+            console.log("Note: Cursor Automations are cloud-based. MCP access to local");
+            console.log("servers may not work. Test to confirm.");
+            break;
+        case "codex":
+            console.log("Codex automation support is still evolving.");
+            console.log("To run Forage manually, paste the output of `shelbymcp forage`");
+            console.log("into a Codex conversation.");
+            break;
+        case "windsurf":
+            console.log("Windsurf has no scheduler. To run Forage manually, paste the");
+            console.log("output of `shelbymcp forage` into a Windsurf conversation");
+            console.log("whenever you want to maintain your memories.");
+            break;
+        case "gemini":
+            console.log("To set up Forage on Gemini:");
+            console.log("  1. Create a scheduled action set to Daily");
+            console.log("  2. Paste the Forage prompt: run `shelbymcp forage` to get it");
+            console.log("");
+            console.log("Note: Gemini has a max of 10 active scheduled actions.");
+            console.log("MCP tool access in scheduled actions is uncertain — test to confirm.");
+            break;
+    }
+}
+function setupClaudeCode(forage) {
+    try {
+        execSync("which claude", { stdio: "ignore" });
+    }
+    catch {
+        console.log("Claude Code CLI not found. Install it from https://code.claude.com\n");
+        console.log("Once installed, run:");
+        console.log("  claude mcp add -s user -t stdio memory -- npx shelbymcp");
+        return;
+    }
+    console.log("Adding ShelbyMCP to Claude Code CLI (user scope)...\n");
+    try {
+        execSync("claude mcp add -s user -t stdio memory -- npx shelbymcp", {
+            stdio: "inherit",
+        });
+        console.log("\nShelbyMCP added to Claude Code CLI.");
+    }
+    catch {
+        console.log("\nCould not add automatically. Run manually:");
+        console.log("  claude mcp add -s user -t stdio memory -- npx shelbymcp");
+    }
+    console.log("\nNext: Add the Memory Protocol to your rules file:");
+    console.log("  shelbymcp protocol >> ~/.claude/CLAUDE.md");
+    if (forage) {
+        const skillSource = getSkillSourcePath();
+        const skillDest = resolve(homedir(), ".claude/scheduled-tasks/shelby-forage");
+        if (existsSync(resolve(skillDest, "SKILL.md"))) {
+            console.log("\n--- Forage Skill ---\n");
+            console.log(`Forage skill already installed at ${skillDest}`);
+        }
+        else if (existsSync(resolve(skillSource, "SKILL.md"))) {
+            mkdirSync(skillDest, { recursive: true });
+            cpSync(skillSource, skillDest, { recursive: true });
+            console.log("\n--- Forage Skill ---\n");
+            console.log(`Forage skill installed to ${skillDest}`);
+            console.log("It will run daily via Claude Code's scheduler.");
+            console.log("\nNote: Claude Code CLI scheduled tasks auto-expire after 7 days.");
+            console.log("Use Claude Desktop for persistent scheduling.");
+        }
+        else {
+            console.log("\n--- Forage Skill ---\n");
+            console.log("Could not find skills/shelby-forage/SKILL.md in the package.");
+            console.log("Install manually: shelbymcp forage > ~/.claude/scheduled-tasks/shelby-forage/SKILL.md");
+        }
+    }
+}
+function setupClaudeDesktop(forage) {
+    const platform = process.platform;
+    let configPath;
+    if (platform === "darwin") {
+        configPath = resolve(homedir(), "Library/Application Support/Claude/claude_desktop_config.json");
+    }
+    else if (platform === "win32") {
+        configPath = resolve(process.env.APPDATA ?? "", "Claude/claude_desktop_config.json");
+    }
+    else {
+        configPath = resolve(homedir(), ".config/Claude/claude_desktop_config.json");
+    }
+    console.log("Claude Desktop setup\n");
+    console.log(`Config file: ${configPath}\n`);
+    console.log("Open Claude Desktop > Settings > Developer > Edit Config");
+    console.log("Add this to the mcpServers object:\n");
+    console.log(JSON.stringify({
+        memory: {
+            command: "npx",
+            args: ["shelbymcp"],
+        },
+    }, null, 2));
+    console.log("\nIMPORTANT: Quit and restart Claude Desktop after editing.");
+    console.log("\nNote: Claude Desktop and Claude Code CLI have separate configs.");
+    console.log("Setting up one does NOT configure the other.");
+    console.log("\nNext: Add the Memory Protocol to your Desktop profile:");
+    console.log("  Settings > Profile > \"What preferences should Claude consider?\"");
+    console.log("  Run: shelbymcp protocol");
+    if (forage) {
+        printForageInstructions("claude-desktop");
+    }
+}
+function setupCursor(forage) {
+    const configPath = resolve(homedir(), ".cursor/mcp.json");
+    const entry = {
+        command: "npx",
+        args: ["shelbymcp"],
+    };
+    mergeJsonConfig(configPath, entry);
+    console.log("\nOr add via UI: Settings > Tools & MCP > New MCP Server");
+    console.log("\nNext: Add the Memory Protocol for Cursor:");
+    console.log("  mkdir -p .cursor/rules");
+    console.log("  echo '---\\nalwaysApply: true\\n---' > .cursor/rules/shelbymcp.mdc");
+    console.log("  shelbymcp protocol >> .cursor/rules/shelbymcp.mdc");
+    if (forage) {
+        printForageInstructions("cursor");
+    }
+}
+function setupCodex(forage) {
+    try {
+        execSync("which codex", { stdio: "ignore" });
+    }
+    catch {
+        console.log("Codex CLI not found.\n");
+        console.log("Add this to ~/.codex/config.toml:\n");
+        console.log("[mcp_servers.memory]");
+        console.log('command = "npx"');
+        console.log('args = ["shelbymcp"]');
+        console.log("\nNext: Add the Memory Protocol:");
+        console.log("  shelbymcp protocol >> AGENTS.md");
+        if (forage) {
+            printForageInstructions("codex");
+        }
+        return;
+    }
+    console.log("Adding ShelbyMCP to Codex...\n");
+    try {
+        execSync("codex mcp add memory -- npx shelbymcp", { stdio: "inherit" });
+        console.log("\nShelbyMCP added to Codex.");
+    }
+    catch {
+        console.log("\nCould not add automatically. Add to ~/.codex/config.toml:\n");
+        console.log("[mcp_servers.memory]");
+        console.log('command = "npx"');
+        console.log('args = ["shelbymcp"]');
+    }
+    console.log("\nNext: Add the Memory Protocol:");
+    console.log("  shelbymcp protocol >> AGENTS.md");
+    if (forage) {
+        printForageInstructions("codex");
+    }
+}
+function setupWindsurf(forage) {
+    const platform = process.platform;
+    let configPath;
+    if (platform === "win32") {
+        configPath = resolve(process.env.USERPROFILE ?? homedir(), ".codeium/windsurf/mcp_config.json");
+    }
+    else {
+        configPath = resolve(homedir(), ".codeium/windsurf/mcp_config.json");
+    }
+    const entry = {
+        command: "npx",
+        args: ["shelbymcp"],
+    };
+    mergeJsonConfig(configPath, entry);
+    console.log("\nOr add via UI: Settings > Cascade > MCP Servers");
+    console.log("\nNext: Add the Memory Protocol:");
+    console.log("  shelbymcp protocol >> .windsurfrules");
+    if (forage) {
+        printForageInstructions("windsurf");
+    }
+}
+function setupGemini(forage) {
+    const configPath = resolve(homedir(), ".gemini/settings.json");
+    const entry = {
+        command: "npx",
+        args: ["shelbymcp"],
+    };
+    // Gemini stores mcpServers inside settings.json alongside other settings
+    let config = {};
+    if (existsSync(configPath)) {
+        try {
+            config = JSON.parse(readFileSync(configPath, "utf-8"));
+        }
+        catch {
+            console.error(`Warning: Could not parse ${configPath}. Creating new file.`);
+        }
+    }
+    if (!config.mcpServers || typeof config.mcpServers !== "object") {
+        config.mcpServers = {};
+    }
+    const servers = config.mcpServers;
+    if (servers["shelby-memory"]) {
+        console.log(`"shelby-memory" server already exists in ${configPath}`);
+        console.log("To reconfigure, remove the existing entry first.");
+    }
+    else {
+        servers["shelby-memory"] = entry;
+        const dir = dirname(configPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+        console.log(`Added ShelbyMCP as "shelby-memory" to ${configPath}`);
+        console.log('(Using hyphens, not underscores — Gemini\'s parser breaks on underscores)');
+    }
+    console.log("\nNext: Add the Memory Protocol:");
+    console.log("  shelbymcp protocol >> GEMINI.md");
+    if (forage) {
+        printForageInstructions("gemini");
+    }
+}
+export function runSetup(agent, forage) {
+    if (!agent) {
+        console.log("Usage: shelbymcp setup <agent> [--forage]\n");
+        console.log("Agents:");
+        console.log("  claude-code       Claude Code CLI");
+        console.log("  claude-desktop    Claude Desktop app");
+        console.log("  cursor            Cursor IDE");
+        console.log("  codex             OpenAI Codex");
+        console.log("  windsurf          Windsurf (Codeium)");
+        console.log("  gemini            Gemini CLI");
+        console.log("\nFlags:");
+        console.log("  --forage          Also set up the Forage enrichment skill");
+        return;
+    }
+    if (!isAgent(agent)) {
+        console.error(`Unknown agent: "${agent}"\n`);
+        console.error("Available agents: " + AGENTS.join(", "));
+        process.exit(1);
+    }
+    switch (agent) {
+        case "claude-code":
+            setupClaudeCode(forage);
+            break;
+        case "claude-desktop":
+            setupClaudeDesktop(forage);
+            break;
+        case "cursor":
+            setupCursor(forage);
+            break;
+        case "codex":
+            setupCodex(forage);
+            break;
+        case "windsurf":
+            setupWindsurf(forage);
+            break;
+        case "gemini":
+            setupGemini(forage);
+            break;
+    }
+}
+//# sourceMappingURL=setup.js.map