@sage-protocol/cli 0.2.9 → 0.3.0

package/dist/cli/commands/subdao.js

@@ -208,6 +208,54 @@ 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')
+        .description('Create a new SubDAO using a governance playbook (Plan/Apply)')
+        .option('--playbook <id>', 'Playbook ID (creator, squad, community)')
+        .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('--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;
+            }
+
+            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 +604,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,47 @@
+[
+  {
+    "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."
+    }
+  }
+]

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/index.js

@@ -86,7 +86,7 @@ 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'] },

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

@@ -727,89 +727,23 @@ class SageMCPServer {
    * - Skill files live under promptsDir/skills/*.md
    */
   listWorkspaceSkills() {
-    const skills = [];
     try {
       const { readWorkspace, DEFAULT_DIR } = require('./services/prompts/workspace');
+      const { findWorkspaceSkills } = require('./services/skills/discovery');
       const ws = readWorkspace() || {};
       const promptsDir = ws.promptsDir || DEFAULT_DIR || 'prompts';
-      const baseDir = path.join(process.cwd(), promptsDir, 'skills');
-      if (!fs.existsSync(baseDir)) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: 'No workspace skills directory found (expected prompts/skills). Create prompts/skills/<name>.md to define skills for this repo.',
-            },
-          ],
-        };
-      }
-      const walk = (dir) => {
-        const entries = fs.readdirSync(dir, { withFileTypes: true });
-        for (const entry of entries) {
-          const full = path.join(dir, entry.name);
-          if (entry.isDirectory()) {
-            walk(full);
-          } else if (entry.isFile() && full.toLowerCase().endsWith('.md')) {
-            skills.push(full);
-          }
-        }
-      };
-      walk(baseDir);
-      const results = skills.map((filePath) => {
-        const relFromPrompts = path.relative(path.join(process.cwd(), promptsDir), filePath);
-        const key = relFromPrompts.replace(/\\/g, '/').replace(/\.md$/i, '');
-        let title = path.basename(filePath, '.md');
-        let summary = '';
-        let tags = [];
-        try {
-          const raw = fs.readFileSync(filePath, 'utf8');
-          if (raw.startsWith('---')) {
-            const end = raw.indexOf('\n---', 3);
-            if (end !== -1) {
-              const front = raw.slice(3, end).split(/\r?\n/);
-              for (const line of front) {
-                const idx = line.indexOf(':');
-                if (idx === -1) continue;
-                const k = line.slice(0, idx).trim().toLowerCase();
-                let v = line.slice(idx + 1).trim();
-                if (k === 'title' && v) title = v;
-                if (k === 'summary' && v) summary = v;
-                if (k === 'tags' && v) {
-                  try {
-                    tags = JSON.parse(v.replace(/'/g, '"'));
-                  } catch (_) {
-                    tags = String(v)
-                      .split(/[,|\s]+/)
-                      .filter(Boolean);
-                  }
-                }
-              }
-            }
-          }
-        } catch (_) {
-          // ignore parse errors; fall back to filename
-        }
-        return {
-          key,
-          name: title,
-          summary,
-          tags,
-          path: filePath,
-        };
-      });
-
+      const results = findWorkspaceSkills({ promptsDir });
       if (!results.length) {
         return {
           content: [
             {
               type: 'text',
-              text: 'No skills found under prompts/skills. Create prompts/skills/<name>.md to define repo-specific skills.',
+              text: 'No skills found. Create prompts/skills/<name>.md or prompts/skills/<name>/SKILL.md to define skills for this repo.',
             },
             { type: 'json', text: JSON.stringify({ skills: [] }, null, 2) },
           ],
         };
       }
-
       const textLines = results
         .map(
           (s, idx) =>
@@ -818,7 +752,6 @@ class SageMCPServer {
             }${s.tags && s.tags.length ? `\n   🔖 ${s.tags.join(', ')}` : ''}`,
         )
         .join('\n\n');
-
       return {
         content: [
           { type: 'text', text: `Workspace skills (${results.length})\n\n${textLines}` },
@@ -839,42 +772,38 @@ class SageMCPServer {
   getWorkspaceSkill({ key }) {
     try {
       if (!key || !String(key).trim()) {
-        return {
-          content: [{ type: 'text', text: 'get_workspace_skill: key is required' }],
-        };
+        return { content: [{ type: 'text', text: 'get_workspace_skill: key is required' }] };
       }
       const { readWorkspace, DEFAULT_DIR } = require('./services/prompts/workspace');
+      const { resolveSkillFileByKey } = require('./services/skills/discovery');
       const ws = readWorkspace() || {};
       const promptsDir = ws.promptsDir || DEFAULT_DIR || 'prompts';
       const safeKey = String(key).trim().replace(/^\/+/, '').replace(/\.md$/i, '');
-      const filePath = path.join(process.cwd(), promptsDir, `${safeKey}.md`);
-      if (!fs.existsSync(filePath)) {
+      const resolved = resolveSkillFileByKey({ promptsDir, key: safeKey });
+      if (!resolved || !fs.existsSync(resolved.path)) {
+        const expectedFlat = path.join(process.cwd(), promptsDir, `${safeKey}.md`);
+        const expectedDir = path.join(process.cwd(), promptsDir, safeKey, 'SKILL.md');
         return {
           content: [
             {
               type: 'text',
-              text: `Workspace skill not found for key '${safeKey}'. Expected file at ${path.relative(
-                process.cwd(),
-                filePath,
-              )}`,
+              text: `Workspace skill not found for key '${safeKey}'. Expected at ${path.relative(process.cwd(), expectedFlat)} or ${path.relative(process.cwd(), expectedDir)}`,
             },
           ],
         };
       }
-      const body = fs.readFileSync(filePath, 'utf8');
+      const body = fs.readFileSync(resolved.path, 'utf8');
       return {
         content: [
           {
             type: 'text',
-            text: `Loaded workspace skill '${safeKey}' from ${path.relative(process.cwd(), filePath)}.\n\n${body}`,
+            text: `Loaded workspace skill '${safeKey}' from ${path.relative(process.cwd(), resolved.path)}.\n\n${body}`,
           },
-          { type: 'json', text: JSON.stringify({ key: safeKey, path: filePath, body }, null, 2) },
+          { type: 'json', text: JSON.stringify({ key: safeKey, path: resolved.path, baseDir: resolved.baseDir, body }, null, 2) },
         ],
       };
     } catch (error) {
-      return {
-        content: [{ type: 'text', text: `Error loading workspace skill: ${error.message}` }],
-      };
+      return { content: [{ type: 'text', text: `Error loading workspace skill: ${error.message}` }] };
     }
   }
 

package/dist/cli/services/governance/doctor.js

@@ -0,0 +1,140 @@
+const { ethers } = require('ethers');
+const { resolveGovContext } = require('../../utils/gov-context');
+
+/**
+ * Comprehensive Governance Diagnosis
+ * @param {object} opts - { subdao, provider, signer }
+ * @returns {object} Report with recommendations and structured fix payloads
+ */
+async function diagnoseSubDAO({ subdao, provider, signer }) {
+  const out = {
+    subdao,
+    governor: null,
+    timelock: null,
+    mode: null,
+    checks: {},
+    recommendations: [], // { type, msg, fixCmd, fixPayload }
+  };
+
+  // 1. Resolve Context
+  try {
+    const ctx = await resolveGovContext({ subdaoOpt: subdao, govOpt: undefined, provider });
+    out.governor = ctx.governor;
+    out.timelock = ctx.timelock;
+    out.checks.context = 'ok';
+  } catch (e) {
+    out.checks.context = 'failed';
+    out.checks.contextError = e.message;
+    return out;
+  }
+
+  if (!out.governor || !out.timelock) {
+    out.recommendations.push({ msg: 'Could not resolve Governor or Timelock. Verify SubDAO address.' });
+    return out;
+  }
+
+  // 2. Detect Mode
+  try {
+    const SubABI = ['function getGovernanceMode() view returns (uint8)', 'function promptRegistry() view returns (address)'];
+    const sd = new ethers.Contract(subdao, SubABI, provider);
+    const mode = await sd.getGovernanceMode();
+    out.mode = Number(mode); // 0=Operator/Personal, 1=Community
+    out.registry = await sd.promptRegistry();
+  } catch (e) {
+    out.checks.mode = 'failed';
+  }
+
+  // 3. Roles Check (Timelock)
+  try {
+    const tl = new ethers.Contract(out.timelock, [
+      'function PROPOSER_ROLE() view returns (bytes32)',
+      'function EXECUTOR_ROLE() view returns (bytes32)',
+      'function hasRole(bytes32,address) view returns (bool)',
+      'function grantRole(bytes32,address)'
+    ], provider);
+
+    const PROPOSER = await tl.PROPOSER_ROLE();
+    const EXECUTOR = await tl.EXECUTOR_ROLE();
+
+    out.govIsProposer = await tl.hasRole(PROPOSER, out.governor);
+    out.anyoneExec = await tl.hasRole(EXECUTOR, ethers.ZeroAddress);
+
+    if (!out.govIsProposer) {
+        const iface = tl.interface;
+        const calldata = iface.encodeFunctionData('grantRole', [PROPOSER, out.governor]);
+        out.recommendations.push({
+            type: 'role_missing',
+            msg: 'Governor lacks PROPOSER_ROLE on Timelock.',
+            fixCmd: `sage timelock execute-call --subdao ${subdao} --to ${out.timelock} --sig "grantRole(bytes32,address)" --args "${PROPOSER},${out.governor}"`,
+            fixPayload: { to: out.timelock, data: calldata, description: 'Grant PROPOSER to Governor' }
+        });
+    }
+    if (!out.anyoneExec) {
+        const iface = tl.interface;
+        const calldata = iface.encodeFunctionData('grantRole', [EXECUTOR, ethers.ZeroAddress]);
+        out.recommendations.push({
+            type: 'role_missing',
+            msg: 'Timelock execution is restricted (executor != address(0)).',
+            fixCmd: `sage timelock execute-call --subdao ${subdao} --to ${out.timelock} --sig "grantRole(bytes32,address)" --args "${EXECUTOR},${ethers.ZeroAddress}"`,
+            fixPayload: { to: out.timelock, data: calldata, description: 'Open Execution (Grant EXECUTOR to 0x0)' }
+        });
+    }
+  } catch (e) {
+      out.checks.roles = 'failed';
+  }
+
+  // 4. PromptRegistry Governance
+  if (out.registry && out.registry !== ethers.ZeroAddress) {
+      try {
+          const reg = new ethers.Contract(out.registry, [
+              'function GOVERNANCE_ROLE() view returns (bytes32)',
+              'function hasRole(bytes32,address) view returns (bool)',
+              'function grantRole(bytes32,address)'
+          ], provider);
+          const GOV_ROLE = await reg.GOVERNANCE_ROLE().catch(() => null);
+          if (GOV_ROLE) {
+              const has = await reg.hasRole(GOV_ROLE, subdao).catch(() => false);
+              if (!has) {
+                  const calldata = reg.interface.encodeFunctionData('grantRole', [GOV_ROLE, subdao]);
+                  out.recommendations.push({
+                      type: 'registry_role',
+                      msg: 'SubDAO missing GOVERNANCE_ROLE on PromptRegistry.',
+                      fixCmd: `sage timelock execute-call --subdao ${subdao} --to ${out.registry} --sig "grantRole(bytes32,address)" --args "${GOV_ROLE},${subdao}"`,
+                      fixPayload: { to: out.registry, data: calldata, description: 'Grant GOVERNANCE_ROLE to SubDAO' }
+                  });
+              }
+          }
+      } catch (e) {
+          out.checks.registry = 'failed';
+      }
+  }
+
+  // 5. LibraryRegistry (Scoped)
+  const libRegAddr = process.env.LIBRARY_REGISTRY_ADDRESS;
+  if (libRegAddr && out.timelock) {
+      try {
+          const lib = new ethers.Contract(libRegAddr, [
+              'function libraryAdminRole(address subdao) view returns (bytes32)',
+              'function hasRole(bytes32,address) view returns (bool)',
+              'function grantRole(bytes32,address)'
+          ], provider);
+          const scopedRole = await lib.libraryAdminRole(subdao);
+          const has = await lib.hasRole(scopedRole, out.timelock).catch(()=>false);
+          if (!has) {
+              const calldata = lib.interface.encodeFunctionData('grantRole', [scopedRole, out.timelock]);
+              out.recommendations.push({
+                  type: 'library_role',
+                  msg: 'Timelock missing LIBRARY_ADMIN_ROLE (scoped) on LibraryRegistry.',
+                  fixCmd: `sage safe propose --safe <TREASURY> --to ${libRegAddr} --data ${calldata} --operation 0`,
+                  fixPayload: { to: libRegAddr, data: calldata, description: 'Grant Scoped LIBRARY_ADMIN to Timelock' }
+              });
+          }
+      } catch (e) {
+          out.checks.library = 'failed';
+      }
+  }
+
+  return out;
+}
+
+module.exports = { diagnoseSubDAO };