cli-five 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-five",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Code Like I'm Five — scaffold a 5-agent VS Code Copilot team into any repo.",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -24,6 +24,7 @@ ${kleur.bold('Flags')}
   --force         Overwrite without confirmation. Dangerous. Use with --yes.
   --dry-run       Print actions without writing files
   --no-skills     Skip the skills.sh discovery step
+  --doc <file>    Read project docs to pre-fill interview (repeatable)
   --cost-mode <m> Override cost mode (premium, cheap, mixed) — skips interview question
   --cwd <path>    Run against a directory other than the current one
   --version, -v   Print version and exit
@@ -59,13 +60,14 @@ export async function run(argv) {
 }
 
 function parse(argv) {
-  const out = { _: [], yes: false, force: false, dryRun: false, skills: true, costMode: null, cwd: process.cwd() };
+  const out = { _: [], yes: false, force: false, dryRun: false, skills: true, docs: [], costMode: null, cwd: process.cwd() };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--yes' || a === '-y') out.yes = true;
     else if (a === '--force') out.force = true;
     else if (a === '--dry-run') out.dryRun = true;
     else if (a === '--no-skills') out.skills = false;
+    else if (a === '--doc') out.docs.push(argv[++i]);
     else if (a === '--cost-mode') out.costMode = argv[++i];
     else if (a === '--cwd') out.cwd = argv[++i];
     else if (a === '--help' || a === '-h') out._.push('help');

package/src/commands/init.mjs

@@ -1,5 +1,7 @@
 import kleur from 'kleur';
 import prompts from 'prompts';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
 import { log } from '../util/log.mjs';
 import { detect } from '../steps/detect.mjs';
 import { confirmOverwriteIfNeeded } from '../steps/confirm.mjs';
@@ -40,9 +42,51 @@ export async function init(args) {
   }
   if (!detected.hasAgents && !detected.hasCopilotInstructions) log.dim('No collisions.');
 
-  // 4. Interview
-  log.step('3/6 Interview');
-  const answers = await interview(detected, args);
+  // 4. Input mode — docs or manual interview
+  log.step('3/6 Project info');
+  let docHints;
+
+  if (args.docs.length > 0) {
+    // --doc was passed on the CLI — use those files directly
+    docHints = loadDocs(args.docs, cwd);
+  } else if (args.yes) {
+    // --yes skips the choice — go straight to defaults
+    docHints = loadDocs([], cwd);
+  } else {
+    const { mode } = await prompts({
+      type: 'select',
+      name: 'mode',
+      message: 'How would you like to describe your project?',
+      choices: [
+        { title: 'Provide document(s)', value: 'docs', description: 'Feed existing files (README, PRD, etc.) — we extract what we can' },
+        { title: 'Answer questions', value: 'manual', description: 'Short interactive interview' },
+      ],
+      initial: 0,
+    });
+    if (mode === undefined) { log.warn('Cancelled.'); return; }
+
+    if (mode === 'docs') {
+      const { paths } = await prompts({
+        type: 'list',
+        name: 'paths',
+        message: 'File paths (comma-separated, relative to project root)',
+        separator: ',',
+      });
+      if (!paths || paths.length === 0) { log.warn('No files provided. Falling back to interview.'); }
+      docHints = loadDocs((paths || []).map(p => p.trim()).filter(Boolean), cwd);
+    } else {
+      docHints = loadDocs([], cwd);
+    }
+  }
+
+  if (docHints.files.length > 0) {
+    log.info(`Loaded ${docHints.files.length} doc${docHints.files.length > 1 ? 's' : ''}: ${docHints.files.join(', ')}`);
+    if (docHints.projectName) log.dim(`  → project name: ${docHints.projectName}`);
+    if (docHints.oneLiner) log.dim(`  → description: ${docHints.oneLiner}`);
+  }
+
+  // 5. Interview (pre-filled from docs if available, otherwise manual)
+  const answers = await interview(detected, args, docHints);
 
   // CLI --cost-mode override
   if (args.costMode && ['premium', 'cheap', 'mixed'].includes(args.costMode)) {
@@ -106,3 +150,101 @@ function printNextSteps(answers) {
   log.raw(kleur.dim('Edit cost mode anytime by changing `model:` in .github/agents/*.agent.md.'));
   log.raw('');
 }
+
+// ── --doc file loading + extraction ───────────────────────────────────
+
+function loadDocs(docPaths, cwd) {
+  const empty = { files: [], projectName: '', oneLiner: '', goals: '', constraints: '', raw: '' };
+  if (!docPaths || docPaths.length === 0) return empty;
+
+  const sections = [];
+  const files = [];
+  let projectName = '';
+  let oneLiner = '';
+  let goals = '';
+  let constraints = '';
+
+  for (const rawPath of docPaths) {
+    const abs = resolve(cwd, rawPath);
+    if (!existsSync(abs)) {
+      log.warn(`--doc: file not found: ${rawPath}`);
+      continue;
+    }
+
+    let content;
+    try {
+      content = readFileSync(abs, 'utf8');
+    } catch (err) {
+      log.warn(`--doc: cannot read ${rawPath}: ${err.message}`);
+      continue;
+    }
+
+    const name = basename(abs);
+    files.push(name);
+    sections.push(`### ${name}\n\n${content.trim()}`);
+
+    // ── Heuristic extraction ──────────────────────────────────────
+    // Try package.json first (structured data)
+    if (name === 'package.json') {
+      try {
+        const pkg = JSON.parse(content);
+        if (pkg.name && !projectName) projectName = pkg.name;
+        if (pkg.description && !oneLiner) oneLiner = pkg.description;
+      } catch { /* ignore malformed JSON */ }
+      continue;
+    }
+
+    // For markdown/text files — extract from headings and first paragraph
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+
+      // First H1 → project name hint
+      if (!projectName && /^#\s+/.test(line)) {
+        projectName = line.replace(/^#+\s*/, '').trim();
+        continue;
+      }
+
+      // First non-empty paragraph after H1 → one-liner hint
+      if (projectName && !oneLiner && line && !line.startsWith('#') && !line.startsWith('```') && !line.startsWith('- ') && !line.startsWith('|')) {
+        oneLiner = line.length > 120 ? line.slice(0, 117) + '...' : line;
+        continue;
+      }
+
+      // ## Goal / ## Purpose / ## Overview → goals hint
+      if (!goals && /^##\s+(goal|purpose|overview|objective|vision)/i.test(line)) {
+        const body = collectSection(lines, i + 1);
+        if (body) goals = body;
+        continue;
+      }
+
+      // ## Constraints → constraints hint
+      if (!constraints && /^##\s+(constraint|requirement|limit|scope)/i.test(line)) {
+        const body = collectSection(lines, i + 1);
+        if (body) constraints = body;
+        continue;
+      }
+    }
+  }
+
+  return {
+    files,
+    projectName,
+    oneLiner,
+    goals,
+    constraints,
+    raw: sections.join('\n\n---\n\n'),
+  };
+}
+
+/** Collect text from startIdx until the next heading or EOF. */
+function collectSection(lines, startIdx) {
+  const out = [];
+  for (let i = startIdx; i < lines.length; i++) {
+    if (/^##?\s+/.test(lines[i]) && out.length > 0) break;
+    const trimmed = lines[i].trim();
+    if (trimmed) out.push(trimmed);
+    if (out.length >= 3) break; // Keep it short — just the first few lines
+  }
+  return out.join(' ');
+}

package/src/steps/interview.mjs

@@ -6,6 +6,14 @@ import prompts from 'prompts';
 // Research via Context7: Next.js, Vite+React, Express, Hono all score
 // 80+ benchmark with high snippet counts and well-indexed docs.
 const STACK_PRESETS = [
+  {
+    title: 'Next.js + Supabase PWA (TypeScript)',
+    value: 'nextjs-supabase',
+    description: 'Next.js 15 static export, React 19, Tailwind v4, Supabase, SWR, Vercel hosting, PWA.',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Next.js', 'React', 'Tailwind CSS', 'Supabase', 'SWR'],
+    quickstart: 'npx create-next-app@latest . --yes && npm i @supabase/supabase-js swr date-fns clsx && npm run dev',
+  },
   {
     title: 'Next.js (TypeScript)',
     value: 'nextjs',
@@ -70,8 +78,8 @@ const COST_MODES = [
   { title: 'Mixed', value: 'mixed', description: 'Premium Coder + Reviewer, cheap everything else.' },
 ];
 
-export async function interview(detected, args) {
-  if (args.yes) return defaults(detected);
+export async function interview(detected, args, docHints = {}) {
+  if (args.yes) return defaults(detected, docHints);
 
   const onCancel = () => {
     throw new Error('Interview cancelled. Nothing was written.');
@@ -84,13 +92,13 @@ export async function interview(detected, args) {
         type: 'text',
         name: 'projectName',
         message: 'Project name',
-        initial: detected.projectName,
+        initial: docHints.projectName || detected.projectName,
       },
       {
         type: 'text',
         name: 'oneLiner',
         message: 'One-line description (becomes PROJECT.md vision)',
-        initial: '',
+        initial: docHints.oneLiner || '',
       },
     ],
     { onCancel },
@@ -151,11 +159,13 @@ export async function interview(detected, args) {
         type: 'text',
         name: 'goals',
         message: 'Primary goal of this project (one sentence)',
+        initial: docHints.goals || '',
       },
       {
         type: 'text',
         name: 'constraints',
         message: 'Hard constraints (perf, deps, deploy, compliance — one sentence, optional)',
+        initial: docHints.constraints || '',
       },
       {
         type: 'select',
@@ -175,30 +185,32 @@ export async function interview(detected, args) {
   );
 
   return normalize({
-    ...defaults(detected),
+    ...defaults(detected, docHints),
     ...basic,
     ...stackAnswers,
     ...rest,
     presetId: preset,
     quickstart: chosenPreset?.quickstart || '',
+    docs: docHints.raw || '',
   });
 }
 
 /** Default stack is Next.js + TypeScript when nothing detected and --yes. */
-function defaults(detected) {
+function defaults(detected, docHints = {}) {
   const hasDetected = detected.stacks.length > 0;
   const fallback = STACK_PRESETS[0]; // Next.js (TypeScript)
   return {
-    projectName: detected.projectName,
-    oneLiner: '',
+    projectName: docHints.projectName || detected.projectName,
+    oneLiner: docHints.oneLiner || '',
     stack: hasDetected ? detected.stacks.map((s) => s.label) : fallback.stack,
     frameworks: hasDetected ? [] : fallback.frameworks,
-    goals: '',
-    constraints: '',
+    goals: docHints.goals || '',
+    constraints: docHints.constraints || '',
     costMode: 'premium',
     snark: true,
     presetId: hasDetected ? 'custom' : fallback.value,
     quickstart: hasDetected ? '' : fallback.quickstart,
+    docs: docHints.raw || '',
   };
 }
 

package/src/steps/scaffold.mjs

@@ -96,6 +96,13 @@ function buildVars(a) {
     CONSTRAINTS: a.constraints || 'None declared.',
     QUICKSTART: a.quickstart || 'TODO — add install + run commands here.',
     COST_MODE: a.costMode,
+    DOCS_SECTION: a.docs ? `
+## Source Documents
+
+The following documents were provided via \`--doc\` at project init time.
+
+${a.docs}
+` : '',
     DATE: new Date().toISOString().slice(0, 10),
     PERSONA_BLOCK: a.snark ? PERSONA_BLOCK : '',
   };

package/src/steps/skills.mjs

@@ -6,36 +6,9 @@ import { join, dirname } from 'node:path';
 import { createRequire } from 'node:module';
 import { log } from '../util/log.mjs';
 
-// ── Awesome-copilot catalog (github/awesome-copilot) ──────────────────
-// Curated subset mapped by stack term → { name, description, type }
-const AWESOME_CATALOG = [
-  // Universal
-  { terms: ['*'], name: 'frontend-design', desc: 'Production-grade UI design', type: 'skill', source: 'awesome-copilot' },
-  { terms: ['*'], name: 'conventional-commit', desc: 'Commit message standards', type: 'skill', source: 'awesome-copilot' },
-  { terms: ['*'], name: 'documentation-writer', desc: 'Generate project docs', type: 'skill', source: 'awesome-copilot' },
-  { terms: ['*'], name: 'mermaid-diagrams', desc: 'Create software diagrams', type: 'skill', source: 'awesome-copilot' },
-  // JavaScript / TypeScript / React / Next
-  { terms: ['node', 'typescript', 'javascript'], name: 'typescript', desc: 'TypeScript best practices', type: 'instruction', source: 'awesome-copilot' },
-  { terms: ['react', 'next'], name: 'reactjs', desc: 'React patterns & conventions', type: 'instruction', source: 'awesome-copilot' },
-  { terms: ['next'], name: 'nextjs', desc: 'Next.js patterns', type: 'instruction', source: 'awesome-copilot' },
-  { terms: ['node', 'typescript', 'react', 'next'], name: 'playwright-tester', desc: 'E2E testing with Playwright', type: 'skill', source: 'awesome-copilot' },
-  // Python
-  { terms: ['python', 'django', 'flask', 'fastapi'], name: 'python', desc: 'Python best practices', type: 'instruction', source: 'awesome-copilot' },
-  { terms: ['django'], name: 'django', desc: 'Django conventions', type: 'instruction', source: 'awesome-copilot' },
-  { terms: ['fastapi'], name: 'fastapi', desc: 'FastAPI patterns', type: 'instruction', source: 'awesome-copilot' },
-  // .NET
-  { terms: ['dotnet', '.net', 'csharp', 'c#'], name: 'dotnet', desc: '.NET conventions', type: 'instruction', source: 'awesome-copilot' },
-  // Rust
-  { terms: ['rust'], name: 'rust', desc: 'Rust best practices', type: 'instruction', source: 'awesome-copilot' },
-  // Go
-  { terms: ['go', 'golang'], name: 'go', desc: 'Go conventions', type: 'instruction', source: 'awesome-copilot' },
-  // Mobile
-  { terms: ['swift', 'ios'], name: 'swift', desc: 'Swift/iOS patterns', type: 'instruction', source: 'awesome-copilot' },
-  { terms: ['kotlin', 'android'], name: 'kotlin', desc: 'Kotlin/Android patterns', type: 'instruction', source: 'awesome-copilot' },
-  // DevOps / Infra
-  { terms: ['docker', 'kubernetes', 'devops'], name: 'docker', desc: 'Docker best practices', type: 'instruction', source: 'awesome-copilot' },
-  { terms: ['terraform'], name: 'terraform', desc: 'Terraform conventions', type: 'instruction', source: 'awesome-copilot' },
-];
+// ── Known-good skill repos (verified working) ────────────────────────
+// awesome-copilot skills are discovered dynamically via `skills find`.
+const AWESOME_COPILOT_REPO = 'github/awesome-copilot';
 
 // Well-known skill repos matched by stack term → repo + suggested skill names (skills.sh)
 const SKILL_CATALOG = [
@@ -141,8 +114,7 @@ export async function skillDiscovery({ cwd, answers, args }) {
   if (!env) {
     log.warn('Cannot run skills CLI: no bundled binary, pnpm, or npx found.');
     log.warn('Install Node.js (includes npx) or pnpm, then re-run.');
-    // Still show awesome-copilot recs (they don't need skills CLI)
-    await showAwesomeCopilotOnly(answers);
+    printBreadcrumbs();
     return;
   }
 
@@ -165,77 +137,86 @@ export async function skillDiscovery({ cwd, answers, args }) {
   }
 
   log.ok(`Running skills via ${env.label}`);
-  log.raw('');
-
-  // ── Build recommendations from BOTH sources ─────────────────────────
-  const awesomeRecs = buildAwesomeRecommendations(answers);
-  const skillsShRecs = buildRecommendations(answers);
-
-  // ── Display hero section ────────────────────────────────────────────
-  displayHeroRecommendations(awesomeRecs, skillsShRecs, answers);
 
-  // ── Combined picker ─────────────────────────────────────────────────
+  // ── 1. Auto-search all stack terms silently ─────────────────────────
   const terms = suggestSearches(answers);
+  const searchResults = [];
 
-  // Search skills.sh for additional results
-  const allFound = [];
   if (terms.length > 0) {
-    log.dim(`Suggested searches: ${terms.map((t) => `"${t}"`).join(', ')}`);
     log.raw('');
-
+    log.info(`Searching skills.sh for: ${terms.map((t) => kleur.bold(t)).join(', ')} ...`);
     for (const term of terms) {
-      const { go } = await prompts({
-        type: 'confirm',
-        name: 'go',
-        message: `Search skills.sh for "${term}"?`,
-        initial: true,
-      });
-      if (go) {
-        const output = await runSkillsCapture(env, ['find', term], cwd);
-        allFound.push(...parseSkillRefs(output));
-      }
+      const output = await runSkillsSilent(env, ['find', term], cwd);
+      searchResults.push(...parseSkillRefs(output));
+    }
+    if (searchResults.length > 0) {
+      log.ok(`Found ${searchResults.length} skill${searchResults.length > 1 ? 's' : ''} from search.`);
+    } else {
+      log.dim('No additional skills found via search.');
     }
   }
 
-  // Build combined skill picker — awesome recs + catalog recs + search results
+  // ── 2. Build static catalog recommendations ─────────────────────────
+  const catalogRecs = buildRecommendations(answers);
+
+  // ── 3. Categorize search results by source ──────────────────────────
+  const awesomeResults = [];
+  const otherResults = [];
+  for (const r of searchResults) {
+    const parsed = parseRef(r.ref);
+    if (parsed && parsed.repo === AWESOME_COPILOT_REPO) {
+      awesomeResults.push({ ...r, ...parsed });
+    } else {
+      otherResults.push(r);
+    }
+  }
+
+  // ── 4. Display hero section ─────────────────────────────────────────
+  displayHeroRecommendations(awesomeResults, catalogRecs, answers);
+
+  // ── 5. Build unified picker ─────────────────────────────────────────
   const seen = new Set();
   const choices = [];
 
-  // Awesome-copilot recs first (hero placement)
-  for (const r of awesomeRecs) {
-    const key = `awesome:${r.name}`;
+  // awesome-copilot results from search (dynamic, real names)
+  for (const r of awesomeResults) {
+    const key = r.ref;
     if (seen.has(key)) continue;
     seen.add(key);
     choices.push({
-      title: `${kleur.cyan('⬡')} ${r.name} ${kleur.dim(`(${r.desc})`)} ${kleur.cyan('← awesome-copilot')}`,
-      value: { source: 'awesome', name: r.name, type: r.type },
+      title: `${kleur.cyan('⬡')} ${r.skill} ${kleur.dim(`(${r.installs})`)} ${kleur.cyan('← awesome-copilot')}`,
+      value: { source: 'awesome', repo: r.repo, skill: r.skill, ref: r.ref },
       selected: true,
     });
   }
 
-  // skills.sh catalog recs
-  for (const r of skillsShRecs) {
+  // Static catalog recs (verified repos)
+  for (const r of catalogRecs) {
     const ref = `${r.repo}@${r.skill}`;
     if (seen.has(ref)) continue;
     seen.add(ref);
     choices.push({
       title: `${kleur.yellow('◆')} ${r.skill} ${kleur.dim(`(${r.repo})`)} ${kleur.yellow('← skills.sh')}`,
-      value: { source: 'skillssh', ref, repo: r.repo, skill: r.skill },
+      value: { source: 'catalog', ref, repo: r.repo, skill: r.skill },
       selected: true,
     });
   }
 
-  // skills.sh search results
-  for (const r of allFound) {
+  // Other search results (non-awesome-copilot)
+  for (const r of otherResults) {
     if (seen.has(r.ref)) continue;
     seen.add(r.ref);
+    const parsed = parseRef(r.ref);
     choices.push({
-      title: `${kleur.yellow('◆')} ${r.ref} ${kleur.dim(`— ${r.installs}`)} ${kleur.yellow('← skills.sh')}`,
-      value: { source: 'skillssh', ref: r.ref },
+      title: `${kleur.yellow('◆')} ${parsed ? parsed.skill : r.ref} ${kleur.dim(`(${parsed ? parsed.repo : ''} — ${r.installs})`)} ${kleur.yellow('← skills.sh')}`,
+      value: { source: 'search', ref: r.ref, repo: parsed?.repo, skill: parsed?.skill },
       selected: false,
     });
   }
 
+  // ── 6. Prompt user to select skills ─────────────────────────────────
+  const installResults = [];
+
   if (choices.length > 0) {
     log.raw('');
     const { toInstall } = await prompts({
@@ -247,51 +228,47 @@ export async function skillDiscovery({ cwd, answers, args }) {
     });
 
     if (toInstall && toInstall.length > 0) {
-      // Separate awesome-copilot entries from skills.sh entries
-      const awesomeItems = toInstall.filter((i) => i.source === 'awesome');
-      const skillsShItems = toInstall.filter((i) => i.source === 'skillssh');
-
-      // Install awesome-copilot skills/instructions via npx skills (they're in the registry too)
-      if (awesomeItems.length > 0) {
-        log.raw('');
-        log.info(`${kleur.cyan('awesome-copilot')} resources selected: ${awesomeItems.map((i) => i.name).join(', ')}`);
-        log.dim('These will be installed via skills CLI from the awesome-copilot registry.');
-        for (const item of awesomeItems) {
-          log.info(`Installing ${item.name} (${item.type})...`);
-          await runSkills(env, ['add', `awesome-copilot@${item.name}`, '-a', 'github-copilot'], cwd);
+      log.raw('');
+
+      // Group by repo for batch install
+      const byRepo = new Map();
+      const standalone = [];
+
+      for (const item of toInstall) {
+        if (item.repo && item.skill) {
+          if (!byRepo.has(item.repo)) byRepo.set(item.repo, []);
+          byRepo.get(item.repo).push(item.skill);
+        } else if (item.ref) {
+          standalone.push(item.ref);
         }
       }
 
-      // Install skills.sh entries
-      if (skillsShItems.length > 0) {
-        const byRepo = new Map();
-        const standalone = [];
-
-        for (const item of skillsShItems) {
-          if (item.repo) {
-            if (!byRepo.has(item.repo)) byRepo.set(item.repo, []);
-            byRepo.get(item.repo).push(item.skill);
-          } else {
-            standalone.push(item.ref);
-          }
-        }
-
-        for (const [repo, skills] of byRepo) {
-          const skillArgs = skills.flatMap((s) => ['--skill', s]);
-          log.info(`Installing from ${repo}: ${skills.join(', ')}`);
-          await runSkills(env, ['add', repo, ...skillArgs, '-a', 'github-copilot'], cwd);
+      // Batch install per repo
+      for (const [repo, skills] of byRepo) {
+        const skillArgs = skills.flatMap((s) => ['--skill', s]);
+        log.info(`Installing from ${kleur.bold(repo)}: ${skills.join(', ')}`);
+        const result = await runSkillsTracked(env, ['add', repo, ...skillArgs, '-a', 'github-copilot'], cwd);
+        for (const s of skills) {
+          installResults.push({ name: `${repo}@${s}`, ...result });
         }
+      }
 
-        for (const ref of standalone) {
-          log.info(`Installing ${ref}...`);
-          await runSkills(env, ['add', ref, '-a', 'github-copilot'], cwd);
-        }
+      // Standalone refs
+      for (const ref of standalone) {
+        log.info(`Installing ${ref}...`);
+        const result = await runSkillsTracked(env, ['add', ref, '-a', 'github-copilot'], cwd);
+        installResults.push({ name: ref, ...result });
       }
 
       await relocateSkills(cwd);
     }
   }
 
+  // ── 7. Install summary ──────────────────────────────────────────────
+  if (installResults.length > 0) {
+    printInstallSummary(installResults);
+  }
+
   // Offer freeform catch-all
   const { freeform } = await prompts({
     type: 'confirm',
@@ -310,7 +287,7 @@ export async function skillDiscovery({ cwd, answers, args }) {
 
 // ── Hero display ──────────────────────────────────────────────────────
 
-function displayHeroRecommendations(awesomeRecs, skillsShRecs, answers) {
+function displayHeroRecommendations(awesomeResults, catalogRecs, answers) {
   const stackLabel = [...(answers.stack || []), ...(answers.frameworks || [])].join(', ') || 'general';
 
   log.raw('');
@@ -318,42 +295,50 @@ function displayHeroRecommendations(awesomeRecs, skillsShRecs, answers) {
   log.raw(kleur.bold().cyan('  ║') + kleur.bold('  📦 RECOMMENDED FOR YOUR STACK: ') + kleur.bold().white(stackLabel) + pad('', Math.max(0, 30 - stackLabel.length)) + kleur.bold().cyan(' ║'));
   log.raw(kleur.bold().cyan('  ╚══════════════════════════════════════════════════════════════════╝'));
 
-  if (awesomeRecs.length > 0) {
+  if (awesomeResults.length > 0) {
     log.raw('');
     log.raw(kleur.cyan('  ⬡ Source: awesome-copilot') + kleur.dim('  (github/awesome-copilot · 30k+ ★)'));
     log.raw(kleur.dim('  ─────────────────────────────────────────────────────────'));
-    for (const r of awesomeRecs) {
-      const typeTag = kleur.dim(`[${r.type}]`);
-      log.raw(`    ${kleur.green('✓')} ${pad(r.name, 28)} ${pad(r.desc, 32)} ${typeTag}`);
+    for (const r of awesomeResults) {
+      log.raw(`    ${kleur.green('✓')} ${pad(r.skill, 38)} ${kleur.dim(r.installs)}`);
     }
   }
 
-  if (skillsShRecs.length > 0) {
+  if (catalogRecs.length > 0) {
     log.raw('');
-    log.raw(kleur.yellow('  ◆ Source: skills.sh') + kleur.dim('  (skills.sh registry)'));
+    log.raw(kleur.yellow('  ◆ Source: skills.sh') + kleur.dim('  (verified repos)'));
     log.raw(kleur.dim('  ─────────────────────────────────────────────────────────'));
-    for (const r of skillsShRecs) {
-      log.raw(`    ${kleur.green('✓')} ${pad(r.skill, 28)} ${kleur.dim(r.repo)}`);
+    for (const r of catalogRecs) {
+      log.raw(`    ${kleur.green('✓')} ${pad(r.skill, 38)} ${kleur.dim(r.repo)}`);
     }
   }
 
   log.raw('');
 }
 
-/** Fallback when skills CLI is unavailable — show awesome-copilot recs as copy-paste commands */
-async function showAwesomeCopilotOnly(answers) {
-  const recs = buildAwesomeRecommendations(answers);
-  if (recs.length === 0) return;
+// ── Install summary ───────────────────────────────────────────────────
+
+function printInstallSummary(results) {
+  const succeeded = results.filter((r) => r.ok);
+  const failed = results.filter((r) => !r.ok);
 
   log.raw('');
-  log.info('Cannot install skills automatically, but here are recommendations:');
-  displayHeroRecommendations(recs, [], answers);
-  log.raw(kleur.dim('  Install manually in VS Code Chat:'));
-  for (const r of recs) {
-    log.raw(`    ${kleur.white(`copilot plugin install awesome-copilot@${r.name}`)}`);
+  if (succeeded.length > 0) {
+    log.ok(`Installed ${succeeded.length} skill${succeeded.length > 1 ? 's' : ''} successfully.`);
+  }
+
+  if (failed.length > 0) {
+    log.raw('');
+    log.warn(`${failed.length} skill${failed.length > 1 ? 's' : ''} failed to install:`);
+    for (const f of failed) {
+      log.raw(`    ${kleur.red('✗')} ${f.name}`);
+      if (f.reason) {
+        log.raw(`      ${kleur.dim(f.reason)}`);
+      }
+    }
+    log.raw('');
+    log.dim('Install failed skills manually: npx skills add <owner/repo> --skill <name>');
   }
-  log.raw('');
-  printBreadcrumbs();
 }
 
 // ── Post-install breadcrumbs ──────────────────────────────────────────
@@ -364,9 +349,6 @@ function printBreadcrumbs() {
   log.raw(kleur.bold().green('  │') + kleur.bold('  🎯 KEEP DISCOVERING — paste into VS Code / Copilot Chat:       ') + kleur.bold().green('│'));
   log.raw(kleur.bold().green('  ├──────────────────────────────────────────────────────────────────┤'));
   log.raw(kleur.bold().green('  │') + '                                                                  ' + kleur.bold().green('│'));
-  log.raw(kleur.bold().green('  │') + '  Install the awesome-copilot suggestion skill:                   ' + kleur.bold().green('│'));
-  log.raw(kleur.bold().green('  │') + kleur.white('    copilot plugin install awesome-copilot@suggest              ') + kleur.bold().green('│'));
-  log.raw(kleur.bold().green('  │') + '                                                                  ' + kleur.bold().green('│'));
   log.raw(kleur.bold().green('  │') + '  Add awesome-copilot MCP for ongoing search:                     ' + kleur.bold().green('│'));
   log.raw(kleur.bold().green('  │') + kleur.white('    Add to .vscode/mcp.json:                                   ') + kleur.bold().green('│'));
   log.raw(kleur.bold().green('  │') + kleur.dim('      "awesome-copilot": {                                     ') + kleur.bold().green('│'));
@@ -381,26 +363,61 @@ function printBreadcrumbs() {
   log.raw('');
 }
 
-// ── Awesome-copilot recommendation builder ────────────────────────────
+// ── Runner ─────────────────────────────────────────────────────────────
 
-function buildAwesomeRecommendations(a) {
-  const stackLower = (a.stack || []).map((s) => s.toLowerCase());
-  const fwLower = (a.frameworks || []).map((f) => f.toLowerCase());
-  const all = [...stackLower, ...fwLower];
-  const seen = new Set();
-  const out = [];
+/** Run skills CLI with stdio: inherit (visible to user). */
+function runSkills(env, skillsArgs, cwd) {
+  const { cmd, args } = env.runner(skillsArgs);
+  return runInteractive(cmd, args, cwd);
+}
 
-  for (const entry of AWESOME_CATALOG) {
-    const matches = entry.terms.includes('*') || entry.terms.some((t) => all.some((s) => s.includes(t)));
-    if (!matches) continue;
-    if (seen.has(entry.name)) continue;
-    seen.add(entry.name);
-    out.push({ name: entry.name, desc: entry.desc, type: entry.type, source: entry.source });
-  }
-  return out;
+/** Run skills CLI, capture output, track success/failure. Returns { ok, reason }. */
+function runSkillsTracked(env, skillsArgs, cwd) {
+  const { cmd, args } = env.runner(skillsArgs);
+  return new Promise((resolve) => {
+    let output = '';
+    const proc = spawn(cmd, args, { cwd, stdio: ['inherit', 'pipe', 'pipe'] });
+    proc.stdout.on('data', (chunk) => {
+      const text = chunk.toString();
+      process.stdout.write(text);
+      output += text;
+    });
+    proc.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      process.stderr.write(text);
+      output += text;
+    });
+    proc.on('exit', (code) => {
+      const clean = stripAnsi(output);
+      if (code !== 0 || /failed to clone|installation failed|canceled/i.test(clean)) {
+        const reason = extractFailureReason(clean);
+        resolve({ ok: false, reason });
+      } else {
+        resolve({ ok: true, reason: null });
+      }
+    });
+    proc.on('error', (err) => {
+      resolve({ ok: false, reason: err.message });
+    });
+  });
 }
 
-// ── Relocation ─────────────────────────────────────────────────────────
+/** Run skills CLI silently — capture stdout/stderr without echoing. */
+function runSkillsSilent(env, skillsArgs, cwd) {
+  const { cmd, args } = env.runner(skillsArgs);
+  return new Promise((resolve) => {
+    let output = '';
+    const proc = spawn(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    proc.stdout.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    proc.stderr.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    proc.on('exit', () => resolve(output));
+    proc.on('error', () => resolve(''));
+  });
+}
 
 async function relocateSkills(cwd) {
   const src = join(cwd, '.agents', 'skills');
@@ -458,12 +475,7 @@ async function relocateSkills(cwd) {
   }
 }
 
-// ── Runner ─────────────────────────────────────────────────────────────
-
-function runSkills(env, skillsArgs, cwd) {
-  const { cmd, args } = env.runner(skillsArgs);
-  return runInteractive(cmd, args, cwd);
-}
+// ── Helpers ────────────────────────────────────────────────────────────
 
 function buildRecommendations(a) {
   const stackLower = (a.stack || []).map((s) => s.toLowerCase());
@@ -503,6 +515,24 @@ function suggestSearches(a) {
   return [...out];
 }
 
+/** Parse owner/repo@skill ref into { repo, skill }. */
+function parseRef(ref) {
+  const match = /^(.+?\/.+?)@(.+)$/.exec(ref);
+  if (!match) return null;
+  return { repo: match[1], skill: match[2] };
+}
+
+/** Extract a concise failure reason from skills CLI output. */
+function extractFailureReason(output) {
+  const cloneMatch = /Failed to clone[^:]*:\s*(.+)/i.exec(output);
+  if (cloneMatch) return cloneMatch[1].trim();
+
+  const errorMatch = /(?:error|failed)[:\s]+(.+)/im.exec(output);
+  if (errorMatch) return errorMatch[1].trim();
+
+  return 'Unknown error (check output above)';
+}
+
 function pad(s, n) {
   return (s || '').padEnd(n);
 }
@@ -519,30 +549,6 @@ function runInteractive(cmd, args, cwd) {
   });
 }
 
-/** Run skills CLI, capture stdout/stderr while echoing to the terminal. */
-function runSkillsCapture(env, skillsArgs, cwd) {
-  const { cmd, args } = env.runner(skillsArgs);
-  return new Promise((resolve) => {
-    let output = '';
-    const proc = spawn(cmd, args, { cwd, stdio: ['inherit', 'pipe', 'pipe'] });
-    proc.stdout.on('data', (chunk) => {
-      const text = chunk.toString();
-      process.stdout.write(text);
-      output += text;
-    });
-    proc.stderr.on('data', (chunk) => {
-      const text = chunk.toString();
-      process.stderr.write(text);
-      output += text;
-    });
-    proc.on('exit', () => resolve(output));
-    proc.on('error', (err) => {
-      log.warn(`Could not launch \`${cmd} ${args.join(' ')}\`: ${err.message}`);
-      resolve('');
-    });
-  });
-}
-
 function stripAnsi(str) {
   // eslint-disable-next-line no-control-regex
   return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');

package/templates/PROJECT.md.tmpl

@@ -27,6 +27,6 @@ _(populate as you discover things this project will NOT do)_
 _(populate with measurable outcomes — what does "done" look like?)_
 
 ---
-
+{{DOCS_SECTION}}
 _This file is the durable vision. It changes rarely. Day-to-day status lives in `STATE.md`._
 _Generated by `npx cli-five` on {{DATE}}._