@sage-protocol/cli 0.2.9 → 0.3.2

package/dist/cli/mcp-server-stdio.js

@@ -23,6 +23,12 @@ const { resolveDiscoverySettings } = require('./services/ipfs/discovery-config')
 process.env.MCP_MODE = 'true';
 process.env.IPFS_SILENT = 'true';
 
+// CRITICAL: Redirect console.log to stderr to prevent libraries from polluting stdout
+// JSON-RPC responses must be the ONLY thing written to stdout.
+const originalConsoleLog = console.log;
+console.log = console.error;
+
+
 // Load environment variables without dotenv promotional messages
 const LibraryManager = require('./library-manager');
 const metapromptDesigner = require('./utils/metaprompt-designer');
@@ -63,19 +69,147 @@ class SageMCPServer {
       name: 'sage-protocol-mcp',
       version: '1.0.0'
     };
-    
+
     this.discoverySettings = resolveDiscoverySettings();
     this.discoveryClient = undefined;
-    
+
     this.capabilities = {
       tools: {},
       prompts: {}
     };
 
-      this.tools = [
+    this.tools = [
+      {
+        name: 'quick_create_prompt',
+        description: `Quickly create a new prompt. Handles library creation automatically.
+When to use:
+- Starting a new prompt from scratch
+- Creating a prompt in "My Library" (default)
+
+Prerequisites:
+- None! Just need a name and content.
+
+Next steps:
+- quick_test_prompt() to verify
+- quick_iterate_prompt() to refine`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'Name of the prompt' },
+            content: { type: 'string', description: 'Prompt content (supports ${variable} syntax)' },
+            description: { type: 'string', description: 'Optional description' },
+            library: { type: 'string', description: 'Optional library name (defaults to "My Library")' }
+          },
+          required: ['name', 'content']
+        }
+      },
+      {
+        name: 'quick_iterate_prompt',
+        description: `Update an existing prompt. Creates a backup of the previous version.
+When to use:
+- Refining prompt content
+- Renaming a prompt
+- Safe editing (auto-backup)
+
+Prerequisites:
+- Key of the prompt (from list_prompts)
+
+Next steps:
+- quick_test_prompt() to verify changes`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'Key of the prompt to update' },
+            content: { type: 'string', description: 'New content' },
+            name: { type: 'string', description: 'New name' }
+          },
+          required: ['key']
+        }
+      },
+      {
+        name: 'improve_prompt',
+        description: `Analyze an existing prompt and suggest improvement areas and interview questions.
+When to use:
+- You have a working prompt and want to refine it
+- You want structured feedback and question prompts for the user
+
+Prerequisites:
+- Key of the prompt`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'Prompt key' },
+            library: { type: 'string', description: 'Optional library name or CID to narrow search' },
+            focus: { type: 'string', description: 'Optional focus area (e.g. "clarity", "variables", "edge-cases")' }
+          },
+          required: ['key']
+        }
+      },
+      {
+        name: 'rename_prompt',
+        description: `Rename a prompt's key and/or display name.
+When to use:
+- You want a cleaner key or display name
+- You want to align keys across related prompts
+
+Notes:
+- Keys are stable identifiers; renaming a key will affect how you reference the prompt in tools.`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'Existing prompt key' },
+            newKey: { type: 'string', description: 'New key (optional, stable identifier)' },
+            name: { type: 'string', description: 'New display name (optional)' }
+          },
+          required: ['key']
+        }
+      },
+      {
+        name: 'quick_test_prompt',
+        description: `Alias for test_prompt. Test a prompt with variables.
+When to use:
+- Verifying prompt behavior
+- Checking variable substitution
+- Debugging prompt logic
+
+Prerequisites:
+- Key of the prompt
+
+Next steps:
+- quick_iterate_prompt() if changes needed`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'Prompt key' },
+            variables: { type: 'object', description: 'Variables for substitution' }
+          },
+          required: ['key']
+        }
+      },
+      {
+        name: 'help',
+        description: 'Get help on how to use Sage MCP tools and workflows',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            topic: { type: 'string', description: 'Specific topic (e.g., "create", "publish", "versioning")' }
+          }
+        }
+      },
+
       {
         name: 'search_prompts',
-        description: 'Unified prompt search across local pinned libraries and on-chain registries',
+        description: `Unified prompt search across local pinned libraries and on-chain registries.
+When to use:
+- Finding prompts by topic, tag, or content
+- Searching across BOTH local and on-chain sources
+
+Prerequisites:
+- None
+
+Next steps:
+- get_prompt(key) to view details
+- quick_test_prompt(key) to try it`,
         inputSchema: {
           type: 'object',
           properties: {
@@ -102,6 +236,77 @@ class SageMCPServer {
           required: []
         }
       },
+      {
+        name: 'list_prompts',
+        description: `List all available prompts from local libraries.
+When to use:
+- Browsing your local collection
+- Seeing what's available in a specific library
+
+Prerequisites:
+- None
+
+Next steps:
+- get_prompt(key) to view details`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            source: { type: 'string', enum: ['local', 'all'], description: 'Data source (default: local)' },
+            library: { type: 'string', description: 'Optional: filter by library name or CID' },
+            limit: { type: 'number', description: 'Max prompts to return (default: 20)' }
+          },
+          required: []
+        }
+      },
+      {
+        name: 'get_prompt',
+        description: `Get a specific prompt by key, including its full content.
+When to use:
+- Viewing/editing a known prompt
+- Testing prompt with variables
+- Retrieving prompt for copying/forking
+
+Prerequisites:
+- Know the prompt key (from list_prompts or search_prompts)
+
+Next steps:
+- quick_test_prompt() to fill variables
+- quick_iterate_prompt() to edit`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'Prompt key (e.g. "daily-reflection")' },
+            library: { type: 'string', description: 'Optional: library name or CID to narrow search' }
+          },
+          required: ['key']
+        }
+      },
+      {
+        name: 'test_prompt',
+        description: `Test a prompt by filling in \${variable} placeholders and seeing the rendered result.
+When to use:
+- Verifying prompt behavior
+- Checking variable substitution
+- Debugging prompt logic
+
+Prerequisites:
+- Key of the prompt
+
+Next steps:
+- quick_iterate_prompt() if changes needed`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'Prompt key' },
+            library: { type: 'string', description: 'Optional: library name or CID' },
+            variables: {
+              type: 'object',
+              description: 'Key-value pairs for ${variable} placeholders (e.g. {"language": "Python"})'
+            }
+          },
+          required: ['key']
+        }
+      },
       {
         name: 'search_onchain_prompts',
         description: 'Search for prompts directly on-chain from LibraryRegistry and SubDAO registries',
@@ -163,7 +368,8 @@ class SageMCPServer {
           properties: {
             goal: { type: 'string', description: 'High-level objective for the resulting system prompt' },
             model: { type: 'string', description: 'Target model identifier (default: gpt-5)' },
-            interviewStyle: { type: 'string', description: 'Cadence preference (default: one-question-at-a-time)' }
+            interviewStyle: { type: 'string', description: 'Cadence preference (default: one-question-at-a-time)' },
+            additionalInstructions: { type: 'string', description: 'Any extra instructions for the interviewer (e.g. "Be concise", "Focus on security")' }
           },
           required: []
         }
@@ -307,22 +513,23 @@ class SageMCPServer {
       },
       {
         name: 'propose_manifest',
-        description: 'Build governance payload for a manifest CID and suggest CLI commands',
+        description: `Generate the proposal payload and CLI commands for a SubDAO update.
+Note: This tool does NOT sign transactions. It generates the hex data and CLI commands for you to execute in your terminal.`,
         inputSchema: {
           type: 'object',
           properties: {
-            cid: { type: 'string', description: 'Manifest CID' },
-            subdao: { type: 'string', description: 'Target SubDAO address (optional if governor context is persisted)' },
-            description: { type: 'string', description: 'Proposal description override (optional)' },
-            promptCount: { type: 'number', description: 'Prompt count if known (optional)' },
-            manifest: { type: 'object', description: 'Manifest JSON (optional, used for prompt count/previous)' }
+            cid: { type: 'string', description: 'IPFS CID of the manifest' },
+            subdao: { type: 'string', description: 'SubDAO address' },
+            description: { type: 'string', description: 'Proposal description' },
+            promptCount: { type: 'number', description: 'Number of prompts (optional override)' },
+            manifest: { type: 'object', description: 'Optional manifest object for context' }
           },
-          required: ['cid']
+          required: ['cid', 'subdao']
         }
       },
       {
         name: 'pin_library',
-        description: 'Save a manifest JSON to local cache (~/.sage/libraries/<cid>.json)',
+        description: 'Pin a library manifest to local IPFS node (simulated or real)',
         inputSchema: {
           type: 'object',
           properties: {
@@ -333,35 +540,35 @@ class SageMCPServer {
       },
       {
         name: 'pin_by_cid',
-        description: 'Fetch a manifest by CID from IPFS and save it to local cache',
+        description: 'Fetch a manifest by CID and pin it locally',
         inputSchema: {
           type: 'object',
           properties: {
-            cid: { type: 'string', description: 'Manifest CID' }
+            cid: { type: 'string', description: 'CID to fetch and pin' }
           },
           required: ['cid']
         }
       },
       {
         name: 'diff_manifests',
-        description: 'Diff a previous manifest CID (IPFS) against a new manifest JSON',
+        description: 'Compare two manifests (previous CID vs new manifest object)',
         inputSchema: {
           type: 'object',
           properties: {
-            previousCid: { type: 'string', description: 'Previous manifest CID' },
-            nextManifest: { type: 'object', description: 'Next manifest JSON' }
+            previousCid: { type: 'string', description: 'Base CID' },
+            nextManifest: { type: 'object', description: 'New manifest object' }
           },
           required: ['previousCid', 'nextManifest']
         }
       },
       {
         name: 'list_proposals',
-        description: 'List proposals (subgraph-first) with friendly summaries',
+        description: 'List active proposals for a SubDAO',
         inputSchema: {
           type: 'object',
           properties: {
-            subdao: { type: 'string', description: 'Optional SubDAO address to scope results' },
-            state: { type: 'string', description: 'Optional state filter (Pending|Active|Succeeded|Queued|Executed...)' },
+            subdao: { type: 'string', description: 'SubDAO address' },
+            state: { type: 'string', description: 'Filter by state (Active, Executed, etc)' },
             limit: { type: 'number', description: 'Max items (default 10)' }
           },
           required: []
@@ -369,17 +576,190 @@ class SageMCPServer {
       },
       {
         name: 'publish_manifest_flow',
-        description: 'Validate → push → build proposal payload with CLI hints (no signing)',
+        description: `Prepare a manifest for on-chain publishing.
+1. Validates the manifest
+2. Pins it to IPFS
+3. Generates CLI commands for you to sign & broadcast
+
+Note: This tool does NOT sign transactions. It prepares everything so you can execute the final step in your terminal.`,
         inputSchema: {
           type: 'object',
           properties: {
             manifest: { type: 'object', description: 'Manifest JSON' },
             subdao: { type: 'string', description: 'Optional SubDAO address for hints' },
-            description: { type: 'string', description: 'Optional description override' }
+            description: { type: 'string', description: 'Optional description override' },
+            dry_run: { type: 'boolean', description: 'Validate and build proposal payload without uploading to IPFS (no network calls)' }
           },
           required: ['manifest']
         }
       },
+      {
+        name: 'update_library_metadata',
+        description: 'Update library-level metadata (name/description/tags) and optionally propagate tags to prompts.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            library: {
+              type: 'string',
+              description: 'Pinned library name or CID (case-insensitive name match)'
+            },
+            name: { type: 'string', description: 'New library name (optional)' },
+            description: { type: 'string', description: 'New library description (optional)' },
+            tags: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Library-level tags (replaces existing)'
+            },
+            apply_to_prompts: {
+              type: 'boolean',
+              description: 'If true and tags provided, propagate tags to prompts using merge_mode',
+              default: false
+            },
+            merge_mode: {
+              type: 'string',
+              enum: ['replace', 'merge'],
+              description: 'Prompt tag strategy when apply_to_prompts=true',
+              default: 'merge'
+            }
+          },
+          required: ['library']
+        }
+      },
+      {
+        name: 'bulk_update_prompts',
+        description: 'Apply multiple small updates (name/description/tags/content) to prompts in a single library.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            library: {
+              type: 'string',
+              description: 'Pinned library name or CID'
+            },
+            updates: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  key: {
+                    type: 'string',
+                    description: 'Prompt key within the manifest'
+                  },
+                  name: { type: 'string', description: 'New prompt display name (optional)' },
+                  description: { type: 'string', description: 'New prompt description (optional)' },
+                  tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'If provided, replaces the prompt tags'
+                  },
+                  content: {
+                    type: 'string',
+                    description: 'New prompt content body (optional)'
+                  }
+                },
+                required: ['key']
+              },
+              minItems: 1
+            },
+            dry_run: {
+              type: 'boolean',
+              description: 'If true, return a preview of changes without writing to disk',
+              default: false
+            }
+          },
+          required: ['library', 'updates']
+        }
+      },
+      {
+        name: 'list_templates',
+        description: 'List available prompt templates for quick creation.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            category: { type: 'string', description: 'Optional category filter (design, development, analysis, etc.)' },
+            search: { type: 'string', description: 'Optional text search over template key/name/description' }
+          },
+          required: []
+        }
+      },
+      {
+        name: 'get_template',
+        description: 'Get detailed information about a specific prompt template.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'Template key' }
+          },
+          required: ['key']
+        }
+      },
+      {
+        name: 'create_from_template',
+        description: 'Create a new prompt from a template and save it into a local library via quick_create_prompt.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            template: { type: 'string', description: 'Template key' },
+            customize: {
+              type: 'object',
+              description: 'Values to substitute into the template variables'
+            },
+            library: {
+              type: 'string',
+              description: 'Target library name or CID (optional, default: My Library)'
+            },
+            name: {
+              type: 'string',
+              description: 'Override prompt display name (optional)'
+            }
+          },
+          required: ['template', 'customize']
+        }
+      },
+      {
+        name: 'analyze_dependencies',
+        description: 'Analyze variable usage across all prompts in a pinned library.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            library: {
+              type: 'string',
+              description: 'Pinned library name or CID'
+            },
+            analysis_type: {
+              type: 'string',
+              enum: ['variables', 'all'],
+              description: 'Type of analysis (v1 supports variables)',
+              default: 'variables'
+            }
+          },
+          required: ['library']
+        }
+      },
+      {
+        name: 'suggest_subdaos_for_library',
+        description: 'Suggest SubDAOs that might be a good fit for publishing a given local library, and provide CLI workflows for creating your own SubDAO and pushing the library.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            library: {
+              type: 'string',
+              description: 'Local pinned library name or CID'
+            },
+            limit: {
+              type: 'number',
+              description: 'Max SubDAOs to return (default 5)',
+              default: 5
+            },
+            mode_filter: {
+              type: 'string',
+              enum: ['any', 'creator', 'squad', 'community'],
+              description: 'Optional governance mode preference',
+              default: 'any'
+            }
+          },
+          required: ['library']
+        }
+      },
       {
         name: 'list_workspace_skills',
         description: 'List local workspace skills from prompts/ (e.g. prompts/skills/*.md)',
@@ -407,10 +787,10 @@ class SageMCPServer {
 
     // Structured logger to stderr (stdout must remain JSON-RPC only)
     this.log = pino ? pino({ level: process.env.MCP_DEBUG === 'true' ? 'debug' : 'info' }, pino.destination(2)) : {
-      debug: (...a) => { if (process.env.MCP_DEBUG === 'true') try { console.error(...a); } catch(_){} },
-      info: (...a) => { try { console.error(...a); } catch(_){} },
-      warn: (...a) => { try { console.error(...a); } catch(_){} },
-      error: (...a) => { try { console.error(...a); } catch(_){} },
+      debug: (...a) => { if (process.env.MCP_DEBUG === 'true') try { console.error(...a); } catch (_) { } },
+      info: (...a) => { try { console.error(...a); } catch (_) { } },
+      warn: (...a) => { try { console.error(...a); } catch (_) { } },
+      error: (...a) => { try { console.error(...a); } catch (_) { } },
     };
 
     // Shared provider + ABIs
@@ -500,6 +880,30 @@ class SageMCPServer {
       formatUnifiedResults: this.formatUnifiedResults,
     });
 
+    const { createQuickStart } = require('./services/mcp/quick-start');
+    this.quickStartHandler = createQuickStart({
+      libraryManager: this.libraryManager,
+      logger: this.log,
+    });
+
+    const { createBulkOperations } = require('./services/mcp/bulk-operations');
+    this.bulkOperations = createBulkOperations({
+      libraryManager: this.libraryManager,
+      logger: this.log,
+    });
+
+    const { createTemplateManager } = require('./services/mcp/template-manager');
+    this.templateManager = createTemplateManager({
+      quickStart: this.quickStartHandler,
+      logger: this.log,
+    });
+
+    const { createDependencyAnalyzer } = require('./services/mcp/dependency-analyzer');
+    this.dependencyAnalyzer = createDependencyAnalyzer({
+      libraryManager: this.libraryManager,
+      logger: this.log,
+    });
+
     this.libraryBindingsManager = createLibraryBindingsManager({
       provider: this.provider,
       subdaoAbi: this.subdaoAbi,
@@ -573,6 +977,15 @@ class SageMCPServer {
       'tool:search_prompts': (params) => this.searchPromptsUnified(params),
       'tool:search_onchain_prompts': (params) => this.searchOnchainPrompts(params),
       'tool:trending_prompts': (params) => this.trendingPrompts(params),
+      'tool:list_prompts': (params) => this.listPrompts(params),
+      'tool:get_prompt': (params) => this.getPrompt(params),
+      'tool:test_prompt': (params) => this.testPrompt(params),
+      'tool:quick_create_prompt': (params) => this.quickCreatePrompt(params),
+      'tool:quick_iterate_prompt': (params) => this.quickIteratePrompt(params),
+      'tool:improve_prompt': (params) => this.improvePrompt(params),
+      'tool:rename_prompt': (params) => this.renamePrompt(params),
+      'tool:quick_test_prompt': (params) => this.testPrompt(params),
+      'tool:help': (params) => this.getHelp(params),
       'tool:list_libraries': (params) => this.listLibraries(params),
       'tool:get_prompt_content': (params) => this.getPromptContent(params),
       'tool:list_subdaos': () => this.listSubDAOs(),
@@ -595,6 +1008,13 @@ class SageMCPServer {
       'tool:refresh_library_bindings': (params) => this.refreshLibraryBindings(params),
       'tool:list_workspace_skills': (params) => this.listWorkspaceSkills(params),
       'tool:get_workspace_skill': (params) => this.getWorkspaceSkill(params),
+      'tool:update_library_metadata': (params) => this.updateLibraryMetadata(params),
+      'tool:bulk_update_prompts': (params) => this.bulkUpdatePrompts(params),
+      'tool:list_templates': (params) => this.listTemplates(params),
+      'tool:get_template': (params) => this.getTemplate(params),
+      'tool:create_from_template': (params) => this.createPromptFromTemplate(params),
+      'tool:analyze_dependencies': (params) => this.analyzeDependencies(params),
+      'tool:suggest_subdaos_for_library': (params) => this.suggestSubdaosForLibrary(params),
     });
 
     const toolHandlers = {
@@ -646,7 +1066,7 @@ class SageMCPServer {
       if (process.env.SAGE_DEBUG_DISCOVERY === '1') {
         try {
           console.warn('mcp_discovery_client_failed', error.message);
-        } catch (_) {}
+        } catch (_) { }
       }
     }
     return this.discoveryClient;
@@ -683,7 +1103,7 @@ class SageMCPServer {
       if (process.env.SAGE_DEBUG_DISCOVERY === '1') {
         try {
           console.warn('mcp_discovery_event_failed', error.message);
-        } catch (_) {}
+        } catch (_) { }
       }
     }
   }
@@ -727,102 +1147,34 @@ class SageMCPServer {
    * - Skill files live under promptsDir/skills/*.md
    */
   listWorkspaceSkills() {
-    const skills = [];
     try {
       const { readWorkspace, DEFAULT_DIR } = require('./services/prompts/workspace');
+      const { findWorkspaceSkills } = require('./services/skills/discovery');
       const ws = readWorkspace() || {};
       const promptsDir = ws.promptsDir || DEFAULT_DIR || 'prompts';
-      const baseDir = path.join(process.cwd(), promptsDir, 'skills');
-      if (!fs.existsSync(baseDir)) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: 'No workspace skills directory found (expected prompts/skills). Create prompts/skills/<name>.md to define skills for this repo.',
-            },
-          ],
-        };
-      }
-      const walk = (dir) => {
-        const entries = fs.readdirSync(dir, { withFileTypes: true });
-        for (const entry of entries) {
-          const full = path.join(dir, entry.name);
-          if (entry.isDirectory()) {
-            walk(full);
-          } else if (entry.isFile() && full.toLowerCase().endsWith('.md')) {
-            skills.push(full);
-          }
-        }
-      };
-      walk(baseDir);
-      const results = skills.map((filePath) => {
-        const relFromPrompts = path.relative(path.join(process.cwd(), promptsDir), filePath);
-        const key = relFromPrompts.replace(/\\/g, '/').replace(/\.md$/i, '');
-        let title = path.basename(filePath, '.md');
-        let summary = '';
-        let tags = [];
-        try {
-          const raw = fs.readFileSync(filePath, 'utf8');
-          if (raw.startsWith('---')) {
-            const end = raw.indexOf('\n---', 3);
-            if (end !== -1) {
-              const front = raw.slice(3, end).split(/\r?\n/);
-              for (const line of front) {
-                const idx = line.indexOf(':');
-                if (idx === -1) continue;
-                const k = line.slice(0, idx).trim().toLowerCase();
-                let v = line.slice(idx + 1).trim();
-                if (k === 'title' && v) title = v;
-                if (k === 'summary' && v) summary = v;
-                if (k === 'tags' && v) {
-                  try {
-                    tags = JSON.parse(v.replace(/'/g, '"'));
-                  } catch (_) {
-                    tags = String(v)
-                      .split(/[,|\s]+/)
-                      .filter(Boolean);
-                  }
-                }
-              }
-            }
-          }
-        } catch (_) {
-          // ignore parse errors; fall back to filename
-        }
-        return {
-          key,
-          name: title,
-          summary,
-          tags,
-          path: filePath,
-        };
-      });
-
+      const results = findWorkspaceSkills({ promptsDir });
       if (!results.length) {
         return {
           content: [
             {
               type: 'text',
-              text: 'No skills found under prompts/skills. Create prompts/skills/<name>.md to define repo-specific skills.',
+              text: 'No skills found. Create prompts/skills/<name>.md or prompts/skills/<name>/SKILL.md to define skills for this repo.',
             },
-            { type: 'json', text: JSON.stringify({ skills: [] }, null, 2) },
+            { type: 'text', text: '```json\n' + JSON.stringify({ skills: [] }, null, 2) + '\n```' },
           ],
         };
       }
-
       const textLines = results
         .map(
           (s, idx) =>
-            `${idx + 1}. **${s.name}** (${s.key})\n   📁 ${path.relative(process.cwd(), s.path)}${
-              s.summary ? `\n   📝 ${s.summary}` : ''
+            `${idx + 1}. **${s.name}** (${s.key})\n   📁 ${path.relative(process.cwd(), s.path)}${s.summary ? `\n   📝 ${s.summary}` : ''
             }${s.tags && s.tags.length ? `\n   🔖 ${s.tags.join(', ')}` : ''}`,
         )
         .join('\n\n');
-
       return {
         content: [
           { type: 'text', text: `Workspace skills (${results.length})\n\n${textLines}` },
-          { type: 'json', text: JSON.stringify({ skills: results }, null, 2) },
+          { type: 'text', text: '```json\n' + JSON.stringify({ skills: results }, null, 2) + '\n```' },
         ],
       };
     } catch (error) {
@@ -839,42 +1191,38 @@ class SageMCPServer {
   getWorkspaceSkill({ key }) {
     try {
       if (!key || !String(key).trim()) {
-        return {
-          content: [{ type: 'text', text: 'get_workspace_skill: key is required' }],
-        };
+        return { content: [{ type: 'text', text: 'get_workspace_skill: key is required' }] };
       }
       const { readWorkspace, DEFAULT_DIR } = require('./services/prompts/workspace');
+      const { resolveSkillFileByKey } = require('./services/skills/discovery');
       const ws = readWorkspace() || {};
       const promptsDir = ws.promptsDir || DEFAULT_DIR || 'prompts';
       const safeKey = String(key).trim().replace(/^\/+/, '').replace(/\.md$/i, '');
-      const filePath = path.join(process.cwd(), promptsDir, `${safeKey}.md`);
-      if (!fs.existsSync(filePath)) {
+      const resolved = resolveSkillFileByKey({ promptsDir, key: safeKey });
+      if (!resolved || !fs.existsSync(resolved.path)) {
+        const expectedFlat = path.join(process.cwd(), promptsDir, `${safeKey}.md`);
+        const expectedDir = path.join(process.cwd(), promptsDir, safeKey, 'SKILL.md');
         return {
           content: [
             {
               type: 'text',
-              text: `Workspace skill not found for key '${safeKey}'. Expected file at ${path.relative(
-                process.cwd(),
-                filePath,
-              )}`,
+              text: `Workspace skill not found for key '${safeKey}'. Expected at ${path.relative(process.cwd(), expectedFlat)} or ${path.relative(process.cwd(), expectedDir)}`,
             },
           ],
         };
       }
-      const body = fs.readFileSync(filePath, 'utf8');
+      const body = fs.readFileSync(resolved.path, 'utf8');
       return {
         content: [
           {
             type: 'text',
-            text: `Loaded workspace skill '${safeKey}' from ${path.relative(process.cwd(), filePath)}.\n\n${body}`,
+            text: `Loaded workspace skill '${safeKey}' from ${path.relative(process.cwd(), resolved.path)}.\n\n${body}`,
           },
-          { type: 'json', text: JSON.stringify({ key: safeKey, path: filePath, body }, null, 2) },
+          { type: 'text', text: '```json\n' + JSON.stringify({ key: safeKey, path: resolved.path, baseDir: resolved.baseDir, body }, null, 2) + '\n```' },
         ],
       };
     } catch (error) {
-      return {
-        content: [{ type: 'text', text: `Error loading workspace skill: ${error.message}` }],
-      };
+      return { content: [{ type: 'text', text: `Error loading workspace skill: ${error.message}` }] };
     }
   }
 
@@ -951,7 +1299,7 @@ class SageMCPServer {
         libraryRegistryAddress: addressResolution.resolveRegistryAddress().registry,
         searchSubDAOPrompts: this.searchSubDAOPrompts.bind(this),
         fetchManifestPrompts: this.fetchManifestPrompts.bind(this),
-    });
+      });
       return buildOnchainSearchResponse(prompts);
     } catch (error) {
       return {
@@ -969,6 +1317,839 @@ class SageMCPServer {
     return this.searchPromptsUnifiedHandler(options);
   }
 
+  async listPrompts({ source = 'local', library = '', limit = 20 } = {}) {
+    try {
+      const results = await this.searchPromptsUnifiedHandler({
+        query: '',
+        source,
+        includeContent: false,
+        page: 1,
+        pageSize: limit
+      });
+
+      if (library && results?.content?.[1]?.text) {
+        const jsonMatch = results.content[1].text.match(/```json\n([\s\S]+)\n```/);
+        if (jsonMatch) {
+          const data = JSON.parse(jsonMatch[1]);
+          const libraryLower = library.toLowerCase();
+          data.results = data.results.filter(r =>
+            r.library?.name?.toLowerCase().includes(libraryLower) ||
+            r.library?.cid?.toLowerCase().includes(libraryLower)
+          );
+          data.total = data.results.length;
+
+          const formatted = this.formatUnifiedResults(data.results, { total: data.total, page: 1, pageSize: limit });
+          return {
+            content: [
+              { type: 'text', text: formatted },
+              { type: 'text', text: '```json\n' + JSON.stringify(data, null, 2) + '\n```' }
+            ]
+          };
+        }
+      }
+
+      return results;
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error listing prompts: ${error.message}` }] };
+    }
+  }
+
+  async getPrompt({ key, library = '' } = {}) {
+    try {
+      if (!key) {
+        return { content: [{ type: 'text', text: 'Error: key parameter is required' }] };
+      }
+
+      const results = await this.searchPromptsUnifiedHandler({
+        query: key,
+        source: 'local',
+        includeContent: true,
+        pageSize: 50
+      });
+
+      if (results?.content?.[1]?.text) {
+        const jsonMatch = results.content[1].text.match(/```json\n([\s\S]+)\n```/);
+        if (jsonMatch) {
+          const data = JSON.parse(jsonMatch[1]);
+          let prompt = data.results.find(r => r.key === key);
+
+          if (library && !prompt) {
+            const libraryLower = library.toLowerCase();
+            prompt = data.results.find(r =>
+              r.key === key && (r.library?.name?.toLowerCase().includes(libraryLower) || r.library?.cid?.toLowerCase().includes(libraryLower))
+            );
+          }
+
+          if (!prompt) {
+            prompt = data.results.find(r => r.key?.includes(key));
+          }
+
+          if (!prompt) {
+            return { content: [{ type: 'text', text: `No prompt found with key "${key}"` }] };
+          }
+
+          const text = `**${prompt.name}**\n\n🔑 Key: ${prompt.key}\n📚 Library: ${prompt.library?.name || 'Unknown'}\n📄 ${prompt.description || 'No description'}\n🏷️ Tags: ${prompt.tags?.join(', ') || 'None'}\n\n**Content:**\n\`\`\`\n${prompt.content || '(No content)'}\n\`\`\``;
+
+          return {
+            content: [
+              { type: 'text', text },
+              { type: 'text', text: '```json\n' + JSON.stringify(prompt, null, 2) + '\n```' }
+            ]
+          };
+        }
+      }
+
+      return { content: [{ type: 'text', text: `No prompt found with key "${key}"` }] };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error getting prompt: ${error.message}` }] };
+    }
+  }
+
+  async testPrompt({ key, library = '', variables = {} } = {}) {
+    try {
+      if (!key) {
+        return { content: [{ type: 'text', text: 'Error: key parameter is required' }] };
+      }
+
+      const promptResult = await this.getPrompt({ key, library });
+      if (!promptResult?.content?.[1]?.text) {
+        return promptResult;
+      }
+
+      const jsonMatch = promptResult.content[1].text.match(/```json\n([\s\S]+)\n```/);
+      if (!jsonMatch) {
+        return { content: [{ type: 'text', text: 'Error: Failed to parse prompt data' }] };
+      }
+
+      const prompt = JSON.parse(jsonMatch[1]);
+      let content = prompt.content || '';
+
+      if (!content) {
+        return { content: [{ type: 'text', text: `Prompt "${key}" has no content to test` }] };
+      }
+
+      const variablePattern = /\$\{([^}]+)\}/g;
+      const foundVariables = [];
+      let match;
+      while ((match = variablePattern.exec(content)) !== null) {
+        if (!foundVariables.includes(match[1])) {
+          foundVariables.push(match[1]);
+        }
+      }
+
+      let renderedContent = content;
+      const substitutions = {};
+
+      for (const varName of foundVariables) {
+        if (variables[varName] !== undefined) {
+          renderedContent = renderedContent.replace(new RegExp(`\\$\\{${varName}\\}`, 'g'), variables[varName]);
+          substitutions[varName] = variables[varName];
+        }
+      }
+
+      const missingVars = foundVariables.filter(v => variables[v] === undefined);
+
+      let result = `**Testing: ${prompt.name}**\n\n`;
+      if (foundVariables.length === 0) {
+        result += '✅ No variables\n\n';
+      } else {
+        result += `**Variables:** ${foundVariables.join(', ')}\n`;
+        if (Object.keys(substitutions).length > 0) {
+          result += `**Substituted:** ${Object.keys(substitutions).join(', ')}\n`;
+        }
+        if (missingVars.length > 0) {
+          result += `**⚠️ Missing:** ${missingVars.join(', ')}\n`;
+        }
+        result += '\n';
+      }
+
+      result += `**Rendered:**\n\`\`\`\n${renderedContent}\n\`\`\``;
+
+      return {
+        content: [
+          { type: 'text', text: result },
+          { type: 'text', text: '```json\n' + JSON.stringify({ prompt: { key: prompt.key, name: prompt.name }, variables: { found: foundVariables, substituted: Object.keys(substitutions), missing: missingVars }, rendered: renderedContent }, null, 2) + '\n```' }
+        ]
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error testing prompt: ${error.message}` }] };
+    }
+  }
+
+  async updateLibraryMetadata(params) {
+    try {
+      const result = await this.bulkOperations.updateLibraryMetadata(params);
+      const textLines = [
+        '✅ Updated library metadata',
+        `Library: ${result.library}`,
+        `CID: ${result.cid}`,
+        `Fields: ${result.updatedLibraryFields.length ? result.updatedLibraryFields.join(', ') : '(none)'}`,
+        `Prompts touched: ${result.updatedPromptCount}`,
+      ];
+      return {
+        content: [
+          { type: 'text', text: textLines.join('\n') },
+          { type: 'text', text: '```json\n' + JSON.stringify(result, null, 2) + '\n```' },
+        ],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error updating library metadata: ${error.message}` }] };
+    }
+  }
+
+  async bulkUpdatePrompts(params) {
+    try {
+      const result = await this.bulkOperations.bulkUpdatePrompts(params);
+      const header = result.dryRun ? '✅ Dry run: no changes written' : '✅ Bulk prompt update complete';
+      const textLines = [
+        header,
+        `Library: ${result.library}`,
+        `CID: ${result.cid}`,
+        `Updated prompts: ${result.updatedCount}`,
+      ];
+      if (result.missingKeys?.length) {
+        textLines.push(`Missing keys: ${result.missingKeys.join(', ')}`);
+      }
+      return {
+        content: [
+          { type: 'text', text: textLines.join('\n') },
+          { type: 'text', text: '```json\n' + JSON.stringify(result, null, 2) + '\n```' },
+        ],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error bulk updating prompts: ${error.message}` }] };
+    }
+  }
+
+  async listTemplates(params = {}) {
+    try {
+      const result = this.templateManager.listTemplates(params || {});
+      const items = result.templates || [];
+      if (!items.length) {
+        return { content: [{ type: 'text', text: 'No templates available.' }] };
+      }
+      const lines = [];
+      lines.push(`Available templates (${items.length}):`);
+      lines.push('');
+      for (const tpl of items) {
+        lines.push(`- **${tpl.name}** (${tpl.key}) [${tpl.category || 'uncategorized'}]`);
+        if (tpl.summary) {
+          lines.push(`  ${tpl.summary}`);
+        }
+        if (tpl.requiredVariables?.length) {
+          lines.push(`  Required: ${tpl.requiredVariables.join(', ')}`);
+        }
+        lines.push('');
+      }
+      return {
+        content: [
+          { type: 'text', text: lines.join('\n') },
+          { type: 'text', text: '```json\n' + JSON.stringify(result, null, 2) + '\n```' },
+        ],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error listing templates: ${error.message}` }] };
+    }
+  }
+
+  async getTemplate(params) {
+    try {
+      const result = this.templateManager.getTemplate(params || {});
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              `Template: ${result.template.name} (${result.template.key})\n` +
+              `Category: ${result.template.category || 'uncategorized'}\n\n` +
+              `${result.template.description || ''}`,
+          },
+          { type: 'text', text: '```json\n' + JSON.stringify(result.template, null, 2) + '\n```' },
+        ],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error getting template: ${error.message}` }] };
+    }
+  }
+
+  async createPromptFromTemplate(params) {
+    try {
+      const result = await this.templateManager.createFromTemplate(params || {});
+      const quick = result.quickCreate || {};
+      const lines = [];
+      lines.push('✅ Created prompt from template');
+      lines.push(`Template: ${result.template}`);
+      lines.push(`Key: ${quick.key || '(unknown key)'}`);
+      lines.push(`Library: ${quick.library || '(unknown library)'}`);
+      return {
+        content: [
+          { type: 'text', text: lines.join('\n') },
+          { type: 'text', text: '```json\n' + JSON.stringify(result, null, 2) + '\n```' },
+        ],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error creating prompt from template: ${error.message}` }] };
+    }
+  }
+
+  async analyzeDependencies(params) {
+    try {
+      return await this.dependencyAnalyzer.analyzeDependencies(params || {});
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error analyzing dependencies: ${error.message}` }] };
+    }
+  }
+
+  async suggestSubdaosForLibrary({ library, limit = 5, mode_filter = 'any' } = {}) {
+    try {
+      const lm = this.libraryManager;
+      const pinned = lm.listPinned() || [];
+      const id = String(library || '').trim();
+      if (!id) {
+        return { content: [{ type: 'text', text: 'Error: library parameter is required' }] };
+      }
+
+      let selected = null;
+      let row = pinned.find((r) => r.cid === id);
+      if (row) {
+        selected = lm.loadPinned(row.cid);
+        selected.row = row;
+      } else {
+        const lower = id.toLowerCase();
+        const matches = [];
+        for (const r of pinned) {
+          try {
+            const loaded = lm.loadPinned(r.cid);
+            const libName = String(loaded.manifest?.library?.name || r.name || '').toLowerCase();
+            if (libName === lower) {
+              matches.push({ row: r, ...loaded });
+            }
+          } catch (_) {
+            // ignore corrupt
+          }
+        }
+        if (matches.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `No pinned library found matching "${library}". Use list_libraries(source="local") to see available libraries.`,
+              },
+            ],
+          };
+        }
+        if (matches.length > 1) {
+          const lines = matches.map(
+            (m) => `- ${m.row.cid} (${m.manifest?.library?.name || m.row.name || 'unnamed'})`,
+          );
+          return {
+            content: [
+              {
+                type: 'text',
+                text:
+                  `Ambiguous library match for "${library}". Candidates:\n` +
+                  `${lines.join('\n')}\n\nPass an explicit CID to disambiguate.`,
+              },
+            ],
+          };
+        }
+        selected = matches[0];
+      }
+
+      const manifest = selected.manifest;
+      const libName = manifest.library?.name || selected.row?.name || library;
+      const libDescription = manifest.library?.description || '';
+      const tagsSet = new Set(
+        (manifest.library?.tags || []).map((t) => String(t).toLowerCase().trim()).filter(Boolean),
+      );
+      for (const p of manifest.prompts || []) {
+        if (!p || !Array.isArray(p.tags)) continue;
+        for (const t of p.tags) {
+          const v = String(t).toLowerCase().trim();
+          if (v) tagsSet.add(v);
+        }
+      }
+      const libTags = Array.from(tagsSet);
+
+      const subdaos = await this.getSubDAOList({ limit: 50 });
+      if (!subdaos || !subdaos.length) {
+        const fallbackText =
+          'No SubDAOs discovered from subgraph/factory.\n\n' +
+          'You can still create your own personal SubDAO for this library:\n\n' +
+          `1) Create personal SubDAO:\n   sage subdao create --type personal --name "${libName}" --description "${libDescription || libName}" --bootstrap\n\n` +
+          '2) Scaffold and push a manifest:\n' +
+          '   sage library scaffold-manifest courtyard-lib/manifest.json \\\n' +
+          `     --name "${libName}" \\\n` +
+          `     --description "${libDescription || libName}"\n` +
+          '   # Add prompts with: sage library add-prompt --manifest courtyard-lib/manifest.json --file prompts/<file>.md --key <key>\n' +
+          '   sage library push courtyard-lib/manifest.json --subdao 0xYourSubDAO --pin --wait\n';
+        return { content: [{ type: 'text', text: fallbackText }] };
+      }
+
+      const modeFilter = mode_filter || 'any';
+      const scored = [];
+      for (const s of subdaos) {
+        const name = String(s.name || '').toLowerCase();
+        const desc = String(s.description || '').toLowerCase();
+        const tokens = new Set(
+          (name + ' ' + desc)
+            .split(/[^a-z0-9]+/i)
+            .map((t) => t.toLowerCase().trim())
+            .filter(Boolean),
+        );
+        let matchCount = 0;
+        const matchedTags = [];
+        for (const tag of libTags) {
+          if (tokens.has(tag)) {
+            matchCount += 1;
+            matchedTags.push(tag);
+          }
+        }
+
+        if (modeFilter !== 'any') {
+          // Mode-specific filtering can be added in a future iteration.
+        }
+
+        const libraryCount = Array.isArray(s.registries) ? s.registries.length : 0;
+        const fitScore = matchCount + libraryCount * 0.1;
+        scored.push({
+          address: s.address,
+          name: s.name || `SubDAO-${String(s.address).slice(-6)}`,
+          description: s.description || '',
+          registryAddress: s.registryAddress || null,
+          defaultLibraryId: s.defaultLibraryId || 'main',
+          libraryCount,
+          matchedTags,
+          fitScore,
+        });
+      }
+
+      scored.sort((a, b) => (b.fitScore || 0) - (a.fitScore || 0));
+      const top = scored.slice(0, limit);
+
+      const lines = [];
+      lines.push(`🎯 Suggested SubDAOs for library "${libName}"`);
+      lines.push('');
+
+      if (!top.length || !libTags.length) {
+        lines.push('No strong SubDAO matches found based on tags and names.');
+      } else {
+        top.forEach((s, idx) => {
+          lines.push(`${idx + 1}. ${s.name} (${s.address})`);
+          if (s.matchedTags.length) {
+            lines.push(`   • Tag overlap: ${s.matchedTags.join(', ')}`);
+          }
+          lines.push(`   • Libraries: ${s.libraryCount}`);
+          if (s.description) {
+            lines.push(`   • Description: ${s.description}`);
+          }
+          lines.push('');
+        });
+      }
+
+      lines.push('---');
+      lines.push('💡 If none of these feel right, you can create your own personal SubDAO and publish there:');
+      lines.push('');
+      lines.push('1) Create a personal SubDAO for this library:');
+      lines.push(
+        `   sage subdao create --type personal --name "${libName}" --description "${libDescription || libName}" --bootstrap`,
+      );
+      lines.push('');
+      lines.push('2) Scaffold a manifest and push it:');
+      lines.push('   sage library scaffold-manifest courtyard-lib/manifest.json \\');
+      lines.push(`     --name "${libName}" \\`);
+      lines.push(`     --description "${libDescription || libName}"`);
+      lines.push(
+        '   # Add prompts with: sage library add-prompt --manifest courtyard-lib/manifest.json --file prompts/<file>.md --key <key>',
+      );
+      lines.push(
+        '   sage library push courtyard-lib/manifest.json --subdao 0xYourSubDAO --pin --wait',
+      );
+
+      const cliWorkflows = {
+        createPersonalSubdao: {
+          description: 'Create a personal SubDAO for this library.',
+          commands: [
+            `sage subdao create --type personal --name "${libName}" --description "${libDescription || libName}" --bootstrap`,
+          ],
+        },
+        createLibraryAndPush: {
+          description: 'Scaffold a manifest from your local prompts and push it to a SubDAO.',
+          commands: [
+            '# Scaffold manifest (adjust path/name as needed):',
+            'sage library scaffold-manifest courtyard-lib/manifest.json \\',
+            `  --name "${libName}" \\`,
+            `  --description "${libDescription || libName}"`,
+            '',
+            '# Add prompts (repeat per prompt):',
+            'sage library add-prompt --manifest courtyard-lib/manifest.json \\',
+            '  --file prompts/<file>.md \\',
+            '  --key <key> \\',
+            '  --name "<Prompt Name>"',
+            '',
+            '# Push to your SubDAO (replace 0xYourSubDAO):',
+            'sage library push courtyard-lib/manifest.json --subdao 0xYourSubDAO --pin --wait',
+          ],
+        },
+      };
+
+      const jsonPayload = {
+        library: {
+          cid: selected.row?.cid,
+          name: libName,
+          tags: libTags,
+        },
+        suggestions: top,
+        cliWorkflows,
+      };
+
+      return {
+        content: [
+          { type: 'text', text: lines.join('\n') },
+          { type: 'text', text: '```json\n' + JSON.stringify(jsonPayload, null, 2) + '\n```' },
+        ],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error suggesting SubDAOs: ${error.message}` }] };
+    }
+  }
+
+  async improvePrompt({ key, library = '', pass = 'single', focus = 'all' } = {}) {
+    try {
+      if (!key) {
+        return { content: [{ type: 'text', text: 'Error: key parameter is required' }] };
+      }
+
+      const promptResult = await this.getPrompt({ key, library });
+      if (!promptResult?.content?.[1]?.text) {
+        return promptResult;
+      }
+
+      const jsonMatch = promptResult.content[1].text.match(/```json\n([\s\S]+)\n```/);
+      if (!jsonMatch) {
+        return { content: [{ type: 'text', text: 'Error: Failed to parse prompt data for improvement' }] };
+      }
+
+      const prompt = JSON.parse(jsonMatch[1]);
+      const content = String(prompt.content || '');
+      const description = String(prompt.description || '');
+
+      if (!content.trim()) {
+        return { content: [{ type: 'text', text: `Prompt "${key}" has no content to analyze` }] };
+      }
+
+      // Variable analysis
+      const varPattern = /\$\{([^}]+)\}/g;
+      const foundVars = [];
+      let m;
+      while ((m = varPattern.exec(content)) !== null) {
+        const v = m[1];
+        if (!foundVars.includes(v)) foundVars.push(v);
+      }
+
+      // Simple heuristics
+      const lengthChars = content.length;
+      const lines = content.split(/\r?\n/).length;
+      const mentionsOutput =
+        /output|format|respond|response|return\b/i.test(content);
+      const mentionsRole =
+        /you are\b|as an? /i.test(content);
+
+      const improvementAreas = [];
+      if (!mentionsOutput) {
+        improvementAreas.push('Specify the expected output format (structure, tone, and level of detail).');
+      }
+      if (!mentionsRole) {
+        improvementAreas.push('Clarify the assistant role (e.g. "You are a landscape design assistant...").');
+      }
+      if (!foundVars.length) {
+        improvementAreas.push('Consider parameterizing important details with ${variables} to make the prompt reusable.');
+      }
+      if (foundVars.length && !description.toLowerCase().includes('variable')) {
+        improvementAreas.push('Document variables in the description so users know what to provide.');
+      }
+      if (lengthChars < 300) {
+        improvementAreas.push('Prompt is quite short; consider adding more context and edge-case handling.');
+      }
+
+      const focusNote = focus && focus !== 'all'
+        ? `\nFocus requested: **${focus}**\n`
+        : '';
+
+      const baseInterviewQuestions = [
+        'What edge cases or failure modes do you most want this prompt to handle?',
+        'Should the prompt enforce a specific output format (e.g. bullet list, JSON, sections)?',
+        'Are there any important variables (budget, constraints, region, style, etc.) that are currently missing?',
+        'Should the prompt ask clarifying questions when information is missing, or make reasonable assumptions?',
+        'Is this prompt meant for a single use-case, or should it be adaptable across multiple related tasks?',
+      ];
+
+      const variableQuestions = [
+        'Are the variable names clear and self-explanatory to future users?',
+        'Should any currently hard-coded values be turned into variables?',
+      ];
+
+      const edgeCaseQuestions = [
+        'What should happen if key inputs are missing, contradictory, or clearly invalid?',
+        'Are there any \"must not happen\" outcomes you want to guard against?',
+      ];
+
+      const outputQualityQuestions = [
+        'Do you want the model to always respond with a consistent structure (sections, headings, bullet points)?',
+        'Would example outputs help clarify what a great response looks like?',
+      ];
+
+      const reusabilityQuestions = [
+        'Should this prompt be reusable across multiple projects or tightly scoped to one?',
+        'Are there any project-specific details that should be parameterized instead of hard-coded?',
+      ];
+
+      // Select interview questions based on focus
+      let interviewQuestions = baseInterviewQuestions.slice();
+      if (focus === 'variables' || focus === 'all') interviewQuestions = interviewQuestions.concat(variableQuestions);
+      if (focus === 'edge-cases' || focus === 'all') interviewQuestions = interviewQuestions.concat(edgeCaseQuestions);
+      if (focus === 'output-quality' || focus === 'all') interviewQuestions = interviewQuestions.concat(outputQualityQuestions);
+      if (focus === 'reusability' || focus === 'all') interviewQuestions = interviewQuestions.concat(reusabilityQuestions);
+
+      let text = `**Prompt Improvement Analysis**\n\n`;
+      text += `**Name:** ${prompt.name || key}\n`;
+      text += `**Key (stable ID):** ${prompt.key || key}\n`;
+      text += `**Library:** ${prompt.library?.name || 'Unknown'}\n`;
+      text += `**Length:** ${lengthChars} characters, ${lines} line(s)\n`;
+      text += `**Variables:** ${foundVars.length ? foundVars.join(', ') : 'None'}\n`;
+      text += `**Has role guidance:** ${mentionsRole ? 'Yes' : 'No'}\n`;
+      text += `**Has output format guidance:** ${mentionsOutput ? 'Yes' : 'No'}\n`;
+      text += `**Pass:** ${pass}\n`;
+      text += focusNote;
+
+      if (improvementAreas.length) {
+        text += `\n**Suggested Improvement Areas:**\n`;
+        improvementAreas.forEach((area) => {
+          text += `- ${area}\n`;
+        });
+      } else {
+        text += `\n✅ No obvious structural issues detected. Focus on domain-specific refinements.\n`;
+      }
+
+      text += `\n**Interview Questions to Ask the User:**\n`;
+      interviewQuestions.forEach((q, i) => {
+        text += `${i + 1}. ${q}\n`;
+      });
+
+      text += `\n**Next Steps (for the agent):**\n`;
+      text += `- Ask the user some of the questions above.\n`;
+      text += `- Use the answers to propose changes via quick_iterate_prompt (updating content, description, and tags).\n`;
+      text += `- Optionally use rename_prompt to align key and display name if needed.\n`;
+
+      const metrics = {
+        prompt: {
+          key: prompt.key,
+          name: prompt.name,
+          library: prompt.library?.name || null,
+        },
+        metrics: {
+          lengthChars,
+          lines,
+          variables: foundVars,
+          hasRoleGuidance: mentionsRole,
+          hasOutputGuidance: mentionsOutput,
+        },
+      };
+
+      let deep = null;
+      if (pass === 'deep') {
+        // Very lightweight scoring per dimension; all heuristic.
+        const structureIssues = [];
+        if (!mentionsRole) structureIssues.push('missing_role');
+        if (!mentionsOutput) structureIssues.push('missing_output');
+        if (lengthChars < 300) structureIssues.push('too_short');
+
+        const structureScore = 100
+          - (structureIssues.includes('missing_role') ? 20 : 0)
+          - (structureIssues.includes('missing_output') ? 20 : 0)
+          - (structureIssues.includes('too_short') ? 10 : 0);
+
+        const variableScore = (() => {
+          if (!foundVars.length) return 60;
+          let score = 90;
+          if (!description.toLowerCase().includes('variable')) score -= 10;
+          return score;
+        })();
+
+        const edgeMention = /edge[- ]case|failure|error|invalid|fallback/i.test(content);
+        const edgeCasesScore = edgeMention ? 80 : 65;
+
+        const reusabilityScore = (() => {
+          let score = 80;
+          if (!foundVars.length) score -= 10;
+          if (lengthChars < 300) score -= 10;
+          return score;
+        })();
+
+        deep = {
+          dimensions: {
+            structure: {
+              score: Math.max(0, Math.min(100, structureScore)),
+              findings: structureIssues,
+            },
+            variables: {
+              score: Math.max(0, Math.min(100, variableScore)),
+              findings: foundVars,
+            },
+            edgeCases: {
+              score: Math.max(0, Math.min(100, edgeCasesScore)),
+              findings: edgeMention ? ['mentions edge cases or error handling'] : ['no explicit edge-case/error-handling guidance'],
+            },
+            reusability: {
+              score: Math.max(0, Math.min(100, reusabilityScore)),
+              findings: [],
+            },
+          },
+        };
+
+        text += `\n**Deep Analysis (scores are heuristic):**\n`;
+        text += `- Structure: ${deep.dimensions.structure.score}/100\n`;
+        text += `- Variables: ${deep.dimensions.variables.score}/100\n`;
+        text += `- Edge Cases: ${deep.dimensions.edgeCases.score}/100\n`;
+        text += `- Reusability: ${deep.dimensions.reusability.score}/100\n`;
+      }
+
+      const analysisJson = {
+        ...metrics,
+        improvementAreas,
+        interviewQuestions,
+        focus: focus || null,
+        pass,
+        deep,
+      };
+
+      return {
+        content: [
+          { type: 'text', text },
+          { type: 'text', text: '```json\n' + JSON.stringify(analysisJson, null, 2) + '\n```' },
+        ],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error improving prompt: ${error.message}` }] };
+    }
+  }
+
+  async renamePrompt(params = {}) {
+    try {
+      const result = await this.quickStartHandler.renamePrompt(params);
+      return {
+        content: [
+          { type: 'text', text: `✅ ${result.message}` },
+          { type: 'text', text: '```json\n' + JSON.stringify(result, null, 2) + '\n```' },
+        ],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error renaming prompt: ${error.message}` }] };
+    }
+  }
+
+  async quickCreatePrompt(params) {
+    try {
+      const result = await this.quickStartHandler.quickCreatePrompt(params);
+      return {
+        content: [
+          { type: 'text', text: `✅ ${result.message}\n\nNext steps:\n- Test it: quick_test_prompt(key="${result.key}")\n- Edit it: quick_iterate_prompt(key="${result.key}")` },
+          { type: 'text', text: '```json\n' + JSON.stringify(result, null, 2) + '\n```' }
+        ]
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error creating prompt: ${error.message}` }] };
+    }
+  }
+
+  async quickIteratePrompt(params) {
+    try {
+      const result = await this.quickStartHandler.quickIteratePrompt(params);
+      return {
+        content: [
+          { type: 'text', text: `✅ ${result.message}\n\n(Backup of previous version saved)` },
+          { type: 'text', text: '```json\n' + JSON.stringify(result, null, 2) + '\n```' }
+        ]
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error updating prompt: ${error.message}` }] };
+    }
+  }
+
+  getHelp({ topic } = {}) {
+    const topics = {
+      create: `
+**Creating Prompts**
+1. Use \`quick_create_prompt(name="my-prompt", content="...")\`
+2. It will be added to "My Library" by default.
+3. Use \`quick_test_prompt(key="my-prompt")\` to verify it.
+4. Use \`quick_iterate_prompt(key="...", name="...", description="...", tags=[...])\` to refine content & metadata.
+`,
+      publish: `
+**Publishing Prompts**
+1. Ensure your prompts are ready in a local library.
+2. Use \`publish_manifest_flow\` to pin to IPFS and propose to a SubDAO.
+3. This makes them available on-chain for others to discover.
+`,
+      versioning: `
+**Versioning**
+- \`quick_iterate_prompt\` automatically creates backups of the previous version.
+- Prompts are stored as files in \`~/.sage/libraries/prompts/\`, so you can use Git for version control.
+ - The \`key\` is a stable identifier used to reference the prompt; \`name\` is the human-readable display name.
+ - Use \`rename_prompt(key="old", newKey="new", name="New Name")\` when you truly need to change the key; otherwise, prefer updating \`name\` only.
+`,
+      manifest: `
+**Manifest Structure (v2)**
+
+Minimal example:
+
+\`\`\`json
+{
+  "version": 2,
+  "library": {
+    "name": "My Library",
+    "description": "Optional description"
+  },
+  "prompts": [
+    {
+      "key": "hello-world",
+      "name": "Hello World",
+      "description": "A simple test prompt",
+      "tags": ["test"],
+      "cid": "Qm...optional-ipfs-cid",
+      "files": ["prompts/hello-world.md"]
+    }
+  ]
+}
+\`\`\`
+
+Use \`validate_manifest(manifest=...)\` to see detailed errors and hints if anything is missing.
+`
+    };
+
+    if (topic && topics[topic]) {
+      return { content: [{ type: 'text', text: topics[topic] }] };
+    }
+
+    const generalHelp = `
+**Sage MCP Tools Help**
+
+**Quick Start:**
+- Create: \`quick_create_prompt(name="...", content="...")\`
+- Edit: \`quick_iterate_prompt(key="...", content="...")\`
+- Test: \`quick_test_prompt(key="...", variables={...})\`
+
+**Discovery:**
+- Browse: \`list_prompts()\`
+- Search: \`search_prompts(query="...")\`
+- Inspect: \`get_prompt(key="...")\`
+
+**Next Steps:**
+Use \`help(topic="create")\` for more details.
+`;
+    return { content: [{ type: 'text', text: generalHelp }] };
+  }
+
   async listLibraries(options = {}) {
     return this.listLibrariesHandler(options);
   }
@@ -978,22 +2159,23 @@ class SageMCPServer {
     if (!rows.length) {
       return { content: [{ type: 'text', text: 'No metaprompts saved yet. Use save_metaprompt to create one.' }] };
     }
-    const textLines = rows.map((row, idx) => `${idx + 1}. **${row.title}** (${row.slug})\n   🕒 Updated: ${row.updatedAt}\n   🔖 Tags: ${row.tags.join(', ') || 'none'}\n   📝 ${row.summary || 'No summary provided.'}\n`).join('\n');
+    const textLines = rows.map((row, idx) => `${idx + 1
+      }. ** ${row.title}** (${row.slug}) \n   🕒 Updated: ${row.updatedAt} \n   🔖 Tags: ${row.tags.join(', ') || 'none'} \n   📝 ${row.summary || 'No summary provided.'} \n`).join('\n');
     return {
       content: [
-        { type: 'text', text: `Metaprompts (${rows.length})\n\n${textLines}` },
-        { type: 'json', text: JSON.stringify({ metaprompts: rows }, null, 2) }
+        { type: 'text', text: `Metaprompts(${rows.length}) \n\n${textLines} ` },
+        { type: 'text', text: '```json\n' + JSON.stringify({ metaprompts: rows }, null, 2) + '\n```' }
       ]
     };
   }
 
-  startMetapromptInterview({ goal, model, interviewStyle }) {
-    const primer = metapromptDesigner.generateInterviewPrimer({ goal, model, interviewStyle });
-    const instructions = `Use the following guidance as your first message to the LLM interviewer:\n\n${primer}`;
+  startMetapromptInterview({ goal, model, interviewStyle, additionalInstructions }) {
+    const primer = metapromptDesigner.generateInterviewPrimer({ goal, model, interviewStyle, additionalInstructions });
+    const instructions = `Use the following guidance as your first message to the LLM interviewer: \n\n${primer} `;
     return {
       content: [
         { type: 'text', text: instructions },
-        { type: 'json', text: JSON.stringify({ primer, suggestedUse: 'Send as system message to initiate one-question-at-a-time interview.' }, null, 2) }
+        { type: 'text', text: '```json\n' + JSON.stringify({ primer, suggestedUse: 'Send as system message to initiate one - question - at - a - time interview.' }, null, 2) + '\n```' }
       ]
     };
   }
@@ -1020,7 +2202,7 @@ class SageMCPServer {
       const agentsPath = metapromptDesigner.getAgentsNotebookPath();
       try {
         fs.mkdirSync(path.dirname(agentsPath), { recursive: true });
-        const entry = `\n## ${title}\n\n${body}\n`;
+        const entry = `\n## ${title} \n\n${body} \n`;
         fs.appendFileSync(agentsPath, entry, 'utf8');
         extras.appendedToAgents = agentsPath;
       } catch (e) {
@@ -1036,14 +2218,14 @@ class SageMCPServer {
       ...extras,
     };
     const lines = [];
-    lines.push(`✅ Saved metaprompt '${title}' at ${saved.path}`);
+    lines.push(`✅ Saved metaprompt '${title}' at ${saved.path} `);
     if (destination && destination !== saved.path) {
-      lines.push(`📚 Workspace prompt: ${destination}`);
+      lines.push(`📚 Workspace prompt: ${destination} `);
     }
     return {
       content: [
         { type: 'text', text: lines.join('\n') },
-        { type: 'json', text: JSON.stringify(payload, null, 2) }
+        { type: 'text', text: '```json\n' + JSON.stringify(payload, null, 2) + '\n```' }
       ]
     };
   }
@@ -1054,13 +2236,13 @@ class SageMCPServer {
       const preview = loaded.body.slice(0, 800);
       return {
         content: [
-          { type: 'text', text: `Loaded metaprompt '${slug}'\n\n${preview}${loaded.body.length > 800 ? '\n... (truncated)' : ''}` },
-          { type: 'json', text: JSON.stringify({ slug, meta: loaded.meta, body: loaded.body, path: loaded.path }, null, 2) }
+          { type: 'text', text: `Loaded metaprompt '${slug}'\n\n${preview}${loaded.body.length > 800 ? '\n... (truncated)' : ''} ` },
+          { type: 'text', text: '```json\n' + JSON.stringify({ slug, meta: loaded.meta, body: loaded.body, path: loaded.path }, null, 2) + '\n```' }
         ]
       };
     } catch (error) {
       return {
-        content: [{ type: 'text', text: `Error loading metaprompt: ${error.message}` }]
+        content: [{ type: 'text', text: `Error loading metaprompt: ${error.message} ` }]
       };
     }
   }
@@ -1068,12 +2250,12 @@ class SageMCPServer {
   generateMetapromptLink({ body }) {
     const link = metapromptDesigner.generateChatGPTLink(body);
     const text = link
-      ? `ChatGPT link ready: ${link}`
+      ? `ChatGPT link ready: ${link} `
       : '⚠️  Prompt too long to produce a ChatGPT launch link. Copy the prompt manually.';
     return {
       content: [
         { type: 'text', text },
-        { type: 'json', text: JSON.stringify({ provider: 'chatgpt', link }, null, 2) }
+        { type: 'text', text: '```json\n' + JSON.stringify({ provider: 'chatgpt', link }, null, 2) + '\n```' }
       ]
     };
   }
@@ -1084,7 +2266,9 @@ class SageMCPServer {
       let content = '';
       const preferred = process.env.SAGE_IPFS_GATEWAY || '';
       const gateways = [
-        preferred ? `${preferred.replace(/\/$/, '')}/ipfs/${cid}` : null,
+        preferred ? `${preferred.replace(/\/$/, '')} /ipfs/${cid} ` : null,
+        `https://cloudflare-ipfs.com/ipfs/${cid}`,
+        `https://gateway.pinata.cloud/ipfs/${cid}`,
         `https://dweb.link/ipfs/${cid}`,
         `https://nftstorage.link/ipfs/${cid}`,
         `https://ipfs.io/ipfs/${cid}`
@@ -1111,7 +2295,7 @@ class SageMCPServer {
       if (!content) {
         return { content: [{ type: 'text', text: `Error downloading prompt content: ${lastErr ? lastErr.message : 'unknown error'}` }] };
       }
-      
+
       return {
         content: [
           {
@@ -1132,41 +2316,70 @@ class SageMCPServer {
     }
   }
 
-  async listSubDAOs({ limit = 20 }) {
+  async listSubDAOs({ limit = 20 } = {}) {
     try {
-      const subDAOs = await this.getSubDAOList();
+      const subDAOs = await this.getSubDAOList({ limit });
+
+      if (!subDAOs || subDAOs.length === 0) {
+        return {
+          content: [{
+            type: 'text',
+            text: 'No SubDAOs found.\n\n' +
+              'This may be because:\n' +
+              '• The subgraph is not configured (check SUBGRAPH_URL in .env)\n' +
+              '• The factory contract has no SubDAOs deployed yet\n' +
+              '• Network connectivity issues with the RPC endpoint\n\n' +
+              'Configuration:\n' +
+              `• SUBGRAPH_URL: ${process.env.SUBGRAPH_URL || 'not set'}\n` +
+              `• SUBDAO_FACTORY_ADDRESS: ${process.env.SUBDAO_FACTORY_ADDRESS || 'not set'}\n` +
+              `• RPC_URL: ${process.env.RPC_URL ? process.env.RPC_URL.substring(0, 50) + '...' : 'not set'}`
+          }]
+        };
+      }
+
       const limitedSubDAOs = subDAOs.slice(0, limit);
-      
-      const resultText = `Found ${limitedSubDAOs.length} SubDAOs:\n\n` +
-        limitedSubDAOs.map((subdao, i) => 
-          `${i + 1}. **${subdao.name}**\n` +
+      const resultText = `Found ${limitedSubDAOs.length} SubDAO(s):\n\n` +
+        limitedSubDAOs.map((subdao, i) =>
+          `${i + 1}. **${subdao.name || 'Unnamed SubDAO'}**\n` +
           `   📍 Address: ${subdao.address}\n` +
-          `   📋 Registry: ${subdao.registryAddress}\n\n`
+          `   📋 Registry: ${subdao.registryAddress || 'N/A'}\n` +
+          `   📚 Libraries: ${subdao.registries?.length || 0}\n\n`
         ).join('');
 
       return {
-        content: [
-          {
-            type: 'text',
-            text: resultText || 'No SubDAOs found.'
-          }
-        ]
+        content: [{
+          type: 'text',
+          text: resultText
+        }]
       };
     } catch (error) {
+      this.log?.error?.('list_subdaos_failed', {
+        error: error.message,
+        stack: error.stack,
+        subgraphUrl: process.env.SUBGRAPH_URL,
+        factoryAddress: process.env.SUBDAO_FACTORY_ADDRESS
+      });
+
       return {
-        content: [
-          {
-            type: 'text',
-            text: `Error listing SubDAOs: ${error.message}`
-          }
-        ]
+        content: [{
+          type: 'text',
+          text: `Error listing SubDAOs: ${error.message}\n\n` +
+            'This tool requires one of the following configurations:\n' +
+            '• SUBGRAPH_URL (recommended) - for fast SubDAO discovery\n' +
+            '• SUBDAO_FACTORY_ADDRESS + RPC_URL - for on-chain event scanning\n\n' +
+            'Current configuration:\n' +
+            `• SUBGRAPH_URL: ${process.env.SUBGRAPH_URL || '❌ not set'}\n` +
+            `• SUBDAO_FACTORY_ADDRESS: ${process.env.SUBDAO_FACTORY_ADDRESS || '❌ not set'}\n` +
+            `• RPC_URL: ${process.env.RPC_URL ? '✅ set' : '❌ not set'}\n\n` +
+            `Debug info: ${error.stack?.split('\n').slice(0, 3).join('\n')}`
+        }]
       };
     }
   }
 
   async listSubdaoLibraries({ subdao }) {
     const list = await this.getSubDAOList();
-    const found = list.find(x => (x.address || '').toLowerCase() === String(subdao||'').toLowerCase());
+    const found = list.find(x => (x.address || '').toLowerCase() === String(subdao || '').toLowerCase());
     if (!found) {
       // Attempt to rebuild from chain/subgraph
       const regs = await this._buildBindingsForSubdao(subdao);
@@ -1245,8 +2458,8 @@ class SageMCPServer {
     }
   }
 
-  async publishManifestFlow({ manifest, subdao = '', description = '' }) {
-    return this.manifestWorkflows.publishManifestFlow({ manifest, subdao, description });
+  async publishManifestFlow({ manifest, subdao = '', description = '', dry_run = false }) {
+    return this.manifestWorkflows.publishManifestFlow({ manifest, subdao, description, dry_run });
   }
 
   // Helper methods (same as HTTP server implementation)
@@ -1257,7 +2470,7 @@ class SageMCPServer {
   async searchSubDAOPrompts(allPrompts, targetSubDAO = '', includeContent = false) {
     try {
       const subDAOs = await this.getSubDAOList();
-      
+
       for (const subDAO of subDAOs) {
         if (targetSubDAO && subDAO.address.toLowerCase() !== targetSubDAO.toLowerCase()) {
           continue;
@@ -1289,11 +2502,11 @@ class SageMCPServer {
               const from = Math.max(earliest, to - WINDOW);
               const evsUpd = await contract.queryFilter(contract.filters.PromptUpdated(), from, to).catch(() => []);
               for (const e of evsUpd) {
-                try { const { key, cid } = e.args; latestPrompts.set(key, { cid: cid.toString() }); } catch {}
+                try { const { key, cid } = e.args; latestPrompts.set(key, { cid: cid.toString() }); } catch { }
               }
               const evsAdd = await contract.queryFilter(contract.filters.PromptAdded(), from, to).catch(() => []);
               for (const e of evsAdd) {
-                try { const cid = e.args.contentCID.toString(); const key = cid; if (!latestPrompts.has(key)) latestPrompts.set(key, { cid }); } catch {}
+                try { const cid = e.args.contentCID.toString(); const key = cid; if (!latestPrompts.has(key)) latestPrompts.set(key, { cid }); } catch { }
               }
               to = from - 1;
             }
@@ -1301,7 +2514,15 @@ class SageMCPServer {
             for (const [key, { cid }] of latestPrompts) {
               let content = '';
               if (includeContent && cid) {
-                try { const IPFSManager = require('./ipfs-manager'); const ipfs = new IPFSManager(); await ipfs.initialize(); content = await ipfs.downloadPrompt(cid); } catch {}
+                try {
+                  const IPFSManager = require('./ipfs-manager');
+                  const ipfs = new IPFSManager();
+                  await ipfs.initialize();
+                  const data = await ipfs.downloadJson(cid);
+                  content = data?.content || data?.prompt?.content || JSON.stringify(data);
+                } catch (_) {
+                  // Best-effort: leave content empty on failure
+                }
               }
               allPrompts.push({
                 id: `${subDAO.address}-${r.libraryId}-${key}`,
@@ -1340,7 +2561,7 @@ class SageMCPServer {
   hexToString(hex) {
     try {
       hex = hex.replace(/^0x/, '');
-      
+
       if (hex.length > 128) {
         // Skip the offset (first 64 chars)
         // Get the length from the next 64 chars
@@ -1348,7 +2569,7 @@ class SageMCPServer {
         const length = parseInt(lengthHex, 16) * 2;
         // Get the actual content
         const contentHex = hex.slice(128, 128 + length);
-        
+
         let result = '';
         for (let i = 0; i < contentHex.length; i += 2) {
           const byte = parseInt(contentHex.substr(i, 2), 16);
@@ -1370,7 +2591,7 @@ class SageMCPServer {
 if (require.main === module) {
   const server = new SageMCPServer();
   server.run().catch((error) => {
-    try { console.error('MCP Server error:', error); } catch(_) {}
+    try { console.error('MCP Server error:', error); } catch (_) { }
     process.exit(1);
   });
 }