capman 0.4.1 → 0.4.3

package/bin/lib/cmd-demo.js

@@ -0,0 +1,180 @@
+'use strict'
+
+const { header, c, requireSrc } = require('./shared')
+
+module.exports = function cmdDemo() {
+  header()
+  const { generate, match } = requireSrc()
+
+  console.log(`${c.bold}  Turn natural language into reliable, explainable backend actions.${c.reset}`)
+  console.log(`${c.gray}  ─────────────────────────────────────────${c.reset}\n`)
+
+  const config = {
+    app: 'demo-store',
+    baseUrl: 'https://api.demo-store.com',
+    capabilities: [
+      {
+        id: 'check_product_availability',
+        name: 'Check product availability',
+        description: 'Check stock and pricing for a product by name or ID.',
+        examples: [
+          'Is the blue jacket in stock?',
+          'Check stock for blue jacket',
+          'Check availability for blue jacket',
+          'Product availability for jacket',
+        ],
+        params: [
+          { name: 'product', description: 'Product name or ID', required: true, source: 'user_query' },
+        ],
+        returns: ['stock', 'price', 'variants'],
+        resolver: { type: 'api', endpoints: [{ method: 'GET', path: '/products/{product}/availability' }] },
+        privacy: { level: 'public' },
+      },
+      {
+        id: 'get_order_status',
+        name: 'Get order status',
+        description: 'Retrieve the current status and tracking info for an order by order ID.',
+        examples: [
+          'Where is my order?',
+          'Track order 1234',
+          'What is the status of my purchase?',
+        ],
+        params: [
+          { name: 'order_id', description: 'Order ID', required: true, source: 'user_query' },
+        ],
+        returns: ['status', 'tracking', 'estimated_delivery'],
+        resolver: { type: 'api', endpoints: [{ method: 'GET', path: '/orders/{order_id}' }] },
+        privacy: { level: 'user_owned' },
+      },
+      {
+        id: 'navigate_to_screen',
+        name: 'Navigate to screen',
+        description: 'Route the user to a specific page in the store.',
+        examples: [
+          'Take me to cart',
+          'Open cart',
+          'Go to checkout',
+          'Navigate to account',
+        ],
+        params: [
+          { name: 'destination', description: 'Target screen', required: true, source: 'user_query' },
+        ],
+        returns: ['deep_link'],
+        resolver: { type: 'nav', destination: '/{destination}' },
+        privacy: { level: 'public' },
+      },
+    ],
+  }
+
+  const manifest = generate(config)
+
+  console.log(`${c.gray}  app:${c.reset}          ${c.bold}${config.app}${c.reset}`)
+  console.log(`${c.gray}  capabilities:${c.reset} ${manifest.capabilities.length}`)
+  console.log(`${c.gray}  matcher:${c.reset}      keyword (no LLM, no API key needed)\n`)
+
+  const queries = [
+    { text: 'Check availability for blue jacket', expectMatch: true  },
+    { text: 'Track order 1234',                   expectMatch: true  },
+    { text: 'Go to cart',                         expectMatch: true  },
+    { text: 'Is the website down?',               expectMatch: false },
+  ]
+
+  let passed    = 0
+  let outOfScope = 0
+
+  for (const q of queries) {
+    const t0     = Date.now()
+    const result = match(q.text, manifest)
+    const ms     = Date.now() - t0
+
+    console.log(`${c.gray}  ────────────────────────────────────────${c.reset}`)
+    console.log()
+    console.log(`  ${c.bold}QUERY${c.reset}`)
+    console.log(`  "${c.bold}${q.text}${c.reset}"\n`)
+
+    if (!result.capability) {
+      outOfScope++
+      console.log(`  ${c.bold}MATCH${c.reset}`)
+      console.log(`  ${c.yellow}○  OUT_OF_SCOPE${c.reset} — no capability handles this query\n`)
+      console.log(`  ${c.bold}EXECUTION${c.reset}`)
+      console.log(`  ${c.gray}[1] keyword_match  no match  ${ms}ms${c.reset}\n`)
+      console.log(`  ${c.bold}RESULT${c.reset}`)
+      console.log(`  ${c.yellow}No action taken — query is outside manifest scope${c.reset}\n`)
+      console.log(`  ${c.bold}EXPLANATION${c.reset}`)
+      if (result.candidates.length) {
+        const best = result.candidates.sort((a, b) => b.score - a.score)[0]
+        console.log(`  ${c.gray}Closest capability was "${best.capabilityId}" (${best.score}%) —`)
+        console.log(`  below the 50% confidence threshold. Correctly rejected.${c.reset}`)
+      }
+      console.log()
+      continue
+    }
+
+    passed++
+
+    let actionLine = ''
+    if (result.capability.resolver.type === 'api') {
+      const endpoint = result.capability.resolver.endpoints[0]
+      let p = endpoint.path
+      for (const [k, v] of Object.entries(result.extractedParams)) {
+        if (v) p = p.replace(`{${k}}`, String(v))
+      }
+      actionLine = `${endpoint.method} ${config.baseUrl}${p}`
+    } else if (result.capability.resolver.type === 'nav') {
+      let dest = result.capability.resolver.destination
+      for (const [k, v] of Object.entries(result.extractedParams)) {
+        if (v) dest = dest.replace(`{${k}}`, String(v))
+      }
+      actionLine = `navigate → ${dest}`
+    }
+
+    const sorted      = [...result.candidates].sort((a, b) => b.score - a.score)
+    const winner      = sorted[0]
+    const runners     = sorted.slice(1).filter(r => r.score > 0)
+    const paramEntries = Object.entries(result.extractedParams).filter(([, v]) => v !== null)
+
+    console.log(`  ${c.bold}MATCH${c.reset}`)
+    console.log(`  ${c.green}✓  ${result.capability.id}${c.reset}`)
+    console.log(`  ${c.gray}intent:     ${c.reset}${result.intent}`)
+    console.log(`  ${c.gray}confidence: ${c.reset}${c.bold}${result.confidence}%${c.reset}`)
+    console.log(`  ${c.gray}privacy:    ${c.reset}${result.capability.privacy.level}`)
+    if (paramEntries.length) {
+      console.log(`  ${c.gray}params:     ${c.reset}${paramEntries.map(([k, v]) => `${k}=${v}`).join(', ')}`)
+    }
+    console.log()
+
+    console.log(`  ${c.bold}EXECUTION${c.reset}`)
+    console.log(`  ${c.gray}[1] cache_check    miss    0ms${c.reset}`)
+    console.log(`  ${c.gray}[2]${c.reset} keyword_match  ${c.green}pass${c.reset}    ${ms}ms   confidence: ${result.confidence}%`)
+    console.log(`  ${c.gray}[3] privacy_check  pass    0ms   level: ${result.capability.privacy.level}${c.reset}`)
+    console.log(`  ${c.gray}[4] resolve        pass    ${ms}ms   via ${result.capability.resolver.type}${c.reset}`)
+    console.log()
+
+    console.log(`  ${c.bold}RESULT${c.reset}`)
+    console.log(`  ${c.green}${actionLine}${c.reset}`)
+    console.log()
+
+    console.log(`  ${c.bold}EXPLANATION${c.reset}`)
+    console.log(`  ${c.gray}Why "${winner.capabilityId}"?${c.reset}`)
+    console.log(`  ${c.gray}  scored ${winner.score}% — highest match against examples and description${c.reset}`)
+    if (runners.length) {
+      console.log(`  ${c.gray}  rejected: ${runners.map(r => `${r.capabilityId} (${r.score}%)`).join(', ')}${c.reset}`)
+    }
+    if (paramEntries.length) {
+      console.log(`  ${c.gray}  extracted from query: ${paramEntries.map(([k, v]) => `${k}="${v}"`).join(', ')}${c.reset}`)
+    }
+    console.log()
+  }
+
+  console.log(`${c.gray}  ────────────────────────────────────────${c.reset}\n`)
+  console.log(`  ${c.green}${passed} matched${c.reset}  ${c.gray}·${c.reset}  ${c.yellow}${outOfScope} out of scope${c.reset}  ${c.gray}·${c.reset}  ${manifest.capabilities.length} capabilities  ${c.gray}·${c.reset}  no LLM required\n`)
+  console.log(`  ${c.bold}Every query above is fully traced.${c.reset}`)
+  console.log(`  ${c.gray}You saw what matched, why it matched, how it executed, what it called,`)
+  console.log(`  and which alternatives were considered and rejected.${c.reset}`)
+  console.log(`  ${c.gray}No black box. No guessing. Full control.\n${c.reset}`)
+  console.log(`  ${c.gray}Next steps:${c.reset}`)
+  console.log(`  ${c.teal}npx capman init${c.reset}                          ${c.gray}→ define your app's capabilities${c.reset}`)
+  console.log(`  ${c.teal}npx capman generate${c.reset}                      ${c.gray}→ generate manifest.json${c.reset}`)
+  console.log(`  ${c.teal}npx capman run "your query" --debug${c.reset}      ${c.gray}→ trace any query live${c.reset}`)
+  console.log(`  ${c.teal}npm install capman${c.reset}                       ${c.gray}→ use in your AI agent${c.reset}\n`)
+}

package/bin/lib/cmd-explain.js

@@ -0,0 +1,72 @@
+'use strict'
+
+const { header, log, c, args, getFlag, requireSrc } = require('./shared')
+
+module.exports = async function cmdExplain() {
+  header()
+  const query = args[1]
+  const manifestPath = getFlag('--manifest') ?? 'manifest.json'
+
+  if (!query) {
+    log.error('Please provide a query.')
+    console.log(`  Example: npx capman explain "show me articles"\n`)
+    process.exit(1)
+  }
+
+  const { readManifest, CapmanEngine } = requireSrc()
+
+  let manifest
+  try {
+    manifest = readManifest(manifestPath)
+  } catch (e) {
+    log.error(e.message)
+    process.exit(1)
+  }
+
+  const engine = new CapmanEngine({ manifest, cache: false, learning: false, mode: 'cheap' })
+  const result = await engine.explain(query)
+
+  console.log(`\n  ${c.bold}QUERY${c.reset}`)
+  console.log(`  "${c.bold}${query}${c.reset}"\n`)
+
+  // ── Match ────────────────────────────────────────────────────────────────
+  console.log(`  ${c.bold}MATCH${c.reset}`)
+  if (result.matched.capability) {
+    console.log(`  ${c.green}✓  ${result.matched.capability.id}${c.reset}`)
+    console.log(`  ${c.gray}confidence:${c.reset} ${result.matched.confidence}%`)
+    console.log(`  ${c.gray}intent:${c.reset}     ${result.matched.intent}`)
+  } else {
+    console.log(`  ${c.yellow}○  OUT_OF_SCOPE${c.reset} — no capability matched\n`)
+  }
+  console.log()
+
+  // ── Reasoning ────────────────────────────────────────────────────────────
+  console.log(`  ${c.bold}REASONING${c.reset}`)
+  result.matched.reasoning.forEach(r => {
+    console.log(`  ${c.gray}•${c.reset} ${r}`)
+  })
+  console.log()
+
+  // ── All candidates ────────────────────────────────────────────────────────
+  console.log(`  ${c.bold}ALL CANDIDATES${c.reset}`)
+  result.candidates.forEach(cand => {
+    const marker     = cand.matched ? `${c.green}✓${c.reset}` : `${c.gray}○${c.reset}`
+    const scoreColor = cand.score >= 50 ? c.green : c.gray
+    console.log(`  ${marker}  ${cand.capabilityId}`)
+    console.log(`     ${scoreColor}${cand.score}%${c.reset}  ${c.gray}${cand.explanation}${c.reset}`)
+  })
+  console.log()
+
+  // ── Would execute ─────────────────────────────────────────────────────────
+  console.log(`  ${c.bold}WOULD EXECUTE${c.reset}`)
+  if (result.wouldExecute.blocked) {
+    console.log(`  ${c.yellow}✗  Blocked — ${result.wouldExecute.blocked}${c.reset}`)
+  } else if (result.wouldExecute.action) {
+    console.log(`  ${c.green}✓  ${result.wouldExecute.action}${c.reset}`)
+    console.log(`  ${c.gray}privacy: ${result.wouldExecute.privacy}${c.reset}`)
+  } else {
+    console.log(`  ${c.yellow}○  No action — query is out of scope${c.reset}`)
+  }
+  console.log()
+  console.log(`  ${c.gray}${result.durationMs}ms  ·  via ${result.resolvedVia}${c.reset}\n`)
+}

package/bin/lib/cmd-generate.js

@@ -0,0 +1,280 @@
+'use strict'
+
+const fs   = require('fs')
+const { header, log, c, flags, getFlag, requireSrc } = require('./shared')
+
+// ─── AI prompt builder ────────────────────────────────────────────────────────
+
+function buildAIPrompt(description) {
+  return `You are helping generate a capman capability manifest config.
+
+The user's app description:
+${JSON.stringify({ app_description: description })}
+
+Generate a valid capman config as a JSON object (not module.exports, just the raw JSON object).
+
+The config must follow this exact structure:
+{
+  "app": "app-name-in-kebab-case",
+  "baseUrl": "https://api.your-app.com",
+  "capabilities": [
+    {
+      "id": "snake_case_id",
+      "name": "Human readable name",
+      "description": "What this capability does (min 10 chars)",
+      "examples": ["Example query 1", "Example query 2", "Example query 3"],
+      "params": [
+        {
+          "name": "param_name",
+          "description": "What this param is",
+          "required": true,
+          "source": "user_query"
+        }
+      ],
+      "returns": ["resource_name"],
+      "resolver": {
+        "type": "api",
+        "endpoints": [{ "method": "GET", "path": "/resource/{param_name}" }]
+      },
+      "privacy": { "level": "public" }
+    }
+  ]
+}
+
+Rules:
+- privacy.level must be "public", "user_owned", or "admin"
+- resolver.type must be "api", "nav", or "hybrid"
+- method must be "GET", "POST", "PUT", "PATCH", or "DELETE"
+- source must be "user_query", "session", "context", or "static"
+- Generate 3-8 capabilities based on the description
+- Each capability needs at least 2 examples
+- Respond ONLY with the raw JSON object — no markdown, no explanation`
+}
+
+// ─── LLM caller ───────────────────────────────────────────────────────────────
+
+async function callLLM(provider, apiKey, prompt) {
+  if (provider === 'anthropic') {
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 4000,
+        messages: [{ role: 'user', content: prompt }],
+      }),
+    })
+    const data = await res.json()
+    if (!res.ok) throw new Error(data.error?.message ?? res.statusText)
+    return data.content[0].text
+  }
+
+  if (provider === 'openai') {
+    const res = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model: 'gpt-4o-mini',
+        max_tokens: 4000,
+        messages: [{ role: 'user', content: prompt }],
+      }),
+    })
+    const data = await res.json()
+    if (!res.ok) throw new Error(data.error?.message ?? res.statusText)
+    return data.choices[0].message.content
+  }
+
+  if (provider === 'openrouter') {
+    const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+        'HTTP-Referer': 'https://github.com/Hobbydefiningdoctory/capman',
+      },
+      body: JSON.stringify({
+        model: 'openai/gpt-oss-120b:free',
+        max_tokens: 4000,
+        messages: [{ role: 'user', content: prompt }],
+        provider: { order: ['open-inference'], allow_fallbacks: true },
+      }),
+    })
+    const data = await res.json()
+    if (!res.ok) throw new Error(data.error?.message ?? res.statusText)
+    return data.choices[0].message.content
+  }
+
+  throw new Error(`Unknown provider: ${provider}`)
+}
+
+// ─── Command ──────────────────────────────────────────────────────────────────
+
+module.exports = async function cmdGenerate() {
+  header()
+  const { generate, loadConfig, writeManifest, validate, parseOpenAPI } = requireSrc()
+
+  const fromFlag  = getFlag('--from')
+  const aiFlag    = flags.includes('--ai')
+  const outPath   = getFlag('--out') ?? 'manifest.json'
+  const configOut = getFlag('--config-out') ?? 'capman.config.js'
+
+  // ── Path 1: OpenAPI parser ───────────────────────────────────────────────
+  if (fromFlag) {
+    log.info(`Parsing OpenAPI spec: ${fromFlag}`)
+    let result
+    try {
+      result = await parseOpenAPI(fromFlag)
+    } catch (e) {
+      log.error(e.message)
+      process.exit(1)
+    }
+
+    const { config, stats } = result
+
+    log.success(`Parsed ${stats.total} capabilities from spec`)
+    if (stats.skipped > 0) log.info(`Skipped ${stats.skipped} operations (insufficient info)`)
+    if (stats.warnings.length) stats.warnings.forEach(w => log.warn(w))
+
+    const configContent = `// Auto-generated by capman from OpenAPI spec
+    // Review and adjust before committing
+
+    module.exports = ${JSON.stringify(config, null, 2)}
+    `
+    fs.writeFileSync(configOut, configContent)
+    log.success(`Config written to ${configOut}`)
+
+    try {
+      const manifest = generate(config)
+      writeManifest(manifest, outPath)
+      log.success(`Manifest written to ${outPath}`)
+      log.info(`${manifest.capabilities.length} capabilities registered`)
+    } catch (e) {
+      log.warn(`Could not generate manifest: ${e.message}`)
+    }
+
+    console.log()
+    console.log(`  ${c.gray}Next steps:${c.reset}`)
+    console.log(`  1. Review ${c.teal}${configOut}${c.reset} — adjust descriptions and examples`)
+    console.log(`  2. Run ${c.teal}npx capman validate${c.reset} to check your manifest`)
+    console.log(`  3. Run ${c.teal}npx capman demo${c.reset} to see it in action`)
+    console.log()
+    return
+  }
+
+  // ── Path 2: LLM-assisted ─────────────────────────────────────────────────
+  if (aiFlag) {
+    log.info('LLM-assisted manifest generation')
+    console.log()
+
+    const readline = require('readline')
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+    const ask = (q) => new Promise(resolve => rl.question(q, resolve))
+
+    console.log(`  ${c.gray}Describe your app and its main capabilities.${c.reset}`)
+    console.log(`  ${c.gray}Example: "A CRM app. Users can create contacts, log calls,`)
+    console.log(`  view pipeline stages. Admins can manage teams and billing."${c.reset}\n`)
+
+    const description = await ask(`  ${c.teal}>${c.reset} `)
+    rl.close()
+
+    if (!description.trim()) {
+      log.error('No description provided.')
+      process.exit(1)
+    }
+
+    const apiKey = process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? process.env.OPENROUTER_API_KEY
+    const provider =
+      process.env.ANTHROPIC_API_KEY  ? 'anthropic' :
+      process.env.OPENAI_API_KEY     ? 'openai' :
+      process.env.OPENROUTER_API_KEY ? 'openrouter' : null
+
+    if (!apiKey || !provider) {
+      log.error('No LLM API key found.')
+      console.log(`  Set one of: ${c.teal}ANTHROPIC_API_KEY${c.reset}, ${c.teal}OPENAI_API_KEY${c.reset}, or ${c.teal}OPENROUTER_API_KEY${c.reset}`)
+      process.exit(1)
+    }
+
+    log.info(`Using ${provider} to generate manifest...`)
+
+    let raw
+    try {
+      raw = await callLLM(provider, apiKey, buildAIPrompt(description))
+    } catch (e) {
+      log.error(`LLM call failed: ${e.message}`)
+      process.exit(1)
+    }
+
+    let config
+    try {
+      const clean = raw.replace(/```json|```javascript|```js|```/g, '').trim()
+      const match = clean.match(/module\.exports\s*=\s*(\{[\s\S]+\})/)
+      config = JSON.parse(match ? match[1] : clean)
+    } catch (e) {
+      log.error('Could not parse LLM response. Try again or use --from with an OpenAPI spec.')
+      console.log(`\n  Raw response:\n${raw.slice(0, 500)}`)
+      process.exit(1)
+    }
+
+    const configContent = `// Auto-generated by capman AI\n// Review before committing\n\nmodule.exports = ${JSON.stringify(config, null, 2)}\n`
+    fs.writeFileSync(configOut, configContent)
+    log.success(`Config written to ${configOut}`)
+
+    try {
+      const manifest = generate(config)
+      writeManifest(manifest, outPath)
+      log.success(`Manifest written to ${outPath}`)
+      log.info(`${manifest.capabilities.length} capabilities generated`)
+    } catch (e) {
+      log.warn(`Manifest generation failed — review your config: ${e.message}`)
+    }
+
+    console.log()
+    console.log(`  ${c.gray}Review ${configOut} — the AI may have missed things.${c.reset}`)
+    console.log(`  ${c.teal}npx capman validate${c.reset}   ${c.gray}→ check for errors${c.reset}`)
+    console.log(`  ${c.teal}npx capman inspect${c.reset}    ${c.gray}→ see all capabilities${c.reset}`)
+    console.log()
+    return
+  }
+
+  // ── Path 3: Manual ───────────────────────────────────────────────────────
+  const configPath = getFlag('--config')
+  log.info('Loading config...')
+  let config
+  try {
+    config = loadConfig(configPath)
+  } catch (e) {
+    log.error(e.message)
+    process.exit(1)
+  }
+
+  log.info(`Generating manifest for ${config.app}...`)
+
+  let manifest
+  try {
+    manifest = generate(config)
+  } catch (e) {
+    log.error(`Generation failed: ${e.message}`)
+    process.exit(1)
+  }
+
+  const validation = validate(manifest)
+  if (!validation.valid) {
+    validation.errors.forEach(e => log.error(e))
+    process.exit(1)
+  }
+  if (validation.warnings.length) {
+    validation.warnings.forEach(w => log.warn(w))
+  }
+
+  writeManifest(manifest, outPath)
+  log.success(`Manifest written to ${outPath}`)
+  log.info(`${manifest.capabilities.length} capabilities registered`)
+  console.log()
+}

package/bin/lib/cmd-help.js

@@ -0,0 +1,26 @@
+'use strict'
+
+const { header, c } = require('./shared')
+
+module.exports = function cmdHelp() {
+  header()
+  console.log(`${c.bold}  Usage:${c.reset}  capman <command>`)
+  console.log()
+  console.log(`${c.bold}  Commands:${c.reset}`)
+  console.log(`    ${c.teal}init${c.reset}                         Create a starter capman.config.js`)
+  console.log(`    ${c.teal}generate${c.reset}                     Generate manifest from capman.config.js`)
+  console.log(`    ${c.teal}generate --from <path|url>${c.reset}   Generate from OpenAPI/Swagger spec`)
+  console.log(`    ${c.teal}generate --ai${c.reset}                Generate manifest using AI`)
+  console.log(`    ${c.teal}validate${c.reset}                     Validate an existing manifest.json`)
+  console.log(`    ${c.teal}inspect${c.reset}                      Print all capabilities in manifest`)
+  console.log(`    ${c.teal}demo${c.reset}                         Run a live demo with sample queries`)
+  console.log(`    ${c.teal}run "query"${c.reset}                  Run a query against your manifest`)
+  console.log(`    ${c.teal}run "query" --debug${c.reset}          Run with full candidate scoring`)
+  console.log(`    ${c.teal}explain "query"${c.reset}              Explain what would match without executing`)
+  console.log()
+  console.log(`${c.bold}  Options:${c.reset}`)
+  console.log(`    ${c.gray}--config    Path to config file  (default: capman.config.js)${c.reset}`)
+  console.log(`    ${c.gray}--out       Output path          (default: manifest.json)${c.reset}`)
+  console.log(`    ${c.gray}--manifest  Manifest to read     (default: manifest.json)${c.reset}`)
+  console.log()
+}

package/bin/lib/cmd-init.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const path = require('path')
+const fs   = require('fs')
+const { header, log, c, requireSrc } = require('./shared')
+
+module.exports = function cmdInit() {
+  header()
+  const outPath = path.resolve(process.cwd(), 'capman.config.js')
+  if (fs.existsSync(outPath)) {
+    log.warn('capman.config.js already exists — not overwriting.')
+    process.exit(0)
+  }
+  const { generateStarterConfig } = requireSrc()
+  fs.writeFileSync(outPath, generateStarterConfig())
+  log.success(`Created ${c.bold}capman.config.js${c.reset}`)
+  log.info(`Edit it with your app's capabilities, then run:`)
+  console.log(`\n    npx capman generate\n`)
+}

package/bin/lib/cmd-inspect.js

@@ -0,0 +1,33 @@
+  'use strict'
+
+  const { header, log, c, getFlag, requireSrc } = require('./shared')
+
+  module.exports = function cmdInspect() {
+    header()
+    const { readManifest } = requireSrc()
+
+    const manifestPath = getFlag('--manifest') ?? 'manifest.json'
+    let manifest
+    try {
+      manifest = readManifest(manifestPath)
+    } catch (e) {
+      log.error(e.message)
+      process.exit(1)
+    }
+
+    console.log(`${c.bold}  App:${c.reset}          ${manifest.app}`)
+    console.log(`${c.bold}  Generated:${c.reset}    ${manifest.generatedAt}`)
+    console.log(`${c.bold}  Capabilities:${c.reset} ${manifest.capabilities.length}`)
+    console.log()
+
+    for (const cap of manifest.capabilities) {
+      const col = cap.resolver.type === 'hybrid' ? c.yellow : c.teal
+      console.log(`  ${c.bold}${cap.name}${c.reset}  ${col}[${cap.resolver.type}]${c.reset}  ${c.gray}${cap.privacy.level}${c.reset}`)
+      console.log(`  ${c.gray}id: ${cap.id}${c.reset}`)
+      console.log(`  ${cap.description}`)
+      if (cap.examples?.length) {
+        console.log(`  ${c.gray}e.g. "${cap.examples[0]}"${c.reset}`)
+      }
+      console.log()
+    }
+  }

package/bin/lib/cmd-run.js

@@ -0,0 +1,71 @@
+'use strict'
+
+const { header, log, c, args, flags, getFlag, requireSrc } = require('./shared')
+
+module.exports = function cmdRun() {
+  header()
+  const query = args[1]
+  const debug = flags.includes('--debug')
+  const manifestPath = getFlag('--manifest') ?? 'manifest.json'
+
+  if (!query) {
+    log.error('Please provide a query.')
+    console.log(`  Example: npx capman run "show me articles"\n`)
+    process.exit(1)
+  }
+
+  const { readManifest, match } = requireSrc()
+
+  let manifest
+  try {
+    manifest = readManifest(manifestPath)
+  } catch (e) {
+    log.error(e.message)
+    process.exit(1)
+  }
+
+  log.info(`Query: "${query}"`)
+  log.blank()
+
+  const result = match(query, manifest)
+
+  if (result.capability) {
+    console.log(`  ${c.green}✓${c.reset}  Matched: ${c.bold}${result.capability.id}${c.reset}`)
+    console.log(`     Intent:     ${result.intent}`)
+    console.log(`     Confidence: ${result.confidence}%`)
+    console.log(`     Resolver:   ${result.capability.resolver.type}`)
+
+    if (Object.keys(result.extractedParams).length > 0) {
+      const params = Object.entries(result.extractedParams)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ')
+      console.log(`     Params:     ${params}`)
+    }
+
+    if (debug && result.candidates.length) {
+      log.blank()
+      console.log(`  ${c.gray}── All candidates:${c.reset}`)
+      result.candidates
+        .sort((a, b) => b.score - a.score)
+        .forEach(c2 => {
+          const marker = c2.matched ? c.green + '✓' : c.gray + '○'
+          console.log(`     ${marker}${c.reset}  ${c2.capabilityId}: ${c2.score}%`)
+        })
+    }
+  } else {
+    console.log(`  ${c.yellow}○${c.reset}  OUT_OF_SCOPE — no capability matched`)
+    console.log(`     ${c.gray}${result.reasoning}${c.reset}`)
+
+    if (debug && result.candidates.length) {
+      log.blank()
+      console.log(`  ${c.gray}── All candidates:${c.reset}`)
+      result.candidates
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 5)
+        .forEach(c2 => {
+          console.log(`     ${c.gray}○  ${c2.capabilityId}: ${c2.score}%${c.reset}`)
+        })
+    }
+  }
+  console.log()
+}