@sage-protocol/cli 0.2.9 → 0.3.2

package/dist/cli/commands/subdao.js

@@ -208,6 +208,74 @@ function register(program) {
     .description('SubDAO management commands')
     .addHelpText('afterAll', '\nGuided launch walkthrough: sage help workflow subdao-launch\n')
     .addHelpText('after', `\nExamples:\n  $ sage subdao save 0xAbc... --alias team-alpha\n  $ sage subdao pick\n  $ sage subdao use team-alpha\n  $ sage subdao info team-alpha --json\n\nTemplates:\n  1. rapid-iteration   - Fast community voting (testnet)\n  2. standard-secure   - Balanced community governance\n  3. team              - Safe multisig for small teams (was: operator)\n`)
+    .addCommand(
+      new Command('create-playbook')
+        .description('Create a new SubDAO using a governance playbook (Plan/Apply)')
+        .option('--playbook <id>', 'Playbook ID (creator, squad, community, community-long)')
+        .option('--name <name>', 'SubDAO name')
+        .option('--description <desc>', 'SubDAO description')
+        .option('--owners <addresses>', 'Safe owners (comma-separated)')
+        .option('--threshold <n>', 'Safe threshold')
+        .option('--min-stake <amount>', 'Minimum stake amount (SXXX)')
+        .option('--voting-period <duration>', 'Voting period (e.g., "3 days", "36 hours", "720 minutes")')
+        .option('--quorum-bps <bps>', 'Quorum basis points (e.g., 200 for 2%)')
+        .option('--proposal-threshold <amount>', 'Proposal threshold (wei or token units as string)')
+        .option('--block-time-sec <n>', 'Override block time (seconds per block); auto-detected when omitted')
+        .option('--wizard', 'Prompt for governance parameters interactively')
+        .option('--yes', 'Skip confirmation')
+        .option('--dry-run', 'Generate plan only (do not execute)')
+        .option('--apply <file>', 'Apply a previously generated plan file')
+        .action(async (opts) => {
+          try {
+            if (opts.apply) {
+              const { applyPlan } = require('../services/subdao/applier');
+              await applyPlan(opts.apply);
+              return;
+            }
+
+            // Optional wizard for governance parameters
+            if (opts.wizard) {
+              const inquirer = (require('inquirer').default || require('inquirer'));
+              const answers = await inquirer.prompt([
+                { type: 'input', name: 'votingPeriod', message: 'Voting period (e.g., 7 days)', default: opts.votingPeriod || '' },
+                { type: 'input', name: 'quorumBps', message: 'Quorum (bps, e.g., 200 for 2%)', default: opts.quorumBps || '' },
+                { type: 'input', name: 'proposalThreshold', message: 'Proposal threshold (string/wei)', default: opts.proposalThreshold || '' },
+                { type: 'input', name: 'blockTimeSec', message: 'Seconds per block (blank = auto-detect)', default: opts.blockTimeSec || '' },
+              ]);
+              opts.votingPeriod = answers.votingPeriod || opts.votingPeriod;
+              opts.quorumBps = answers.quorumBps || opts.quorumBps;
+              opts.proposalThreshold = answers.proposalThreshold || opts.proposalThreshold;
+              opts.blockTimeSec = answers.blockTimeSec || opts.blockTimeSec;
+            }
+
+            const { planSubDAO } = require('../services/subdao/planner');
+            const plan = await planSubDAO(opts);
+            
+            console.log(JSON.stringify(plan, null, 2));
+            
+            if (opts.dryRun) {
+              const fs = require('fs');
+              const filename = `subdao-plan-${Date.now()}.json`;
+              fs.writeFileSync(filename, JSON.stringify(plan, null, 2));
+              console.log(`\n✅ Plan saved to ${filename}`);
+              return;
+            }
+
+            const inquirer = (require('inquirer').default || require('inquirer'));
+            if (!opts.yes) {
+              const { confirm } = await inquirer.prompt([{ type: 'confirm', name: 'confirm', message: 'Apply this plan?', default: true }]);
+              if (!confirm) return;
+            }
+
+            const { applyPlan } = require('../services/subdao/applier');
+            await applyPlan(plan);
+
+          } catch (e) {
+            console.error('❌ Create failed:', e.message);
+            process.exit(1);
+          }
+        })
+    )
     .addCommand(
       new Command('create-wizard')
         .description('Interactive SubDAO creation wizard (choose governance type and access model)')
@@ -556,140 +624,36 @@ function register(program) {
         .option('--json', 'Output JSON', false)
         .action(async (opts) => {
           try {
-            const { ethers } = require('ethers');
-            const { resolveGovContext } = require('../utils/gov-context');
+            const { diagnoseSubDAO } = require('../services/governance/doctor');
+            const { getSignerSession } = require('../utils/cli-session');
             const { signer, provider } = await getSignerSession();
-            const ctx = await resolveGovContext({ govOpt: undefined, subdaoOpt: opts.subdao, provider });
-            const subdao = ctx.subdao;
-            if (!subdao) throw new Error('SubDAO not resolved. Pass --subdao or save one in profile via `sage context use --subdao <addr>`.');
-            const governor = ctx.governor; const timelock = ctx.timelock;
-            if (!governor || !timelock) throw new Error('Failed to resolve governor/timelock from --subdao');
-            const out = { subdao, governor, timelock };
-            try {
-              const sd = new ethers.Contract(subdao, [
-                'function getGovernanceMode() view returns (uint8)',
-                'function promptRegistry() view returns (address)'
-              ], provider);
-              out.mode = Number(await sd.getGovernanceMode());
-              out.registry = await sd.promptRegistry();
-            } catch(_){}
-            try { const tl = new ethers.Contract(timelock, ['function getMinDelay() view returns (uint256)','function PROPOSER_ROLE() view returns (bytes32)','function EXECUTOR_ROLE() view returns (bytes32)','function DEFAULT_ADMIN_ROLE() view returns (bytes32)','function hasRole(bytes32,address) view returns (bool)'], provider);
-              out.minDelay = String(await tl.getMinDelay().catch(()=>0n));
-              const PROPOSER = await tl.PROPOSER_ROLE();
-              const EXECUTOR = await tl.EXECUTOR_ROLE();
-              const ADMIN = await tl.DEFAULT_ADMIN_ROLE();
-              out.govIsProposer = await tl.hasRole(PROPOSER, governor).catch(()=>false);
-              out.anyoneExec = await tl.hasRole(EXECUTOR, ethers.ZeroAddress).catch(()=>false);
-              out.signerIsAdmin = await tl.hasRole(ADMIN, await signer.getAddress()).catch(()=>false);
-            } catch(_){}
-            // Prompt registry governance handover / timelock wiring
-            try {
-              if (out.registry) {
-                const reg = new ethers.Contract(out.registry, [
-                  'function adminHandoverComplete() view returns (bool)',
-                  'function governor() view returns (address)',
-                  'function subDAO() view returns (address)'
-                ], provider);
-                out.registryAdminHandoverComplete = await reg.adminHandoverComplete().catch(()=>false);
-                out.registryGovernor = await reg.governor().catch(()=>ethers.ZeroAddress);
-                out.registrySubDAO = await reg.subDAO().catch(()=>ethers.ZeroAddress);
-              }
-            } catch(_) {}
-
-            // LibraryRegistry scoped roles (if configured)
-            try {
-              const cfg = require('../config');
-              const libRegAddr = cfg.resolveAddress ? cfg.resolveAddress('LIBRARY_REGISTRY_ADDRESS', null) : (process.env.LIBRARY_REGISTRY_ADDRESS || null);
-              if (libRegAddr && out.timelock) {
-                const lib = new ethers.Contract(libRegAddr, [
-                  'function libraryAdminRole(address subdao) view returns (bytes32)',
-                  'function hasRole(bytes32,address) view returns (bool)'
-                ], provider);
-                const scopedRole = await lib.libraryAdminRole(subdao);
-                out.libraryRegistryAddress = libRegAddr;
-                out.libraryAdminRole = scopedRole;
-                out.libraryTimelockHasRole = await lib.hasRole(scopedRole, out.timelock).catch(()=>false);
-                out.libraryGovernorHasRole = await lib.hasRole(scopedRole, out.governor).catch(()=>false);
-              }
-            } catch(_) {}
-
-            const promptsAddr = opts.prompts || process.env.PREMIUM_PROMPTS_ADDRESS;
-            if (promptsAddr) {
-              try {
-                const pr = new ethers.Contract(ethers.getAddress(promptsAddr), ['function factory() view returns (address)'], provider);
-                const factory = await pr.factory(); out.prompts = promptsAddr; out.factory = factory;
-                if (factory && /^0x/.test(factory)) {
-                  const f = new ethers.Contract(factory, ['function isSubDAO(address) view returns (bool)'], provider);
-                  out.factoryRecognizesSubDAO = await f.isSubDAO(subdao).catch(()=>false);
-                }
-              } catch(_){}
-            }
-            if (opts.json) { console.log(JSON.stringify(out, null, 2)); return; }
-            console.log('┌─ SubDAO Doctor ────────────────────────────┐');
-            console.log(`│ SubDAO   : ${subdao}`);
-            console.log(`│ Governor : ${governor}`);
-            console.log(`│ Timelock : ${timelock}`);
-            // Effective mode label (treat non-proposer as Team-only UX)
-            if (out.mode !== undefined) {
-              let label = (out.mode===0?'Personal':'Community');
-              if (out.govIsProposer === false) label = 'Team-only';
-              console.log(`│ Mode     : ${out.mode} (${label})`);
-            }
-            if (out.minDelay !== undefined) console.log(`│ MinDelay : ${out.minDelay}s`);
-            if (out.govIsProposer !== undefined) console.log(`│ Gov PROPOSER on TL: ${out.govIsProposer?'yes':'no'}`);
-            if (out.registry) console.log(`│ Registry : ${out.registry}`);
-            if (out.registryAdminHandoverComplete !== undefined) {
-              console.log(`│ Registry handover : ${out.registryAdminHandoverComplete ? 'complete' : 'NOT COMPLETE'}`);
-            }
-            if (out.libraryRegistryAddress) {
-              console.log(`│ LibraryRegistry   : ${out.libraryRegistryAddress}`);
-              console.log(`│  TL has LIB_ADMIN : ${out.libraryTimelockHasRole ? 'yes' : 'no'}`);
-              console.log(`│  GOV has LIB_ADMIN: ${out.libraryGovernorHasRole ? 'yes' : 'no'}`);
-            }
-            if (out.prompts) console.log(`│ Premiums : ${out.prompts}`);
-            if (out.factory) console.log(`│ Factory  : ${out.factory}`);
-            if (out.factoryRecognizesSubDAO !== undefined) console.log(`│ Factory isSubDAO(SubDAO): ${out.factoryRecognizesSubDAO?'yes':'no'}`);
-            console.log('└────────────────────────────────────────────┘');
-            console.log('\nRecommendations:');
-            if (!out.govIsProposer) {
-              console.log('- Grant PROPOSER_ROLE to the Governor on the SubDAO Timelock.');
-              if (process.env.SAGE_SHOW_CAST === '1') {
-                console.log('  Encode calldata:');
-                console.log(`  cast calldata "grantRole(bytes32,address)" $(cast call ${timelock} "PROPOSER_ROLE()") ${governor}`);
-              }
-              console.log('  Schedule on timelock:');
-              console.log(`  sage timelock schedule-call --subdao ${subdao} --to ${timelock} --sig 'grantRole(bytes32,address)' --args "$(cast call ${timelock} 'PROPOSER_ROLE()'),${governor}"`);
-              console.log('  Or run one-shot helper:');
-              console.log(`  sage governance enable-proposals --subdao ${subdao}`);
-            }
-            if (out.registry && out.registryAdminHandoverComplete === false) {
-              console.log('- Complete PromptRegistry admin handover to the Timelock to avoid deployer EOAs retaining control.');
-            }
-            if (out.libraryRegistryAddress && !out.libraryTimelockHasRole) {
-              console.log('- Grant the scoped library admin role to the Timelock in LibraryRegistry for this SubDAO.');
-            }
-            console.log('- Prefer encoded helpers to avoid hex mistakes:');
-            console.log('  - Build data:   sage timelock build-data --sig "grantRole(bytes32,address)" --args "PROPOSER_ROLE,', governor, '"');
-            console.log('  - Execute call: sage timelock execute-call --subdao', subdao, '--to', timelock, '--sig "grantRole(bytes32,address)" --args "PROPOSER_ROLE,', governor, '" --salt 0x...');
-            if (out.factoryRecognizesSubDAO === false) {
-              console.log('- PremiumPrompts factory does not recognize this SubDAO. Use a factory-created SubDAO for premium registration or extend the factory with an allowlist and redeploy.');
+            
+            const report = await diagnoseSubDAO({ subdao: opts.subdao, provider, signer });
+            
+            if (opts.json) {
+                console.log(JSON.stringify(report, null, 2));
+                return;
             }
-            if (opts.fix) {
-              if (!out.signerIsAdmin) {
-                console.log('❌ Cannot fix: signer lacks DEFAULT_ADMIN_ROLE on Timelock');
-              } else {
-                const tlw = new ethers.Contract(timelock, ['function PROPOSER_ROLE() view returns (bytes32)','function EXECUTOR_ROLE() view returns (bytes32)','function grantRole(bytes32,address)','function hasRole(bytes32,address) view returns (bool)'], signer);
-                const PROPOSER = await tlw.PROPOSER_ROLE();
-                const EXECUTOR = await tlw.EXECUTOR_ROLE();
-                if (!out.govIsProposer) {
-                  console.log('⚙️  Granting PROPOSER_ROLE to Governor...');
-                  const tx = await tlw.grantRole(PROPOSER, governor); console.log('Tx:', tx.hash); { const { waitForReceipt } = require('../utils/tx-wait'); const { ethers } = require('ethers'); const pr = new ethers.JsonRpcProvider(process.env.RPC_URL || process.env.BASE_SEPOLIA_RPC || process.env.BASE_RPC_URL || 'https://base-sepolia.publicnode.com'); await waitForReceipt(pr, tx, Number(process.env.SAGE_TX_WAIT_MS || 60000)); } console.log('✅ Granted');
-                } else { console.log('✅ Governor already has PROPOSER_ROLE'); }
-                if (!out.anyoneExec) {
-                  console.log('⚙️  Granting EXECUTOR_ROLE to address(0)...');
-                  const tx2 = await tlw.grantRole(EXECUTOR, ethers.ZeroAddress); console.log('Tx:', tx2.hash); { const { waitForReceipt } = require('../utils/tx-wait'); const { ethers } = require('ethers'); const pr = new ethers.JsonRpcProvider(process.env.RPC_URL || process.env.BASE_SEPOLIA_RPC || process.env.BASE_RPC_URL || 'https://base-sepolia.publicnode.com'); await waitForReceipt(pr, tx2, Number(process.env.SAGE_TX_WAIT_MS || 60000)); } console.log('✅ Granted');
-                } else { console.log('✅ address(0) already EXECUTOR'); }
-              }
+            
+            console.log('🔍 Governance Doctor Report');
+            console.log(`SubDAO: ${report.subdao}`);
+            console.log(`Mode: ${report.mode === 1 ? 'Community' : 'Personal/Team'}`);
+            console.log(`Governor: ${report.governor}`);
+            console.log(`Timelock: ${report.timelock}`);
+            
+            if (report.recommendations.length === 0) {
+                console.log('✅ All checks passed.');
+            } else {
+                console.log('⚠️  Issues Found:');
+                report.recommendations.forEach(rec => {
+                    console.log(` - ${rec.msg}`);
+                    if (rec.fixCmd) console.log(`   Fix Cmd: ${rec.fixCmd}`);
+                });
+                
+                if (opts.fix) {
+                   console.log('\n⚠️  Automatic --fix is deprecated. Please use the commands above.');
+                   console.log('   Or for Safe/Tally payloads, rely on "sage skills publish" or "sage timelock" tools.');
+                }
             }
           } catch (e) {
             console.error('❌ Doctor failed:', e.message);

package/dist/cli/config/playbooks.json

@@ -0,0 +1,62 @@
+[
+  {
+    "id": "creator",
+    "name": "Creator Playbook (Solo)",
+    "version": "1.0.0",
+    "description": "For publishing your own work. Direct control.",
+    "governance": "operator",
+    "params": {
+      "proposalThreshold": "0",
+      "votingPeriod": "0",
+      "quorumBps": 0
+    },
+    "roles": {
+      "description": "Owner has all roles. No voting."
+    }
+  },
+  {
+    "id": "squad",
+    "name": "Squad Playbook (Small Team)",
+    "version": "1.0.0",
+    "description": "Collaborate with a small team via a Safe multisig.",
+    "governance": "operator",
+    "params": {
+      "proposalThreshold": "0",
+      "votingPeriod": "0",
+      "quorumBps": 0
+    },
+    "roles": {
+      "description": "Safe multisig holds Admin/Proposer roles."
+    }
+  },
+  {
+    "id": "community",
+    "name": "Community Playbook (Decentralized)",
+    "version": "1.0.0",
+    "description": "Token-based voting governance.",
+    "governance": "token",
+    "params": {
+      "proposalThreshold": "10000",
+      "votingPeriod": "3 days",
+      "quorumBps": 400
+    },
+    "roles": {
+      "description": "Token holders propose/vote. Timelock executes."
+    }
+  },
+  {
+    "id": "community-long",
+    "name": "Community Playbook (Long Voting)",
+    "version": "1.0.0",
+    "description": "Lower quorum (2%) with a longer voting window (7 days) for broader participation.",
+    "governance": "token",
+    "params": {
+      "proposalThreshold": "10000",
+      "votingPeriod": "7 days",
+      "quorumBps": 200
+    },
+    "roles": {
+      "description": "Token holders propose/vote. Timelock executes. Lower quorum, longer window."
+    }
+  }
+]

package/dist/cli/config.js

@@ -322,6 +322,10 @@ function createLocalConfig() {
           if (ipfs.warmGateway !== undefined && !process.env.SAGE_IPFS_WARM) {
             process.env.SAGE_IPFS_WARM = String(!!ipfs.warmGateway);
           }
+          const git = profile.git || {};
+          if (git.githubToken && !process.env.GITHUB_TOKEN && !process.env.GH_TOKEN) {
+            process.env.GITHUB_TOKEN = git.githubToken;
+          }
         }
         if (!isQuiet()) console.log(`🧭 Loaded config profile: ${active}`);
       } catch (e) {
@@ -410,6 +414,17 @@ function createLocalConfig() {
       this.writeProfileSettings({ ipfs: settings }, options);
     },
 
+    readGitConfig() {
+      const profiles = this.readProfiles();
+      const active = profiles.activeProfile || 'default';
+      const profile = profiles.profiles?.[active] || {};
+      return mergeObjects({}, profile.git || {});
+    },
+
+    writeGitConfig(settings = {}, options = {}) {
+      this.writeProfileSettings({ git: settings }, options);
+    },
+
     getActiveProfile(options = {}) {
       const profiles = this.readProfiles();
       const profileName = options.profile || profiles.activeProfile || 'default';

package/dist/cli/governance-manager.js

@@ -1283,9 +1283,14 @@ class GovernanceManager {
         }
     }
  
-    async executeProposal(id) {
+    async executeProposal(id, opts = {}) {
         try {
-            console.log(colors.blue('⚡ Executing proposal...'));
+            const { simulate } = opts;
+            if (simulate) {
+                console.log(colors.blue('🔮 Simulating proposal execution...'));
+            } else {
+                console.log(colors.blue('⚡ Executing proposal...'));
+            }
             console.log('Proposal ID:', id);
             
             // Convert proposalId to BigInt for consistency
@@ -1309,9 +1314,9 @@ class GovernanceManager {
                 throw new Error(`Governor contract at ${governorAddr} is not deployed or has no code. This may be a network/fork issue.`);
             }
 
-            // Optional wait until ETA is reached
+            // Optional wait until ETA is reached (only if not simulating)
             try {
-                if (process.env.SAGE_EXEC_WAIT === '1') {
+                if (!simulate && process.env.SAGE_EXEC_WAIT === '1') {
                     const eta = await this.governor.proposalEta(this.normalizeProposalId(proposalId)).catch(() => 0n);
                     if (eta && eta > 0n) {
                         const now = BigInt(Math.floor(Date.now() / 1000));
@@ -1361,6 +1366,21 @@ class GovernanceManager {
                             if (eta && eta > 0n) console.log(`🔍 Debug: ETA=${eta.toString()}`);
                             console.log(`🔍 Debug: Proposal state: ${nm} (${st})`);
                         } catch {}
+                        
+                        if (simulate) {
+                            // Simulation via call
+                            try {
+                                await this.governor.execute.staticCall(targets, values, calldatas, descriptionHash);
+                                console.log('✅ Simulation successful: Proposal would execute without reverting.');
+                                return;
+                            } catch (err) {
+                                const { decodeContractError } = require('./utils/contract-error-decoder');
+                                const reason = decodeContractError(err, [this.governor, this.timelock]);
+                                console.error('❌ Simulation failed:', reason);
+                                throw new Error(`Simulation failed: ${reason}`);
+                            }
+                        }
+
                         try {
                             const tx = await this.governor.execute(targets, values, calldatas, descriptionHash);
                             console.log('⏳ Waiting for transaction confirmation...');
@@ -1393,6 +1413,7 @@ class GovernanceManager {
                     }
                 }
             } catch (e) {
+                if (simulate && e.message.includes('Simulation failed')) throw e;
                 console.log('⚠️  Cache fast-path failed, falling back to log query:', e.message);
             }
             

package/dist/cli/index.js

@@ -42,7 +42,7 @@ try {
   };
   const getArg = (name) => {
     const i = process.argv.indexOf(name);
-    return i >= 0 && process.argv[i+1] && !process.argv[i+1].startsWith('-') ? process.argv[i+1] : null;
+    return i >= 0 && process.argv[i + 1] && !process.argv[i + 1].startsWith('-') ? process.argv[i + 1] : null;
   };
   const netArg = getArg('--net') || process.env.SAGE_NET || null;
   if (netArg) {
@@ -86,10 +86,10 @@ program
 
 // Reordered to highlight consolidated namespaces ('prompts' and 'gov')
 const commandGroups = [
-  { title: 'Content (new)', modules: ['prompts', 'prompt', 'library', 'premium', 'premium-pre', 'creator', 'contributor', 'bounty'] },
+  { title: 'Content (new)', modules: ['skills', 'prompts', 'prompt', 'library', 'premium', 'premium-pre', 'creator', 'contributor', 'bounty'] },
   { title: 'Governance (new)', modules: ['proposals', 'governance', 'subdao', 'timelock', 'roles', 'members', 'gov-config', 'stake-status'] },
   { title: 'Treasury', modules: ['treasury', 'safe', 'boost'] },
-  { title: 'Ops & Utilities', modules: ['config', 'wallet', 'sxxx', 'ipfs', 'ipns', 'context', 'doctor', 'factory', 'upgrade', 'resolve', 'dry-run-queue', 'mcp', 'start', 'wizard', 'init', 'subdao-config', 'pin', 'council', 'sbt', 'completion', 'help', 'hook', 'ipns'] },
+  { title: 'Ops & Utilities', modules: ['config', 'wallet', 'sxxx', 'ipfs', 'ipns', 'context', 'doctor', 'factory', 'upgrade', 'resolve', 'dry-run-queue', 'mcp', 'start', 'wizard', 'init', 'subdao-config', 'pin', 'council', 'sbt', 'completion', 'help', 'hook'] },
   { title: 'Developer', modules: ['dev', 'registry'] }
 ];
 
@@ -116,7 +116,7 @@ program.addHelpText('beforeAll', () => {
     if (!hasProjectConfig && !hasWorkspace) {
       firstRun = '\nTip: first time here? Try:\n  - sage wizard\n  - or: sage ipfs setup && sage prompts init\n';
     }
-  } catch (_) {}
+  } catch (_) { }
   return `Top workflows: ${highlights}\n${lines}\n${note}${firstRun}\n`;
 });
 
@@ -148,7 +148,6 @@ const additionalModules = [
   'completion',
   'help',
   'hook'
-  , 'ipns'
 ];
 additionalModules.forEach((mod) => moduleSet.add(mod));
 
@@ -168,7 +167,7 @@ if (cliTestMode) {
 
 program.configureOutput({
   writeOut: (str) => process.stdout.write(str),
-  writeErr: () => {},
+  writeErr: () => { },
   outputError: (str, write) => {
     if (!aliasSupport.handleOutputError(str)) {
       write(str);
@@ -202,7 +201,7 @@ process.on('exit', () => {
   process.stderr.write = originalStderrWrite;
   aliasSupport.setStderrWriter(originalStderrWrite);
   if (global.walletManager) {
-    global.walletManager.disconnect().catch(() => {});
+    global.walletManager.disconnect().catch(() => { });
   }
 });
 

package/dist/cli/library-manager.js

@@ -79,6 +79,85 @@ class LibraryManager {
 		return searchLocalManifests({ config: cliConfig, query });
 	}
 
+	/**
+	 * Create a new local library manifest in the pinned libraries directory.
+	 * This is used by MCP quick-start flows for "My Library" and ad-hoc libraries.
+	 * Returns a pseudo-CID (local_*) that can be used with the local manifest loader.
+	 */
+	createLibrary(name, description = '', options = {}) {
+		const dir = this.ensureLibrariesDir();
+		const baseName = String(name || 'Library').trim() || 'Library';
+		const slugBase = baseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'library';
+		let cid = `local_${slugBase}`;
+		let suffix = 1;
+		// Ensure uniqueness within the libraries dir
+		while (fs.existsSync(path.join(dir, `${cid}.json`))) {
+			cid = `local_${slugBase}_${suffix++}`;
+		}
+
+		const manifest = {
+			version: 2,
+			library: {
+				name: baseName,
+				description: String(description || ''),
+				...(options.metadata || {}),
+			},
+			prompts: [],
+		};
+
+		const manifestPath = path.join(dir, `${cid}.json`);
+		fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+		return { cid, path: manifestPath, manifest };
+	}
+
+	/**
+	 * Pin (or re-pin) a manifest into the local libraries directory.
+	 * Accepts either a manifest object or { manifestPath, manifestData } from callers.
+	 * Returns { cid, path } where cid may be provided or auto-assigned as local_*.
+	 */
+	pinLibrary(manifestOrOptions) {
+		const dir = this.ensureLibrariesDir();
+		let manifest = manifestOrOptions;
+
+		// Support callers that pass { manifestPath, manifestData }
+		if (manifestOrOptions && typeof manifestOrOptions === 'object' && (manifestOrOptions.manifest || manifestOrOptions.manifestData)) {
+			manifest = manifestOrOptions.manifest || manifestOrOptions.manifestData;
+		}
+
+		if (!manifest || typeof manifest !== 'object') {
+			throw new Error('pinLibrary requires a manifest object');
+		}
+
+		const libName = String(manifest.library?.name || 'Library').trim() || 'Library';
+		const slugBase = libName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'library';
+
+		let cid = manifest.cid || manifest.library?.cid || null;
+		if (!cid) {
+			cid = `local_${slugBase}`;
+			let suffix = 1;
+			while (fs.existsSync(path.join(dir, `${cid}.json`))) {
+				cid = `local_${slugBase}_${suffix++}`;
+			}
+		}
+
+		// Ensure manifest has expected top-level fields
+		if (!manifest.version) {
+			manifest.version = 2;
+		}
+		if (!manifest.library) {
+			manifest.library = { name: libName };
+		}
+		if (!Array.isArray(manifest.prompts)) {
+			manifest.prompts = [];
+		}
+
+		const manifestPath = path.join(dir, `${cid}.json`);
+		fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+		return { cid, path: manifestPath };
+	}
+
 	// Compute CID locally from bytes using ipfs-only-hash (UnixFS DAG-PB, CIDv0 by default)
 	// Compute CID locally from bytes using ipfs-only-hash (UnixFS DAG-PB, CIDv0 by default)
 	async _computeCidFromBuffer(buffer) {