@sage-protocol/cli 0.4.0 → 0.4.2

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

@@ -53,7 +53,13 @@ const { createLibraryLister, formatLibraryList } = require('./services/mcp/libra
 const { createSubdaoDiscovery } = require('./services/mcp/subdao-discovery');
 const { createUnifiedPromptSearcher } = require('./services/mcp/unified-prompt-search');
 const { createToolArgsValidator } = require('./services/mcp/tool-args-validator');
+const {
+  TOOL_REGISTRY,
+  getToolsForCategory,
+  getToolMeta,
+} = require('./services/mcp/sage-tool-registry');
 const { createToolDispatcher } = require('./services/mcp/tool-dispatcher');
+const ProjectContextService = require('./services/project-context');
 const { createProposalLister } = require('./services/mcp/proposal-lister');
 const fs = require('fs');
 const path = require('path');
@@ -79,6 +85,53 @@ class SageMCPServer {
     };
 
     this.tools = [
+      {
+        name: 'get_project_context',
+        description: `Get context about the current Sage project (root, DAO, counts, etc).
+When to use:
+- At the start of a session to understand where you are
+- Before suggesting tools to check if workspace/wallet is available`,
+        inputSchema: {
+          type: 'object',
+          properties: {},
+          required: []
+        }
+      },
+      {
+        name: 'suggest_sage_tools',
+        description: `Suggest the most relevant Sage MCP tools for a given goal.
+When to use:
+- You have a vague goal and want help choosing the right Sage tools
+- You want a ranked list of 3–5 tools with rationale and required parameters
+
+This tool does not execute any actions; it only recommends which tools to call next.`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            goal: { type: 'string', description: 'Free-text description of what you are trying to do' },
+            stage: {
+              type: 'string',
+              enum: ['prompt_workspace', 'persona', 'libraries', 'governance', 'treasury', 'discovery'],
+              description: 'Optional hint about which area you are working in',
+            },
+            context: {
+              type: 'object',
+              description: 'Optional execution context (workspace, wallet, etc.)',
+              properties: {
+                hasWorkspace: { type: 'boolean', description: 'Whether a Sage prompt workspace is present' },
+                hasWallet: { type: 'boolean', description: 'Whether a wallet is configured/available' },
+                currentTask: { type: 'string', description: 'Short description of what you just did' },
+              },
+            },
+            limit: { type: 'number', description: 'Maximum number of primary recommendations (default: 5)' },
+            includeAlternatives: {
+              type: 'boolean',
+              description: 'Whether to include a secondary list of alternative tools (default: false)',
+            },
+          },
+          required: ['goal'],
+        },
+      },
       {
         name: 'quick_create_prompt',
         description: `Quickly create a new prompt. Handles library creation automatically.
@@ -215,7 +268,7 @@ Next steps:
           properties: {
             query: { type: 'string', description: 'Free-text search applied to names, descriptions, and tags' },
             source: { type: 'string', enum: ['local', 'onchain', 'all'], description: 'Data source preference (default: all)' },
-            subdao: { type: 'string', description: 'Optional SubDAO address when source=onchain' },
+            subdao: { type: 'string', description: 'Optional DAO address when source=onchain' },
             tags: { type: 'array', items: { type: 'string' }, description: 'Optional tag filters (matches any tag)' },
             includeContent: { type: 'boolean', description: 'Include raw prompt content when supported (default: false)' },
             page: { type: 'number', description: 'Results page (default: 1)' },
@@ -309,7 +362,7 @@ Next steps:
       },
       {
         name: 'search_onchain_prompts',
-        description: 'Search for prompts directly on-chain from LibraryRegistry and SubDAO registries',
+        description: 'Search for prompts directly on-chain from LibraryRegistry and DAO registries',
         inputSchema: {
           type: 'object',
           properties: {
@@ -319,7 +372,7 @@ Next steps:
             },
             subdao: {
               type: 'string',
-              description: 'Filter by specific SubDAO address (optional)'
+              description: 'Filter by specific DAO address (optional)'
             },
             tags: {
               type: 'array',
@@ -374,6 +427,42 @@ Next steps:
           required: []
         }
       },
+      {
+        name: 'list_persona_templates',
+        description: 'List available persona templates for the Metaprompt Engine',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+          required: []
+        }
+      },
+      {
+        name: 'run_persona_interview',
+        description: 'Generate a persona system prompt from structured answers (One-Shot, no human loop)',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            template: { type: 'string', description: 'Template key (e.g., coding-assistant, governance-helper)' },
+            answers: { type: 'object', description: 'Key-value map of slot answers' },
+            save: { type: 'boolean', description: 'Whether to save the artifact to disk (default: false)' },
+            saveKey: { type: 'string', description: 'Optional filename for saving' }
+          },
+          required: ['template', 'answers']
+        }
+      },
+      {
+        name: 'persona_interview_step',
+        description: 'Stateful persona interview. Returns slot metadata for the host agent to phrase questions. Pass answers back with the stateToken to progress through slots.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            template: { type: 'string', description: 'Template key (coding-assistant, governance-helper, research-analyst, custom). Required on first call.' },
+            stateToken: { type: 'string', description: 'Base64-encoded state from previous response. Omit on first call.' },
+            answer: { type: 'string', description: 'Answer for the slot identified by currentSlotKey in the previous response.' }
+          },
+          required: []
+        }
+      },
       {
         name: 'save_metaprompt',
         description: 'Persist a metaprompt to the local Sage workspace and optionally append to agents.md',
@@ -427,13 +516,13 @@ Next steps:
       },
       {
         name: 'list_subdaos',
-        description: 'List all available SubDAOs in the Sage Protocol',
+        description: 'List all available DAOs in the Sage Protocol',
         inputSchema: {
           type: 'object',
           properties: {
             limit: {
               type: 'number',
-              description: 'Maximum number of SubDAOs to return (default: 20)'
+              description: 'Maximum number of DAOs to return (default: 20)'
             }
           },
           required: []
@@ -455,10 +544,10 @@ Next steps:
       },
       {
         name: 'refresh_library_bindings',
-        description: 'Refresh cached per-library registry mappings (optional: target a specific SubDAO)',
+        description: 'Refresh cached per-library registry mappings (optional: target a specific DAO)',
         inputSchema: {
           type: 'object',
-          properties: { subdao: { type: 'string', description: 'Optional SubDAO address (0x...)' } },
+          properties: { subdao: { type: 'string', description: 'Optional DAO address (0x...)' } },
           required: []
         }
       },
@@ -482,10 +571,10 @@ Next steps:
       },
       {
         name: 'list_subdao_libraries',
-        description: 'List per-library PromptRegistry mappings for a SubDAO',
+        description: 'List per-library PromptRegistry mappings for a DAO',
         inputSchema: {
           type: 'object',
-          properties: { subdao: { type: 'string', description: 'SubDAO address (0x...)' } },
+          properties: { subdao: { type: 'string', description: 'DAO address (0x...)' } },
           required: ['subdao']
         }
       },
@@ -513,13 +602,13 @@ Next steps:
       },
       {
         name: 'propose_manifest',
-        description: `Generate the proposal payload and CLI commands for a SubDAO update.
+        description: `Generate the proposal payload and CLI commands for a DAO governance 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: 'IPFS CID of the manifest' },
-            subdao: { type: 'string', description: 'SubDAO address' },
+            subdao: { type: 'string', description: 'DAO 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' }
@@ -563,11 +652,11 @@ Note: This tool does NOT sign transactions. It generates the hex data and CLI co
       },
       {
         name: 'list_proposals',
-        description: 'List active proposals for a SubDAO',
+        description: 'List active governance proposals for a DAO',
         inputSchema: {
           type: 'object',
           properties: {
-            subdao: { type: 'string', description: 'SubDAO address' },
+            subdao: { type: 'string', description: 'DAO address' },
             state: { type: 'string', description: 'Filter by state (Active, Executed, etc)' },
             limit: { type: 'number', description: 'Max items (default 10)' }
           },
@@ -586,7 +675,7 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
           type: 'object',
           properties: {
             manifest: { type: 'object', description: 'Manifest JSON' },
-            subdao: { type: 'string', description: 'Optional SubDAO address for hints' },
+            subdao: { type: 'string', description: 'Optional DAO address for hints' },
             description: { type: 'string', description: 'Optional description override' },
             dry_run: { type: 'boolean', description: 'Validate and build proposal payload without uploading to IPFS (no network calls)' }
           },
@@ -737,7 +826,7 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
       },
       {
         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.',
+        description: 'Suggest DAOs that might be a good fit for publishing a given local library, and provide CLI workflows for creating your own DAO and pushing the library.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -747,7 +836,7 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
             },
             limit: {
               type: 'number',
-              description: 'Max SubDAOs to return (default 5)',
+              description: 'Max DAOs to return (default 5)',
               default: 5
             },
             mode_filter: {
@@ -772,36 +861,15 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
             },
             target: {
               type: 'string',
-              description: 'Target SubDAO address or "auto" to pick a likely candidate',
+              description: 'Target DAO address or "auto" to pick a likely candidate',
               default: 'auto'
             }
           },
           required: ['library']
         }
       },
-      {
-        name: 'list_workspace_skills',
-        description: 'List local workspace skills from prompts/ (e.g. prompts/skills/*.md)',
-        inputSchema: {
-          type: 'object',
-          properties: {},
-          required: []
-        }
-      },
-      {
-        name: 'get_workspace_skill',
-        description: 'Load a workspace skill by key and return its content',
-        inputSchema: {
-          type: 'object',
-          properties: {
-            key: {
-              type: 'string',
-              description: 'Skill key relative to prompts dir (e.g. skills/backend-dev-guidelines)'
-            }
-          },
-          required: ['key']
-        }
-      }
+      // NOTE: list_workspace_skills and get_workspace_skill have been removed.
+      // Use list_prompts({ kind: 'skill' }) and get_prompt({ key }) instead.
     ];
 
     // Structured logger to stderr (stdout must remain JSON-RPC only)
@@ -835,6 +903,9 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
     // Local library helper for unified search
     this.libraryManager = new LibraryManager();
 
+    // Project context service for get_project_context tool
+    this.projectContextService = new ProjectContextService();
+
     // Simple rate limiter (token bucket per tool)
     this.rateConfig = { capacity: 20, refillPerSec: 0.33 }; // ~20/min
     this.rateLimiter = createRateLimiter(this.rateConfig);
@@ -1013,6 +1084,9 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
       'tool:get_prompts_from_manifest': (params) => this.getPromptsFromManifest(params),
       'tool:list_metaprompts': () => this.listMetaprompts(),
       'tool:start_metaprompt_interview': (params) => this.startMetapromptInterview(params),
+      'tool:list_persona_templates': () => this.listPersonaTemplates(),
+      'tool:run_persona_interview': (params) => this.runPersonaInterview(params),
+      'tool:persona_interview_step': (params) => this.personaInterviewStep(params),
       'tool:save_metaprompt': (params) => this.saveMetaprompt(params),
       'tool:get_metaprompt': (params) => this.getMetaprompt(params),
       'tool:generate_metaprompt_link': (params) => this.generateMetapromptLink(params),
@@ -1025,8 +1099,6 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
       'tool:list_proposals': (params) => this.listProposals(params),
       'tool:publish_manifest_flow': (params) => this.publishManifestFlow(params),
       '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),
@@ -1035,6 +1107,8 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
       'tool:analyze_dependencies': (params) => this.analyzeDependencies(params),
       'tool:suggest_subdaos_for_library': (params) => this.suggestSubdaosForLibrary(params),
       'tool:generate_publishing_commands': (params) => this.generatePublishingCommands(params),
+      'tool:suggest_sage_tools': (params) => this.suggestSageTools(params),
+      'tool:get_project_context': (params) => this.getProjectContext(params),
     });
 
     const toolHandlers = {
@@ -1202,93 +1276,9 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
   }
 
   // ───────────────────────── Workspace skills (repo-tied skills) ─────────────────────────
-
-  /**
-   * List skills defined in the current project's prompt workspace.
-   * Convention:
-   * - Workspace file: .sage/workspace.json (optional)
-   * - Prompts dir: workspace.promptsDir or "prompts"
-   * - Skill files live under promptsDir/skills/*.md
-   */
-  listWorkspaceSkills() {
-    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 results = findWorkspaceSkills({ promptsDir });
-      if (!results.length) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: 'No skills found. Create prompts/skills/<name>.md or prompts/skills/<name>/SKILL.md to define skills for this repo.',
-            },
-            { 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}` : ''
-            }${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: 'text', text: '```json\n' + JSON.stringify({ skills: results }, null, 2) + '\n```' },
-        ],
-      };
-    } catch (error) {
-      return {
-        content: [{ type: 'text', text: `Error listing workspace skills: ${error.message}` }],
-      };
-    }
-  }
-
-  /**
-   * Load a workspace skill by key and return its content.
-   * Key is relative to prompts dir, e.g. "skills/backend-dev-guidelines".
-   */
-  getWorkspaceSkill({ key }) {
-    try {
-      if (!key || !String(key).trim()) {
-        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 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 at ${path.relative(process.cwd(), expectedFlat)} or ${path.relative(process.cwd(), expectedDir)}`,
-            },
-          ],
-        };
-      }
-      const body = fs.readFileSync(resolved.path, 'utf8');
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Loaded workspace skill '${safeKey}' from ${path.relative(process.cwd(), resolved.path)}.\n\n${body}`,
-          },
-          { 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}` }] };
-    }
-  }
+  // NOTE: listWorkspaceSkills and getWorkspaceSkill have been removed.
+  // Use list_prompts({ kind: 'skill' }) and get_prompt({ key }) instead.
+  // ─────────────────────────────────────────────────────────────────────────────────────────
 
   async getPromptByName(params = {}) {
     const name = String(params.name || '').trim();
@@ -1381,38 +1371,87 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
     return this.searchPromptsUnifiedHandler(options);
   }
 
-  async listPrompts({ source = 'local', library = '', limit = 20 } = {}) {
+  async listPrompts({ source = 'local', library = '', limit = 20, kind, publishable } = {}) {
     try {
-      const results = await this.searchPromptsUnifiedHandler({
-        query: '',
-        source,
-        includeContent: false,
-        page: 1,
-        pageSize: limit
-      });
+      // If source is 'workspace' or we want to include workspace artifacts, use ArtifactManager
+      const includeWorkspace = source === 'local' || source === 'workspace' || source === 'all';
+
+      let workspaceResults = [];
+      if (includeWorkspace) {
+        const ArtifactManager = require('./services/artifact-manager');
+        const artifactManager = new ArtifactManager();
+        const filter = {};
+        if (kind) filter.kind = kind;
+        if (publishable !== undefined) filter.publishable = publishable;
+
+        const artifacts = await artifactManager.listArtifacts(filter);
+        workspaceResults = artifacts.map(a => ({
+          resultType: 'prompt',
+          origin: 'workspace',
+          source: 'Workspace',
+          key: a.key,
+          name: a.meta?.title || a.key,
+          description: a.meta?.summary || '',
+          tags: a.meta?.tags || [],
+          content: a.body,
+          kind: a.kind,
+          publishable: a.publishable,
+          publishing: a.publishing,
+          targets: a.targets,
+          filePath: a.filePath,
+        }));
+      }
 
-      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;
+      // Also get library prompts if not workspace-only
+      let libraryResults = [];
+      if (source !== 'workspace') {
+        const results = await this.searchPromptsUnifiedHandler({
+          query: '',
+          source: source === 'workspace' ? 'local' : source,
+          includeContent: false,
+          page: 1,
+          pageSize: limit
+        });
 
-          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```' }
-            ]
-          };
+        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]);
+            libraryResults = (data.results || []).map(r => ({
+              ...r,
+              kind: r.kind || 'prompt',
+              publishable: true, // library prompts are published
+              publishing: { status: 'published' }
+            }));
+          }
         }
       }
 
-      return results;
+      // Merge and filter
+      let allResults = [...workspaceResults, ...libraryResults];
+
+      // Filter by library if specified
+      if (library) {
+        const libraryLower = library.toLowerCase();
+        allResults = allResults.filter(r =>
+          r.library?.name?.toLowerCase().includes(libraryLower) ||
+          r.library?.cid?.toLowerCase().includes(libraryLower) ||
+          r.origin === 'workspace' // workspace prompts don't have library
+        );
+      }
+
+      // Apply limit
+      allResults = allResults.slice(0, limit);
+
+      const data = { results: allResults, total: allResults.length, page: 1, pageSize: limit };
+      const formatted = this.formatUnifiedResults(allResults, { total: data.total, page: 1, pageSize: limit });
+
+      return {
+        content: [
+          { type: 'text', text: formatted },
+          { type: 'text', text: '```json\n' + JSON.stringify(data, null, 2) + '\n```' }
+        ]
+      };
     } catch (error) {
       return { content: [{ type: 'text', text: `Error listing prompts: ${error.message}` }] };
     }
@@ -1424,6 +1463,41 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
         return { content: [{ type: 'text', text: 'Error: key parameter is required' }] };
       }
 
+      // First try workspace artifacts (ArtifactManager)
+      const ArtifactManager = require('./services/artifact-manager');
+      const artifactManager = new ArtifactManager();
+      const artifact = await artifactManager.getArtifact(key);
+
+      if (artifact) {
+        const prompt = {
+          resultType: 'prompt',
+          origin: 'workspace',
+          source: 'Workspace',
+          key: artifact.key,
+          name: artifact.meta?.title || artifact.key,
+          description: artifact.meta?.summary || '',
+          tags: artifact.meta?.tags || [],
+          content: artifact.body,
+          kind: artifact.kind,
+          publishable: artifact.publishable,
+          publishing: artifact.publishing,
+          targets: artifact.targets,
+          filePath: artifact.filePath,
+        };
+
+        const kindBadge = prompt.kind !== 'prompt' ? ` [${prompt.kind}]` : '';
+        const publishBadge = prompt.publishable ? '' : ' (local only)';
+        const text = `**${prompt.name}**${kindBadge}${publishBadge}\n\n🔑 Key: ${prompt.key}\n📂 Source: Workspace\n📄 ${prompt.description || 'No description'}\n🏷️ Tags: ${prompt.tags?.join(', ') || 'None'}\n📌 Kind: ${prompt.kind}\n📤 Publishable: ${prompt.publishable}\n📊 Status: ${prompt.publishing?.status || 'unknown'}\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```' }
+          ]
+        };
+      }
+
+      // Fall back to library search
       const results = await this.searchPromptsUnifiedHandler({
         query: key,
         source: 'local',
@@ -1452,7 +1526,12 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
             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\`\`\``;
+          // Add kind/publishable for library prompts
+          prompt.kind = prompt.kind || 'prompt';
+          prompt.publishable = true;
+          prompt.publishing = { status: 'published' };
+
+          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📌 Kind: ${prompt.kind}\n\n**Content:**\n\`\`\`\n${prompt.content || '(No content)'}\n\`\`\``;
 
           return {
             content: [
@@ -1585,6 +1664,61 @@ Note: This tool does NOT sign transactions. It prepares everything so you can ex
     }
   }
 
+  async getProjectContext(params) {
+    try {
+      const ctx = await this.projectContextService.getProjectContext(params || {});
+      const lines = [];
+      lines.push('✅ Project context');
+      lines.push(`Project root: ${ctx.projectRoot || 'not found'}`);
+      lines.push(`Prompts dir: ${ctx.promptsDir || 'prompts'}`);
+      if (ctx.subdao) {
+        lines.push(`SubDAO: ${ctx.subdao}`);
+      }
+      if (ctx.registry) {
+        lines.push(`Library registry: ${ctx.registry}`);
+      }
+      if (ctx.network) {
+        lines.push(`Network: ${ctx.network}`);
+      }
+      if (ctx.rpcUrl) {
+        lines.push(`RPC URL: ${ctx.rpcUrl}`);
+      }
+      if (ctx.workspace) {
+        lines.push(
+          `Workspace artifacts: prompts=${ctx.workspace.promptCount}, skills=${ctx.workspace.skillCount}, snippets=${ctx.workspace.snippetCount}, total=${ctx.workspace.total}`
+        );
+      }
+      if (ctx.agentSurfaces) {
+        const surfaces = [];
+        if (ctx.agentSurfaces.cursorRulesDir) {
+          surfaces.push(`cursor rules at ${ctx.agentSurfaces.cursorRulesDir}`);
+        }
+        if (ctx.agentSurfaces.claudeManifest) {
+          surfaces.push(`CLAUDE manifest at ${ctx.agentSurfaces.claudeManifest}`);
+        }
+        if (ctx.agentSurfaces.copilotPromptsDir) {
+          surfaces.push(`Copilot prompts at ${ctx.agentSurfaces.copilotPromptsDir}`);
+        }
+        if (Array.isArray(ctx.agentSurfaces.agentsFiles) && ctx.agentSurfaces.agentsFiles.length) {
+          surfaces.push(`AGENTS files: ${ctx.agentSurfaces.agentsFiles.join(', ')}`);
+        }
+        if (surfaces.length) {
+          lines.push('Agent surfaces:');
+          surfaces.forEach((s) => lines.push(`- ${s}`));
+        }
+      }
+
+      return {
+        content: [
+          { type: 'text', text: lines.join('\n') },
+          { type: 'text', text: '```json\n' + JSON.stringify(ctx, null, 2) + '\n```' },
+        ],
+      };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error retrieving project context: ${error.message}` }] };
+    }
+  }
+
   async listTemplates(params = {}) {
     try {
       const result = this.templateManager.listTemplates(params || {});
@@ -2453,6 +2587,274 @@ Use \`help(topic="create")\` for more details.
     return this.listLibrariesHandler(options);
   }
 
+  // ───────────────────────── Tool suggestion meta-router ─────────────────────────
+
+  tokenizeForMatching(text) {
+    if (!text) return [];
+    const lower = String(text).toLowerCase();
+    const tokens = lower.split(/[^a-z0-9]+/g).filter(Boolean);
+    // Small stopword list; just enough to ignore generic phrasing.
+    const stop = new Set([
+      'the', 'a', 'an', 'to', 'for', 'and', 'or', 'of', 'in', 'on', 'with', 'this', 'that',
+      'i', 'me', 'my', 'we', 'our', 'you', 'your',
+      'want', 'need', 'help', 'can', 'could', 'would', 'should',
+      'how', 'do', 'does', 'did', 'what', 'is', 'are', 'it', 'be',
+    ]);
+    return tokens.filter((t) => !stop.has(t));
+  }
+
+  inferStage(goal, explicitStage) {
+    if (explicitStage) return explicitStage;
+    if (!goal) return null;
+
+    const patterns = {
+      prompt_workspace: /\b(prompt|skill|workspace|create|edit|draft|write|local)\b/gi,
+      persona: /\b(persona|metaprompt|interview|agent|character|assistant|system prompt)\b/gi,
+      libraries: /\b(library|manifest|template|collection|import|export)\b/gi,
+      governance: /\b(publish|proposal|vote|subdao|dao|govern|approve|execute)\b/gi,
+      treasury: /\b(treasury|bond|boost|withdraw|sxxx|token|stake)\b/gi,
+      discovery: /\b(search|find|list|browse|explore|trending|discover)\b/gi,
+    };
+
+    const scores = {};
+    for (const [stage, pattern] of Object.entries(patterns)) {
+      const matches = goal.match(pattern) || [];
+      if (matches.length > 0) scores[stage] = matches.length;
+    }
+
+    const entries = Object.entries(scores);
+    if (!entries.length) return null;
+    entries.sort((a, b) => b[1] - a[1]);
+    return entries[0][0];
+  }
+
+  detectWorkflow(goal) {
+    if (!goal) return null;
+    const lower = goal.toLowerCase();
+
+    const workflows = [
+      {
+        // Create & publish a prompt/library
+        pattern: /create.*prompt.*publish|publish.*prompt|create.*library.*publish|publish.*library/i,
+        tools: ['quick_create_prompt', 'improve_prompt', 'publish_manifest_flow'],
+      },
+      {
+        // Design & (optionally) publish a persona
+        pattern: /create.*persona.*publish|design.*persona.*publish|persona.*publish/i,
+        tools: ['list_persona_templates', 'persona_interview_step', 'save_metaprompt', 'publish_manifest_flow'],
+      },
+      {
+        // Design a persona without explicit publishing intent
+        pattern: /design.*persona|create.*persona|persona.*workflow/i,
+        tools: ['list_persona_templates', 'persona_interview_step', 'save_metaprompt'],
+      },
+      {
+        // Find & iterate on prompts
+        pattern: /find.*prompt.*iterate|iterate.*prompt|improve.*prompt/i,
+        tools: ['search_prompts', 'get_prompt', 'quick_iterate_prompt'],
+      },
+      {
+        // Publish to a DAO/SubDAO
+        pattern: /publish.*dao|dao.*publish|publish.*subdao|subdao.*publish/i,
+        tools: ['suggest_subdaos_for_library', 'generate_publishing_commands', 'publish_manifest_flow'],
+      },
+    ];
+
+    for (const wf of workflows) {
+      if (wf.pattern.test(lower)) {
+        return wf.tools;
+      }
+    }
+    return null;
+  }
+
+  scoreToolForGoal(toolMeta, goalTokens, stage) {
+    // BM25-inspired scoring with simple term frequency and length normalization.
+    const baseTerms = [
+      ...(toolMeta.keywords || []),
+      ...this.tokenizeForMatching(toolMeta.description || ''),
+      ...this.tokenizeForMatching(toolMeta.whenToUse || ''),
+    ];
+
+    const docLen = baseTerms.length || 1;
+    const avgLen = 15;
+    const k1 = 1.2;
+    const b = 0.75;
+
+    let score = 0;
+
+    for (const token of goalTokens) {
+      const tf = baseTerms.filter((t) => t === token).length;
+      if (tf > 0) {
+        const tfScore = (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * (docLen / avgLen)));
+        score += tfScore;
+      }
+    }
+
+    // Negative keyword penalty.
+    if (toolMeta.negativeKeywords && toolMeta.negativeKeywords.length) {
+      let penalties = 0;
+      for (const neg of toolMeta.negativeKeywords) {
+        if (goalTokens.includes(neg)) penalties += 1;
+      }
+      if (penalties > 0) {
+        score *= (0.5 ** penalties);
+      }
+    }
+
+    // Stage/category boost.
+    if (stage && toolMeta.category === stage) {
+      score *= 1.5;
+    }
+
+    // Base weight.
+    const weight = typeof toolMeta.weight === 'number' ? toolMeta.weight : 1;
+    score *= weight;
+
+    // Normalize to 0–1 range.
+    return Math.min(score / 5, 1);
+  }
+
+  orderSuggestedTools(scored, limit) {
+    if (!Array.isArray(scored) || !scored.length) return [];
+    const sorted = [...scored].sort((a, b) => b.confidence - a.confidence).slice(0, limit);
+    if (sorted.length <= 3) {
+      return sorted.map((item, idx) => ({ ...item, priority: idx + 1 }));
+    }
+
+    // Simple U-shaped ordering: higher-ranked items gravitate to the ends.
+    const result = [];
+    for (let i = 0; i < sorted.length; i += 1) {
+      if (i % 2 === 0) {
+        // Even indices append to the end
+        result.push(sorted[i]);
+      } else {
+        // Odd indices unshift to the front
+        result.unshift(sorted[i]);
+      }
+    }
+
+    return result.map((item, idx) => ({ ...item, priority: idx + 1 }));
+  }
+
+  async suggestSageTools(params) {
+    // Arguments are already validated by createToolArgsValidator.
+    const { goal, stage, context, limit = 5, includeAlternatives = false } = params || {};
+
+    const effectiveStage = this.inferStage(goal, stage);
+    const goalTokens = this.tokenizeForMatching(goal);
+
+    // Choose candidate tools from registry.
+    let candidates = [];
+    if (effectiveStage === 'discovery') {
+      // Discovery is intentionally cross-cutting; surface the most browse/search oriented tools.
+      const discoveryTools = ['search_prompts', 'list_prompts', 'trending_prompts', 'list_persona_templates', 'list_libraries'];
+      candidates = discoveryTools
+        .map((name) => getToolMeta(name))
+        .filter(Boolean);
+    } else if (effectiveStage) {
+      candidates = getToolsForCategory(effectiveStage);
+    } else {
+      // If no clear stage, fall back to a small set of discovery-friendly tools.
+      const discoveryTools = ['search_prompts', 'list_prompts', 'trending_prompts', 'list_persona_templates', 'list_libraries'];
+      candidates = discoveryTools
+        .map((name) => getToolMeta(name))
+        .filter(Boolean);
+    }
+
+    // Cross-category fallback: if we have a clear stage, allow strongly-matching tools
+    // from other categories to join the candidate set.
+    if (effectiveStage) {
+      const allTools = Object.entries(TOOL_REGISTRY).map(([name, meta]) => ({ name, ...meta }));
+      const existingNames = new Set(candidates.map((c) => c.name));
+      const crossCategory = allTools
+        .filter((t) => t.category !== effectiveStage && !existingNames.has(t.name))
+        .map((t) => ({
+          ...t,
+          confidence: this.scoreToolForGoal(t, goalTokens, null),
+        }))
+        .filter((t) => t.confidence > 0.6);
+
+      if (crossCategory.length) {
+        candidates = candidates.concat(crossCategory);
+      }
+    }
+
+    // Apply simple context-based filtering/hints.
+    if (context && context.hasWorkspace === false) {
+      // If there is no workspace, de-prioritize workspace-only tools.
+      candidates = candidates.map((c) => {
+        if (c.category === 'prompt_workspace') {
+          return { ...c, weight: (c.weight || 1) * 0.7 };
+        }
+        return c;
+      });
+    }
+
+    // Score tools.
+    const scored = candidates.map((meta) => ({
+      ...meta,
+      confidence: this.scoreToolForGoal(meta, goalTokens, effectiveStage),
+    })).filter((item) => item.confidence >= 0.15);
+
+    if (!scored.length) {
+      const fallback = {
+        recommendations: [],
+        alternatives: [],
+        inferredStage: effectiveStage || null,
+        suggestedWorkflow: null,
+      };
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(fallback, null, 2),
+        }],
+      };
+    }
+
+    const ordered = this.orderSuggestedTools(scored, limit);
+    const workflow = this.detectWorkflow(goal);
+
+    const recommendations = ordered.map((item) => ({
+      toolName: item.name,
+      category: item.category,
+      confidence: item.confidence,
+      priority: item.priority,
+      rationale: item.whenToUse,
+      requiredParams: item.requiredParams || [],
+    }));
+
+    let alternatives = [];
+    if (includeAlternatives) {
+      const remaining = scored
+        .filter((s) => !ordered.find((r) => r.name === s.name))
+        .sort((a, b) => b.confidence - a.confidence)
+        .slice(0, limit);
+      alternatives = remaining.map((item, idx) => ({
+        toolName: item.name,
+        category: item.category,
+        confidence: item.confidence,
+        priority: idx + 1,
+        rationale: item.whenToUse,
+        requiredParams: item.requiredParams || [],
+      }));
+    }
+
+    const result = {
+      recommendations,
+      alternatives,
+      inferredStage: effectiveStage || null,
+      suggestedWorkflow: workflow || null,
+    };
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result, null, 2),
+      }],
+    };
+  }
+
   listMetaprompts() {
     const rows = metapromptDesigner.listMetaprompts();
     if (!rows.length) {
@@ -2848,6 +3250,207 @@ Use \`help(topic="create")\` for more details.
     }
   }
 
+  // ───────────────────────────── Metaprompt Engine Tools ─────────────────────────────
+
+  async listPersonaTemplates() {
+    try {
+      const templates = require('./services/metaprompt/templates.json');
+      const list = Object.values(templates).map(t => ({
+        key: t.key,
+        name: t.name,
+        description: t.description,
+        recommended_slots: t.recommended_slots?.map(s => s.label) || []
+      }));
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(list, null, 2)
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Failed to list templates: ${error.message}` }]
+      };
+    }
+  }
+
+  async runPersonaInterview(params) {
+    const { template, answers, save, saveKey } = params;
+    try {
+      const config = require('./config');
+      const PromptBuilder = require('./services/metaprompt/prompt-builder');
+      const MetapromptPersistence = require('./services/metaprompt/persistence');
+      const templates = require('./services/metaprompt/templates.json');
+
+      // 1. Validate Template
+      const templateDef = templates[template] || templates['custom'];
+
+      // 2. Build Prompt (One-Shot)
+      // Note: run_persona_interview assumes the *agent* has already done the planning/filling.
+      // It bypasses the SlotPlanner and just builds the artifact.
+      const builder = new PromptBuilder();
+      // We need the full slot definitions to build dynamic sections.
+      // Since we skipped the planner, we'll use the template's recommended slots as the definition.
+      const slots = templateDef.recommended_slots || [];
+
+      const systemPrompt = builder.buildSystemPrompt(template, slots, answers || {});
+
+      let result = {
+        systemPrompt,
+        slug: '',
+        paths: {}
+      };
+
+      // 3. Save (Optional)
+      if (save) {
+        const persistence = new MetapromptPersistence(config);
+        const slug = saveKey || `${template}-${Date.now().toString().slice(-6)}`;
+
+        // Save dummy history so the artifact exists
+        const historyPaths = persistence.saveMetaprompt(slug, {
+          templateKey: template,
+          transcript: [{ role: 'system', content: 'Generated via MCP run_persona_interview (one-shot).' }],
+          answers: answers || {}
+        });
+
+        // Save Skill
+        const skillPath = persistence.saveSkill(slug, systemPrompt);
+
+        result.slug = slug;
+        result.paths = {
+          metaprompt: historyPaths.metaprompt,
+          skill: skillPath
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Failed to run persona interview: ${error.message}` }]
+      };
+    }
+  }
+
+  /**
+   * Stateful persona interview that walks through template slots.
+   *
+   * Returns slot metadata (label, description, group) for the host agent to phrase questions.
+   * The agent passes answers back with the stateToken to progress through slots.
+   * When all required slots are filled, returns the generated system prompt.
+   *
+   * @param {object} params
+   * @param {string} params.template - Template key (coding-assistant, governance-helper, etc.)
+   * @param {string} [params.stateToken] - Base64-encoded state from previous call
+   * @param {string} [params.answer] - Answer for the current slot (currentSlotKey from previous response)
+   */
+  async personaInterviewStep(params) {
+    const { template, stateToken, answer } = params;
+    try {
+      const templates = require('./services/metaprompt/templates.json');
+      const PromptBuilder = require('./services/metaprompt/prompt-builder');
+
+      // 1. Restore or initialize state
+      let state;
+      if (stateToken) {
+        try {
+          state = JSON.parse(Buffer.from(stateToken, 'base64').toString('utf8'));
+        } catch {
+          return { isError: true, content: [{ type: 'text', text: 'Invalid stateToken' }] };
+        }
+      } else {
+        // Initialize new interview state
+        const templateKey = template || 'custom';
+        const templateDef = templates[templateKey] || templates.custom;
+        state = {
+          templateKey,
+          slots: templateDef.recommended_slots || [],
+          answers: {},
+          currentSlotKey: null,
+        };
+      }
+
+      // 2. Record answer for the current slot (if provided)
+      if (answer && state.currentSlotKey) {
+        state.answers[state.currentSlotKey] = answer;
+      }
+
+      // 3. Find next unanswered slot (required first, then optional by priority)
+      const unanswered = state.slots.filter(s => !state.answers[s.key]);
+      const requiredUnanswered = unanswered.filter(s => s.required);
+      const nextSlot = requiredUnanswered[0] || unanswered.find(s => s.priority <= 2) || null;
+
+      // 4. Update state with current slot key
+      state.currentSlotKey = nextSlot?.key || null;
+
+      // 5. Serialize state for next call
+      const newStateToken = Buffer.from(JSON.stringify(state)).toString('base64');
+
+      // 6. Check if interview is complete
+      if (!nextSlot) {
+        // All required slots filled - build the system prompt (no LLM needed)
+        const builder = new PromptBuilder();
+        const systemPrompt = builder.buildSystemPrompt(state.templateKey, state.slots, state.answers);
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              done: true,
+              systemPrompt,
+              template: state.templateKey,
+              answers: state.answers,
+              filledSlots: Object.keys(state.answers).length,
+              totalSlots: state.slots.length,
+              stateToken: newStateToken,
+            }, null, 2)
+          }]
+        };
+      }
+
+      // 7. Return next slot info for the host LLM to phrase the question
+      // The host LLM should use slotLabel/slotDescription to ask the user
+      const suggestedQuestion = `Please provide: ${nextSlot.label}. ${nextSlot.description || ''}`.trim();
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            done: false,
+            currentSlotKey: nextSlot.key,
+            slotLabel: nextSlot.label,
+            slotDescription: nextSlot.description || '',
+            slotGroup: nextSlot.group || 'general',
+            slotRequired: nextSlot.required || false,
+            suggestedQuestion,
+            filledSlots: Object.keys(state.answers).length,
+            totalSlots: state.slots.length,
+            remainingRequired: requiredUnanswered.length,
+            stateToken: newStateToken,
+          }, null, 2)
+        }]
+      };
+
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Failed to execute interview step: ${error.message}` }]
+      };
+    }
+  }
+
   async getSubDAOList(options = {}) {
     try {
       return await this.subdaoDiscovery.listSubDaos(options);