@sage-protocol/cli 0.2.9 → 0.3.2

package/dist/cli/commands/skills.js

@@ -0,0 +1,737 @@
+const { Command } = require('commander');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { findWorkspaceSkills, resolveSkillFileByKey, readFrontmatter } = require('../services/skills/discovery');
+const secrets = require('../services/secrets');
+const https = require('https');
+const { readWorkspace, DEFAULT_DIR } = require('../services/prompts/workspace');
+
+function generateSkillsXml(skills) {
+  const mk = (s) => `<skill>\n<name>${s.name}</name>\n<description>${(s.summary || '').replace(/</g, '&lt;')}</description>\n<location>project</location>\n</skill>`;
+  const inner = skills.map(mk).join('\n\n');
+  return `<skills_system priority="1">\n\n## Available Skills\n\n<usage>\nUse these skills when they are relevant to the user's task.\n- Only use skills listed in <available_skills>\n- Do not duplicate content already in context\n- Load a single skill at a time as needed\n</usage>\n\n<available_skills>\n\n${inner}\n\n</available_skills>\n\n</skills_system>`;
+}
+
+function replaceSkillsSection(content, newSection) {
+  const startMarker = '<skills_system';
+  const endMarker = '</skills_system>';
+  if (content.includes(startMarker)) {
+    const regex = /<skills_system[^>]*>[\s\S]*?<\/skills_system>/;
+    return content.replace(regex, newSection);
+  }
+  const htmlStartMarker = '<!-- SKILLS_TABLE_START -->';
+  const htmlEndMarker = '<!-- SKILLS_TABLE_END -->';
+  if (content.includes(htmlStartMarker)) {
+    const inner = newSection.replace(/<skills_system[^>]*>|<\/skills_system>/g, '');
+    const regex = new RegExp(`${htmlStartMarker}[\\s\\S]*?${htmlEndMarker}`, 'g');
+    return content.replace(regex, `${htmlStartMarker}\n${inner}\n${htmlEndMarker}`);
+  }
+  return content.trimEnd() + '\n\n' + newSection + '\n';
+}
+
+function renderForTarget({ title, body }, target) {
+  const header = `# ${title}`;
+  if (target === 'cursor') {
+    return `${header}\n\n${body.trim()}\n`;
+  }
+  if (target === 'claude') {
+    return `${header}\n\n${body.trim()}\n`;
+  }
+  // browser / generic
+  return `${header}\n\n${body.trim()}\n`;
+}
+
+function register(program) {
+  const cmd = new Command('skills').description('Skills workflow (discover, iterate, export, and sync)');
+
+  cmd
+    .command('init')
+    .description('Initialize skills workspace')
+    .action(() => {
+      try {
+        const cwd = process.cwd();
+        const sageDir = path.join(cwd, '.sage');
+        const wsFile = path.join(sageDir, 'workspace.json');
+        const promptsDir = path.join(cwd, 'prompts');
+        const skillsDir = path.join(promptsDir, 'skills');
+
+        if (!fs.existsSync(sageDir)) fs.mkdirSync(sageDir);
+        if (!fs.existsSync(wsFile)) {
+          fs.writeFileSync(wsFile, JSON.stringify({ promptsDir: 'prompts' }, null, 2));
+          console.log('✅ Created .sage/workspace.json');
+        } else {
+          console.log('ℹ️  .sage/workspace.json already exists');
+        }
+
+        if (!fs.existsSync(promptsDir)) fs.mkdirSync(promptsDir);
+        if (!fs.existsSync(skillsDir)) {
+          fs.mkdirSync(skillsDir);
+          console.log('✅ Created prompts/skills/');
+        } else {
+          console.log('ℹ️  prompts/skills/ already exists');
+        }
+        
+        console.log('Skills workspace initialized.');
+      } catch (e) {
+        console.error('❌ init failed:', e.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('list')
+    .description('List workspace skills (flat files and SKILL.md directories)')
+    .option('--json', 'Output JSON', false)
+    .action((opts) => {
+      try {
+        const ws = readWorkspace() || {};
+        const promptsDir = ws.promptsDir || DEFAULT_DIR || 'prompts';
+        const skills = findWorkspaceSkills({ promptsDir });
+        if (opts.json) {
+          console.log(JSON.stringify({ skills }, null, 2));
+          return;
+        }
+        if (!skills.length) {
+          console.log('No skills found. Create prompts/skills/<name>.md or prompts/skills/<name>/SKILL.md');
+          return;
+        }
+        skills.forEach((s, i) => {
+          console.log(`${i + 1}. ${s.name} (${s.key})`);
+          if (s.summary) console.log(`   ${s.summary}`);
+          console.log(`   ${path.relative(process.cwd(), s.path)}`);
+        });
+      } catch (e) {
+        console.error('❌ list failed:', e.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('variant')
+    .description('Clone a skill into a new local variant (suffix appended)')
+    .argument('<key>', 'Skill key (e.g., skills/my-skill or skills/cat/my-skill)')
+    .argument('[suffix]', 'Suffix (e.g., v2)', 'v2')
+    .action((key, suffix) => {
+      try {
+        const ws = readWorkspace();
+        if (!ws) throw new Error('Workspace not found. Run `sage prompts init`.');
+        const resolved = resolveSkillFileByKey({ promptsDir: ws.promptsDir, key });
+        if (!resolved) throw new Error(`Skill not found for key '${key}'`);
+        const src = resolved.path;
+        const base = resolved.baseDir;
+        if (resolved.type === 'flat') {
+          const srcName = path.basename(src, '.md');
+          const dest = path.join(base, `${srcName}.${suffix}.md`);
+          fs.copyFileSync(src, dest);
+          // Update or create frontmatter with lineage
+          try {
+            const content = fs.readFileSync(dest, 'utf8');
+            if (content.startsWith('---')) {
+              const end = content.indexOf('\n---', 3);
+              if (end !== -1) {
+                let front = content.slice(3, end);
+                if (!/^\s*version\s*:/m.test(front)) front += `\nversion: ${suffix}`;
+                else front = front.replace(/^(\s*version\s*:\s*).+$/m, `$1${suffix}`);
+                if (!/^\s*forked_from\s*:/m.test(front)) front += `\nforked_from: ${key}`;
+                else front = front.replace(/^(\s*forked_from\s*:\s*).+$/m, `$1${key}`);
+                const updated = `---\n${front}\n---` + content.slice(end + 4);
+                fs.writeFileSync(dest, updated, 'utf8');
+              }
+            } else {
+              const updated = `---\nversion: ${suffix}\nforked_from: ${key}\n---\n\n${content}`;
+              fs.writeFileSync(dest, updated, 'utf8');
+            }
+          } catch (_) { /* best effort */ }
+          console.log(`✅ Created variant: ${path.relative(process.cwd(), dest)}`);
+          return;
+        }
+        // directory skill
+        const dirName = path.basename(base);
+        const parent = path.dirname(base);
+        const destDir = path.join(parent, `${dirName}.${suffix}`);
+        fs.cpSync(base, destDir, { recursive: true });
+        // Adjust frontmatter 'name' if present
+        const skillMd = path.join(destDir, 'SKILL.md');
+        if (fs.existsSync(skillMd)) {
+          const raw = fs.readFileSync(skillMd, 'utf8');
+          let replaced = raw.replace(/^(\s*name\s*:\s*)(.+)$/m, (_, p1, p2) => `${p1}${p2}.${suffix}`);
+          if (!/^\s*version\s*:/m.test(replaced)) replaced = replaced.replace(/^---\s*\n/, `---\nversion: ${suffix}\n`);
+          else replaced = replaced.replace(/^(\s*version\s*:\s*).+$/m, `$1${suffix}`);
+          if (!/^\s*forked_from\s*:/m.test(replaced)) replaced = replaced.replace(/^---\s*\n/, `---\nforked_from: ${key}\n`);
+          else replaced = replaced.replace(/^(\s*forked_from\s*:\s*).+$/m, `$1${key}`);
+          fs.writeFileSync(skillMd, replaced, 'utf8');
+        }
+        console.log(`✅ Created variant: ${path.relative(process.cwd(), destDir)}`);
+      } catch (e) {
+        console.error('❌ variant failed:', e.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('agents-sync')
+    .description('Update or append a skills section in AGENTS.md describing local skills')
+    .option('--json', 'Output JSON', false)
+    .action((opts) => {
+      try {
+        const ws = readWorkspace() || {};
+        const promptsDir = ws.promptsDir || DEFAULT_DIR || 'prompts';
+        const skills = findWorkspaceSkills({ promptsDir });
+        const xml = generateSkillsXml(skills);
+        const file = path.join(process.cwd(), 'AGENTS.md');
+        let content = '';
+        if (fs.existsSync(file)) content = fs.readFileSync(file, 'utf8');
+        const updated = replaceSkillsSection(content, xml);
+        fs.writeFileSync(file, updated, 'utf8');
+        if (opts.json) {
+          console.log(JSON.stringify({ ok: true, count: skills.length }, null, 2));
+          return;
+        }
+        console.log(`✅ Synced ${skills.length} skill(s) to AGENTS.md`);
+      } catch (e) {
+        console.error('❌ agents-sync failed:', e.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('export')
+    .description('Render a skill for a target environment')
+    .argument('<key>', 'Skill key')
+    .option('--as <target>', 'Target (cursor|claude|browser)', 'cursor')
+    .option('--write', 'Write to project defaults when supported (e.g., .cursor/rules)', false)
+    .action((key, opts) => {
+      try {
+        const ws = readWorkspace();
+        if (!ws) throw new Error('Workspace not found. Run `sage prompts init`.');
+        const resolved = resolveSkillFileByKey({ promptsDir: ws.promptsDir, key });
+        if (!resolved) throw new Error(`Skill not found for key '${key}'`);
+        const raw = fs.readFileSync(resolved.path, 'utf8');
+        const { meta, body } = readFrontmatter(raw);
+        const title = meta.title || path.basename(resolved.type === 'flat' ? resolved.path : path.dirname(resolved.path));
+        const out = renderForTarget({ title, body }, String(opts.as || 'cursor').toLowerCase());
+        if (opts.write && opts.as === 'cursor') {
+          const rulesDir = fs.existsSync('.cursor/rules') ? '.cursor/rules' : null;
+          if (!rulesDir) {
+            console.log(out);
+            console.warn('ℹ️ No .cursor/rules directory found. Printed to stdout instead.');
+            return;
+          }
+          const safe = key.replace(/[^a-z0-9/_\-.]/gi, '_').replace(/^skills\//, '').replace(/\//g, '__');
+          const dest = path.join(rulesDir, `sage--${safe}.md`);
+          fs.writeFileSync(dest, out, 'utf8');
+          console.log(`✅ Wrote Cursor rule: ${dest}`);
+          return;
+        }
+        console.log(out);
+      } catch (e) {
+        console.error('❌ export failed:', e.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('import')
+    .description('Import a skill from GitHub, OpenSkills dirs, or a local directory into prompts/skills')
+    .argument('<source>', 'Skill source: owner/repo[/path] | https URL | local dir | installed skill name')
+    .option('--from-dir <dir>', 'Explicit directory containing SKILL.md')
+    .option('-y, --yes', 'Skip interactive selection when importing a repo with multiple skills', false)
+    .action(async (source, opts) => {
+      try {
+        const ws = readWorkspace();
+        if (!ws) throw new Error('Workspace not found. Run `sage prompts init`.');
+
+        const toWorkspace = async (dir, origin = null) => {
+          const skillMd = path.join(dir, 'SKILL.md');
+          if (!fs.existsSync(skillMd)) throw new Error('SKILL.md not found in provided directory');
+          const raw = fs.readFileSync(skillMd, 'utf8');
+          
+          // Security: Size Check
+          if (raw.length > 100 * 1024) {
+             console.warn(`⚠️  WARNING: Skill file is large (${Math.round(raw.length/1024)}KB).`);
+             if (process.stdout.isTTY && !opts.yes) {
+               const inquirer = require('inquirer').default || require('inquirer');
+               const { confirm } = await inquirer.prompt([{ type: 'confirm', name: 'confirm', message: 'Import large file?', default: false }]);
+               if (!confirm) { console.log('Skipped.'); return; }
+             }
+          }
+          
+          const { meta, body } = readFrontmatter(raw);
+          
+          // Security: License Warning
+          if (!meta.license && !opts.yes) {
+             console.warn('⚠️  WARNING: No license specified in frontmatter.');
+          }
+
+          const skillName = (meta.title || path.basename(dir)).trim();
+          const destDir = path.join(ws.promptsDir, 'skills', skillName);
+          fs.mkdirSync(destDir, { recursive: true });
+          // Annotate source metadata into frontmatter
+          const sourceComment = `source: ${origin || dir}`;
+          fs.writeFileSync(
+            path.join(destDir, 'SKILL.md'),
+            `---\nname: ${skillName}\n${meta.summary ? `description: ${meta.summary}\n` : ''}${sourceComment ? `${sourceComment}\n` : ''}---\n\n${body.trim()}\n`,
+            'utf8',
+          );
+          console.log(`✅ Imported ${skillName} → ${path.relative(process.cwd(), destDir)}`);
+        };
+
+        // 1) Explicit dir override
+        if (opts.fromDir) return await toWorkspace(opts.fromDir);
+
+        // 2) If 'source' is a local directory path
+        if (fs.existsSync(source) && fs.statSync(source).isDirectory()) return await toWorkspace(source);
+
+        // 3) Try installed skill dirs (.agent/.claude), using provided name as directory
+        const installedRoots = [
+          path.join(process.cwd(), '.agent', 'skills'),
+          path.join(process.cwd(), '.claude', 'skills'),
+          path.join(os.homedir(), '.agent', 'skills'),
+          path.join(os.homedir(), '.claude', 'skills'),
+        ];
+        for (const r of installedRoots) {
+          const candidate = path.join(r, source);
+          if (fs.existsSync(path.join(candidate, 'SKILL.md'))) return await toWorkspace(candidate);
+        }
+
+        // 4) GitHub import: owner/repo[/path] or https URL
+        const isUrl = /^(https?:\/\/|git@)/i.test(source);
+        const isOwnerRepo = /^[^\s/]+\/[^\s/]+(\/.+)?$/.test(source);
+        if (!isUrl && !isOwnerRepo) {
+          throw new Error('Source not found. Provide a local dir, installed skill name, or owner/repo[/path].');
+        }
+        const { spawnSync } = require('child_process');
+        const osTmp = os.tmpdir();
+        const tmpRoot = path.join(osTmp, `sage-skill-${Date.now()}`);
+        fs.mkdirSync(tmpRoot, { recursive: true });
+
+        let repoUrl = source;
+        let subpath = '';
+        let owner = null;
+        let repo = null;
+        if (isOwnerRepo && !isUrl) {
+          const parts = source.split('/');
+          owner = parts[0];
+          repo = parts[1];
+          const base = `https://github.com/${owner}/${repo}`;
+          repoUrl = base;
+          if (parts.length > 2) subpath = parts.slice(2).join('/');
+        }
+
+        const cloneDir = path.join(tmpRoot, 'repo');
+        const envToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || (await secrets.get('github.token', {})) || '';
+        const gitPresent = spawnSync('git', ['--version'], { stdio: 'ignore' }).status === 0;
+        let clonedOk = false;
+        if (gitPresent) {
+          const gitArgs = ['clone', '--depth', '1'];
+          const r = envToken && /github\.com/i.test(repoUrl)
+            ? spawnSync('git', ['-c', `http.extraheader=AUTHORIZATION: bearer ${envToken}`, ...gitArgs, repoUrl, cloneDir], { stdio: 'inherit' })
+            : spawnSync('git', [...gitArgs, repoUrl, cloneDir], { stdio: 'inherit' });
+          clonedOk = (r.status === 0);
+        }
+        if (!clonedOk) {
+          // ZIP fallback using codeload.github.com
+          if (!owner || !repo) {
+            const m = repoUrl.match(/github\.com\/(.+?)\/(.+?)(?:$|\/)/i);
+            if (m) { owner = m[1]; repo = m[2]; }
+          }
+          if (!owner || !repo) throw new Error('Could not parse owner/repo for ZIP fallback');
+          const zipPath = path.join(tmpRoot, 'archive.zip');
+          const tryDownload = (ref) => new Promise((resolve, reject) => {
+            const url = `https://codeload.github.com/${owner}/${repo}/zip/refs/heads/${ref}`;
+            const file = fs.createWriteStream(zipPath);
+            const req = https.get(url, { headers: envToken ? { Authorization: `Bearer ${envToken}` } : {} }, (res) => {
+              if (res.statusCode && res.statusCode >= 400) { reject(new Error(`ZIP download failed: ${res.statusCode}`)); return; }
+              res.pipe(file);
+              file.on('finish', () => file.close(() => resolve({ ok: true, ref })));
+            });
+            req.on('error', reject);
+          });
+          let ok = false; let usedRef = 'main';
+          try { await tryDownload('main'); ok = true; usedRef = 'main'; } catch (_) {}
+          if (!ok) { try { await tryDownload('master'); ok = true; usedRef = 'master'; } catch (e) { throw e; } }
+          const unzip = spawnSync('unzip', ['-q', zipPath, '-d', tmpRoot], { stdio: 'inherit' });
+          if (unzip.status !== 0) throw new Error('unzip failed (install git or unzip, or use --from-dir)');
+          const expectedDir = path.join(tmpRoot, `${repo}-${usedRef}`);
+          if (!fs.existsSync(expectedDir)) {
+            // Fallback: find first directory
+            const entry = fs.readdirSync(tmpRoot, { withFileTypes: true }).find((e) => e.isDirectory() && e.name !== 'repo');
+            if (!entry) throw new Error('ZIP extract succeeded but repo dir not found');
+            fs.renameSync(path.join(tmpRoot, entry.name), cloneDir);
+          } else {
+            fs.renameSync(expectedDir, cloneDir);
+          }
+        }
+
+        const resolvedBase = subpath ? path.join(cloneDir, subpath) : cloneDir;
+        if (!fs.existsSync(resolvedBase)) throw new Error('Specified subpath not found in repository');
+
+        // Find skills (directories containing SKILL.md)
+        const candidates = [];
+        const stack = [resolvedBase];
+        while (stack.length) {
+          const curr = stack.pop();
+          const entries = fs.readdirSync(curr, { withFileTypes: true });
+          let hasSkill = false;
+          for (const e of entries) {
+            if (e.isFile() && e.name === 'SKILL.md') hasSkill = true;
+          }
+          if (hasSkill) {
+            candidates.push(curr);
+          } else {
+            for (const e of entries) if (e.isDirectory()) stack.push(path.join(curr, e.name));
+          }
+        }
+
+        if (candidates.length === 0) throw new Error('No SKILL.md directories found in repository');
+
+        let selected = candidates;
+        if (!opts.yes && candidates.length > 1 && process.stdout.isTTY) {
+          const inquirer = require('inquirer');
+          const { checkbox } = await inquirer.prompt([
+            {
+              type: 'checkbox',
+              name: 'checkbox',
+              message: 'Select skills to import',
+              choices: candidates.map((p) => ({ name: path.relative(cloneDir, p), value: p })),
+              pageSize: 12,
+            },
+          ]);
+          selected = checkbox;
+          if (!selected || !selected.length) {
+            console.log('Cancelled.');
+            return;
+          }
+        }
+
+        const originUrl = `https://github.com/${owner || 'unknown'}/${repo || 'unknown'}${subpath ? `/${subpath}` : ''}`;
+        for (const dir of selected) await toWorkspace(dir, originUrl);
+      } catch (e) {
+        console.error('❌ import failed:', e.message);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command('publish')
+    .description('Publish local skills to the on-chain library (Safe/Tally aware)')
+    .argument('[key]', 'Specific skill key to publish (default: all)')
+    .option('--subdao <address>', 'SubDAO/library address')
+    .option('--force', 'Ignore doctor warnings')
+    .option('--dry-run', 'Skip IPFS upload and transaction generation')
+    .action(async (key, opts) => {
+      try {
+        const fs = require('fs');
+        const { diagnoseSubDAO } = require('../services/governance/doctor');
+        const WalletManager = require('../wallet-manager');
+        const { readWorkspace } = require('../services/prompts/workspace');
+        const { findWorkspaceSkills } = require('../services/skills/discovery');
+        
+        // 1. Init Wallet & Context
+        const wallet = new WalletManager();
+        await wallet.connect();
+        const provider = wallet.getProvider();
+        const signer = wallet.getSigner();
+        
+        // 2. Doctor Preflight
+        console.log('🩺 Running Governance Doctor...');
+        const doctor = await diagnoseSubDAO({ subdao: opts.subdao, provider, signer });
+        
+        if (doctor.recommendations.length > 0) {
+            console.log('⚠️  Issues detected:');
+            doctor.recommendations.forEach(r => {
+                const msg = typeof r==='string' ? r : r.msg;
+                const fix = typeof r==='string' ? '' : (r.fix || r.fixCmd);
+                console.log(` - ${msg} ${fix ? `(Fix: ${fix})` : ''}`);
+            });
+            if (!opts.force && !process.env.SAGE_FORCE) {
+                console.error('❌ Aborting publish due to governance issues. Use --force to ignore.');
+                process.exit(1);
+            }
+        } else {
+            console.log('✅ Governance checks passed.');
+        }
+        
+        const subdaoAddr = doctor.subdao;
+        if (!subdaoAddr) throw new Error('SubDAO not resolved.');
+
+        // 3. Build Manifest
+        console.log('📦 Building manifest...');
+        const ws = readWorkspace() || {};
+        const skills = findWorkspaceSkills({ promptsDir: ws.promptsDir || 'prompts' });
+        // Filter if key provided? "sage skills publish my-skill" usually implies updating just that one?
+        // But manifest is usually holistic for the library.
+        // For now, publish ALL workspace skills as the new version of the library.
+        
+        if (skills.length === 0) throw new Error('No skills found to publish.');
+        
+        const manifest = {
+            version: '1.0.0',
+            timestamp: new Date().toISOString(),
+            skills: skills.map(s => ({
+                id: s.key,
+                metadata: s.meta,
+                // content? usually we upload content separately or include it?
+                // For a "skills library", we probably want content accessible.
+                // Let's assume we pin the SKILL.md files or include content in manifest.
+                // Including content in manifest is easier for MVP.
+                content: fs.readFileSync(s.path, 'utf8')
+            }))
+        };
+        
+        if (opts.dryRun) {
+            console.log('Dry run: Manifest would contain', skills.length, 'skills.');
+            return;
+        }
+
+        // 4. IPFS Upload
+        console.log('☁️  Uploading to IPFS...');
+        // Use IPFS Manager or Worker directly?
+        // Try to require IpfsManager
+        let cid;
+        try {
+            const IpfsManager = require('../ipfs-manager');
+            const ipfs = new IpfsManager();
+            // ipfs.uploadJson(json) returns CID string directly
+            cid = await ipfs.uploadJson(manifest, 'skills-manifest'); 
+            if (!cid) throw new Error('IPFS upload returned no CID');
+        } catch (e) {
+            // Fallback or error
+            throw new Error(`IPFS upload failed: ${e.message}`);
+        }
+        
+        console.log(`✅ Manifest uploaded: ${cid}`);
+        
+        // 5. Generate Transaction Payload
+        console.log('🚀 Generating Governance Payload...');
+        
+        // We need to call updateLibrary(cid) on the Registry or SubDAO?
+        // SubDAOs usually have a `updateLibrary` or `publishManifest` method?
+        // Or LibraryRegistry?
+        // "Creator Playbook": updateLibraryForSubDAO(subdao, libraryId, cid, ...)
+        
+        // Let's assume SubDAO has a `publish(cid)` or we call Registry.
+        // The architecture says: LibraryRegistry.
+        
+        const RegistryABI = require('../utils/factory-abi'); // Wait, need LibraryRegistry ABI
+        // We can construct Interface manually for updateLibrary
+        // function updateLibraryForSubDAO(address subdao, string calldata manifestCid)
+        const { ethers } = require('ethers');
+        const iface = new ethers.Interface(['function updateLibraryForSubDAO(address subdao, string manifestCid)']);
+        const calldata = iface.encodeFunctionData('updateLibraryForSubDAO', [subdaoAddr, cid]);
+        const config = require('../config');
+        // Resolve from env first, then active profile addresses (aliases supported)
+        const resolvedFromConfig = (() => {
+          try { return config.resolveAddress('LIBRARY_REGISTRY_ADDRESS', null); } catch (_) { return null; }
+        })();
+        const target = process.env.LIBRARY_REGISTRY_ADDRESS || resolvedFromConfig;
+        if (!process.env.LIBRARY_REGISTRY_ADDRESS && resolvedFromConfig) {
+          try {
+            const profiles = config.readProfiles?.() || {};
+            const active = profiles.activeProfile || 'default';
+            console.log(`ℹ️ Using LIBRARY_REGISTRY_ADDRESS from profile '${active}': ${target}`);
+          } catch (_) {}
+        }
+        // We need to ensure target is known. Doctor found it?
+        // doctor.registry might be PromptRegistry, NOT LibraryRegistry.
+        // We need LIBRARY_REGISTRY_ADDRESS.
+        if (!target) throw new Error('LIBRARY_REGISTRY_ADDRESS not set in env or active profile. Set env: export LIBRARY_REGISTRY_ADDRESS=0x... or run: sage config addresses (and add LIBRARY_REGISTRY_ADDRESS).');
+
+        // 6. Route based on Mode
+        if (doctor.mode === 1) {
+            // Community -> Tally
+            console.log('\n🗳️  Community Governance Detected (Token Voting)');
+            // Generate Tally URL
+            // Tally URL format: https://www.tally.xyz/gov/[slug]/proposal/create? ...
+            // We need the DAO slug or address. Tally uses address or slug.
+            // Let's output the data for now.
+            
+            console.log('\nProposal Details:');
+            console.log(`Target: ${target}`);
+            console.log(`Method: updateLibrary(${subdaoAddr}, ${cid})`);
+            console.log(`Calldata: ${calldata}`);
+            
+            console.log('\nCreate Proposal on Tally:');
+            console.log(`https://www.tally.xyz/gov/${subdaoAddr}/proposal/create`);
+            console.log('(Copy/paste the calldata above into the "Custom Action" field)');
+            
+        } else {
+            // Creator/Squad -> Safe / Direct
+            // Check if we are owner/admin
+            // If Squad (Multisig), output Safe JSON.
+            
+            console.log('\n🛡️  Team/Creator Governance Detected');
+            
+            // Output Safe JSON
+            const safeBatch = {
+                version: "1.0",
+                chainId: (await provider.getNetwork()).chainId.toString(),
+                createdAt: Date.now(),
+                meta: { name: "Update Skills Library", description: `Publish version ${cid}` },
+                transactions: [{
+                    to: target,
+                    value: "0",
+                    data: calldata,
+                    operation: 0 // Call
+                }]
+            };
+            
+            const filename = `safe-tx-${Date.now()}.json`;
+            fs.writeFileSync(filename, JSON.stringify(safeBatch, null, 2));
+            console.log(`✅ Safe Transaction Builder JSON saved to ${filename}`);
+            console.log('\n📋 Next steps:');
+            console.log(`   1. Import ${filename} in Safe Transaction Builder`);
+            console.log(`   2. Review and sign the transaction`);
+            console.log(`   3. Execute the transaction`);
+            if (subdaoAddr) {
+              console.log(`   4. Verify: sage library status --subdao ${subdaoAddr}`);
+            }
+        }
+
+      } catch (e) {
+        console.error('❌ publish failed:', e.message);
+        process.exit(1);
+      }
+    });
+
+  // QoL: publish-manifest (pin only, no governance)
+  cmd
+    .command('publish-manifest')
+    .description('Build and pin a manifest from workspace skills without proposing')
+    .option('--json', 'Output CID as JSON')
+    .action(async (opts) => {
+      try {
+        const { readWorkspace } = require('../services/prompts/workspace');
+        const { findWorkspaceSkills } = require('../services/skills/discovery');
+        const IpfsManager = require('../ipfs-manager');
+        const fs = require('fs');
+
+        console.log('📦 Building manifest...');
+        const ws = readWorkspace() || {};
+        const skills = findWorkspaceSkills({ promptsDir: ws.promptsDir || 'prompts' });
+        if (skills.length === 0) throw new Error('No skills found in workspace');
+        const manifest = {
+          version: '1.0.0',
+          timestamp: new Date().toISOString(),
+          skills: skills.map((s) => ({ id: s.key, metadata: s.meta, content: fs.readFileSync(s.path, 'utf8') })),
+        };
+
+        console.log('☁️  Uploading to IPFS...');
+        const ipfs = new IpfsManager();
+        const { cid } = await ipfs.uploadJson(manifest, 'skills-manifest');
+        if (opts.json) {
+          console.log(JSON.stringify({ ok: true, cid }, null, 2));
+        } else {
+          console.log(`✅ Manifest CID: ${cid}`);
+        }
+      } catch (e) {
+        console.error('❌ publish-manifest failed:', e.message);
+        process.exit(1);
+      }
+    });
+
+  // QoL: doctor wrapper for skills/governance readiness
+  cmd
+    .command('doctor')
+    .description('Validate workspace skills and diagnose SubDAO governance readiness')
+    .argument('[key]', 'Optional skill key to validate frontmatter')
+    .option('--subdao <address>', 'SubDAO address for governance checks')
+    .action(async (key, opts) => {
+      try {
+        const { readWorkspace } = require('../services/prompts/workspace');
+        const { resolveSkillFileByKey, readFrontmatter, findWorkspaceSkills } = require('../services/skills/discovery');
+        const { diagnoseSubDAO } = require('../services/governance/doctor');
+        const WalletManager = require('../wallet-manager');
+
+        // Validate skill frontmatter if requested
+        if (key) {
+          const ws = readWorkspace() || {};
+          const resolved = resolveSkillFileByKey({ promptsDir: ws.promptsDir || 'prompts', key });
+          if (!resolved) throw new Error(`Skill not found for key '${key}'`);
+          const fm = readFrontmatter(resolved.path);
+          console.log(`✅ Skill frontmatter OK for ${key}`);
+          console.log(fm);
+        } else {
+          // List count as a quick sanity
+          const ws = readWorkspace() || {};
+          const list = findWorkspaceSkills({ promptsDir: ws.promptsDir || 'prompts' });
+          console.log(`✅ Workspace skills found: ${list.length}`);
+        }
+
+        if (opts.subdao) {
+          const wallet = new WalletManager();
+          await wallet.connect();
+          const provider = wallet.getProvider();
+          const signer = wallet.getSigner();
+          console.log('🩺 Running Governance Doctor...');
+          const doctor = await diagnoseSubDAO({ subdao: opts.subdao, provider, signer });
+          console.log(JSON.stringify({
+            status: doctor.recommendations.length ? 'warn' : 'ok',
+            canPropose: doctor.canPropose === true,
+            subdao: doctor.subdao,
+            issues: doctor.recommendations,
+          }, null, 2));
+        }
+      } catch (e) {
+        console.error('❌ doctor failed:', e.message);
+        process.exit(1);
+      }
+    });
+
+  // QoL: use (MCP helper)
+  cmd
+    .command('use')
+    .description('Help use a skill with MCP (prints config; optional server start)')
+    .argument('<key>', 'Skill key (e.g., skills/my-skill)')
+    .option('--server-start', 'Start MCP HTTP server')
+    .option('--stdio-config', 'Print Claude Desktop stdio config snippet instead')
+    .action(async (key, opts) => {
+      try {
+        const path = require('path');
+        const chalk = require('chalk');
+        const { readWorkspace } = require('../services/prompts/workspace');
+        const { resolveSkillFileByKey } = require('../services/skills/discovery');
+
+        const ws = readWorkspace() || {};
+        const resolved = resolveSkillFileByKey({ promptsDir: ws.promptsDir || 'prompts', key });
+        if (!resolved) throw new Error(`Skill not found for key '${key}'`);
+
+        if (opts.stdioConfig) {
+          const stdioPath = path.resolve(__dirname, '..', 'mcp-server-stdio.js');
+          const snippet = {
+            mcpServers: {
+              sage: {
+                command: process.execPath,
+                args: [stdioPath],
+                env: {},
+              }
+            }
+          };
+          console.log(JSON.stringify(snippet, null, 2));
+          return;
+        }
+
+        if (opts.serverStart) {
+          const MCPServer = require('../mcp-server');
+          const server = new MCPServer({ port: 3333 });
+          await server.start();
+          console.log(chalk.green('✅ MCP server started on http://localhost:3333'));
+          console.log(chalk.cyan('Use in Cursor/Claude by configuring the HTTP/WS MCP server.'));
+          console.log(chalk.gray('Press Ctrl+C to stop.'));
+        } else {
+          console.log(chalk.cyan('To start the MCP server, run:'));
+          console.log('  sage mcp start');
+          console.log(chalk.cyan('For Claude stdio config, run:'));
+          console.log('  sage skills use', key, '--stdio-config');
+        }
+      } catch (e) {
+        console.error('❌ use failed:', e.message);
+        process.exit(1);
+      }
+    });
+
+  program.addCommand(cmd);
+}
+
+module.exports = { register };