@codesummary/cli 0.1.0

package/bin/codesummary.js

@@ -0,0 +1,2103 @@
+#!/usr/bin/env node
+import { createHash, randomBytes } from 'node:crypto'
+import { copyFileSync, createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { createServer } from 'node:http'
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { emitKeypressEvents } from 'node:readline'
+import { spawnSync } from 'node:child_process'
+import { homedir, tmpdir } from 'node:os'
+
+const DEFAULT_API_URL = 'https://dashboard.codesummary.io'
+const CONFIG_DIR = '.codesummary'
+const CONFIG_FILE = 'config.json'
+const MANIFEST_FILE = 'manifest.json'
+const LAST_SUBMITTED_MANIFEST_FILE = 'last-submitted-manifest.json'
+const LAST_SOURCE_CHECK_MANIFEST_FILE = 'last-source-check-manifest.json'
+const LAST_GENERATION_ATTEMPT_MANIFEST_FILE = 'last-generation-attempt-manifest.json'
+const LOCAL_GENERATION_SCHEMA_FILE = 'local-generation.schema.json'
+const DEFAULT_LOCAL_CONTEXT_BYTES = 180_000
+const DEFAULT_LOCAL_FILE_BYTES = 24_000
+const ANSI = {
+  reset: '\x1b[0m',
+  inverse: '\x1b[7m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+}
+const DEFAULT_EXCLUDES = new Set([
+  '.git',
+  'node_modules',
+  '.next',
+  'dist',
+  'dist-lambda',
+  'build',
+  'coverage',
+  '.turbo',
+  '.vercel',
+  '.cache',
+  CONFIG_DIR,
+])
+const SECRET_FILE_PATTERNS = [
+  /^\.env($|\.)/,
+  /^\.npmrc$/,
+  /^\.yarnrc$/,
+  /^id_rsa$/,
+  /^id_ed25519$/,
+]
+const GENERATED_DIR_PATTERNS = [
+  /^dist-.+/,
+  /^build-.+/,
+  /^\.serverless$/,
+  /^\.sst$/,
+]
+const GENERATED_FILE_PATTERNS = [
+  /\.zip$/i,
+  /\.tar$/i,
+  /\.tar\.gz$/i,
+  /\.tgz$/i,
+]
+
+function printHelp() {
+  console.log(`CodeSummary CLI
+
+Usage:
+  codesummary
+  codesummary new [directory] [--name <source-name>] [--api-url <url>] [--provider codex|openai|anthropic|mock] [--output <dir>] [--force]
+  codesummary login [--api-url <url>] [--scope <scope>]
+  codesummary whoami [--api-url <url>]
+  codesummary logout
+  codesummary configure [--provider codex|openai|anthropic|mock] [--output <dir>] [--api-key-env <env>] [--model <model>]
+  codesummary config set <key> <value>
+  codesummary config get [key]
+  codesummary config clear <key>
+  codesummary link --site-token <token> [--api-url <url>] [--name <source-name>] [--no-verify]
+  codesummary manifest [--root <path>]
+  codesummary diff [--root <path>] [--against <manifest.json>]
+  codesummary export [--root <path>] [--output <dir|s3://bucket/prefix>] [--include-archive]
+  codesummary generate [--provider codex|openai|anthropic|mock] [--root <path>] [--output <dir>] [--api-key-env <env>] [--model <model>] [--dry-run]
+  codesummary submit [--token <token>] [--api-url <url>] [--site <site-id-or-slug>] [--name <source-name>] [--depth standard|deep] [--no-generate] [--wait] [--verbose]
+  codesummary status [--job-id <id>] [--token <token>] [--api-url <url>] [--wait] [--verbose]
+  codesummary version
+  codesummary update
+
+Environment:
+  CODESUMMARY_API_KEY   Product token or OAuth access token with write:knowledge scope; optional after codesummary login
+  CODESUMMARY_API_URL   Dashboard API base URL
+  OPENAI_API_KEY        Used by generate --provider openai unless --api-key-env is set
+  ANTHROPIC_API_KEY     Used by generate --provider anthropic unless --api-key-env is set
+`)
+}
+
+function packageInfo() {
+  return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+}
+
+function parseArgs(argv) {
+  const out = { _: [] }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (!arg.startsWith('--')) {
+      out._.push(arg)
+      continue
+    }
+    const key = arg.slice(2)
+    if (key.startsWith('no-')) {
+      out[key.slice(3)] = false
+      continue
+    }
+    const next = argv[i + 1]
+    if (!next || next.startsWith('--')) {
+      out[key] = true
+      continue
+    }
+    out[key] = next
+    i += 1
+  }
+  return out
+}
+
+function configPath(root = process.cwd()) {
+  return join(root, CONFIG_DIR, CONFIG_FILE)
+}
+
+function readConfig(root = process.cwd()) {
+  const path = configPath(root)
+  if (!existsSync(path)) return {}
+  return JSON.parse(readFileSync(path, 'utf8'))
+}
+
+function writeConfig(config, root = process.cwd()) {
+  const dir = join(root, CONFIG_DIR)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(configPath(root), `${JSON.stringify(config, null, 2)}\n`)
+}
+
+function configKeyAllowed(key) {
+  return [
+    'apiUrl',
+    'sourceName',
+    'depth',
+    'site.id',
+    'site.slug',
+    'site.name',
+    'localGeneration.provider',
+    'localGeneration.output',
+    'localGeneration.model',
+    'localGeneration.apiKeyEnv',
+  ].includes(key)
+}
+
+function readConfigValue(config, key) {
+  return key.split('.').reduce((value, part) => value?.[part], config)
+}
+
+function writeConfigValue(config, key, value) {
+  if (!configKeyAllowed(key)) {
+    throw new Error(`Unsupported config key: ${key}`)
+  }
+  const next = { ...config }
+  const parts = key.split('.')
+  let cursor = next
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const part = parts[i]
+    cursor[part] = { ...(cursor[part] || {}) }
+    cursor = cursor[part]
+  }
+  cursor[parts[parts.length - 1]] = value
+  return next
+}
+
+function clearConfigValue(config, key) {
+  if (!configKeyAllowed(key)) {
+    throw new Error(`Unsupported config key: ${key}`)
+  }
+  const next = { ...config }
+  const parts = key.split('.')
+  let cursor = next
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const part = parts[i]
+    if (!cursor[part] || typeof cursor[part] !== 'object') return next
+    cursor[part] = { ...cursor[part] }
+    cursor = cursor[part]
+  }
+  delete cursor[parts[parts.length - 1]]
+  return next
+}
+
+function authPath() {
+  return join(homedir(), CONFIG_DIR, 'auth.json')
+}
+
+function readAuth() {
+  const path = authPath()
+  if (!existsSync(path)) return { sessions: {}, defaultKey: null }
+  return JSON.parse(readFileSync(path, 'utf8'))
+}
+
+function writeAuth(auth) {
+  const dir = join(homedir(), CONFIG_DIR)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(authPath(), `${JSON.stringify(auth, null, 2)}\n`)
+}
+
+function sleep(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms))
+}
+
+function cliAuthHeaders(token) {
+  return { 'X-CodeSummary-Token': token }
+}
+
+function shouldExclude(name, relPath) {
+  if (DEFAULT_EXCLUDES.has(name)) return true
+  if (GENERATED_DIR_PATTERNS.some((pattern) => pattern.test(name))) return true
+  if (GENERATED_FILE_PATTERNS.some((pattern) => pattern.test(name))) return true
+  if (relPath.includes(`${CONFIG_DIR}/`)) return true
+  if (SECRET_FILE_PATTERNS.some((pattern) => pattern.test(name))) return true
+  if (relPath === join(CONFIG_DIR, CONFIG_FILE)) return true
+  return false
+}
+
+function pathIsInside(parent, child) {
+  const rel = relative(resolve(parent), resolve(child))
+  return rel === '' || (!!rel && !rel.startsWith('..'))
+}
+
+function walkFiles(root, dir = root, files = [], options = {}) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const abs = join(dir, entry.name)
+    const rel = relative(root, abs)
+    if ((options.excludePaths || []).some((path) => pathIsInside(path, abs))) continue
+    if (shouldExclude(entry.name, rel)) continue
+    if (entry.isDirectory()) {
+      walkFiles(root, abs, files, options)
+    } else if (entry.isFile()) {
+      files.push(abs)
+    }
+  }
+  return files
+}
+
+function sha256File(path) {
+  const hash = createHash('sha256')
+  const stream = createReadStream(path)
+  return new Promise((resolvePromise, reject) => {
+    stream.on('data', (chunk) => hash.update(chunk))
+    stream.on('error', reject)
+    stream.on('end', () => resolvePromise(hash.digest('hex')))
+  })
+}
+
+async function writeManifest(root, options = {}) {
+  const files = walkFiles(root, root, [], options)
+  const manifestFiles = []
+  for (const file of files) {
+    const stats = statSync(file)
+    manifestFiles.push({
+      path: relative(root, file).replaceAll('\\', '/'),
+      bytes: stats.size,
+      sha256: await sha256File(file),
+      modifiedAt: stats.mtime.toISOString(),
+    })
+  }
+  manifestFiles.sort((a, b) => a.path.localeCompare(b.path))
+  const manifest = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    rootName: basename(root),
+    files: manifestFiles,
+  }
+  const dir = join(root, CONFIG_DIR)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`)
+  return manifest
+}
+
+function writeLastSubmittedManifest(root, manifest) {
+  const dir = join(root, CONFIG_DIR)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, LAST_SUBMITTED_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`)
+}
+
+function writeLastSourceCheckManifest(root, manifest) {
+  const dir = join(root, CONFIG_DIR)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, LAST_SOURCE_CHECK_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`)
+}
+
+function writeLastGenerationAttemptManifest(root, manifest) {
+  const dir = join(root, CONFIG_DIR)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, LAST_GENERATION_ATTEMPT_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`)
+}
+
+function readManifestFile(path) {
+  const manifest = JSON.parse(readFileSync(path, 'utf8'))
+  if (manifest?.schemaVersion !== 1 || !Array.isArray(manifest.files)) {
+    throw new Error(`Invalid CodeSummary manifest: ${path}`)
+  }
+  return manifest
+}
+
+function summarizeManifestDiff(previousManifest, currentManifest) {
+  const previous = new Map(previousManifest.files.map((file) => [file.path, file]))
+  const current = new Map(currentManifest.files.map((file) => [file.path, file]))
+  const added = []
+  const removed = []
+  const changed = []
+  const unchanged = []
+
+  for (const [path, file] of current.entries()) {
+    const old = previous.get(path)
+    if (!old) {
+      added.push(path)
+    } else if (old.sha256 !== file.sha256 || old.bytes !== file.bytes) {
+      changed.push(path)
+    } else {
+      unchanged.push(path)
+    }
+  }
+
+  for (const path of previous.keys()) {
+    if (!current.has(path)) removed.push(path)
+  }
+
+  return {
+    added: added.sort(),
+    changed: changed.sort(),
+    removed: removed.sort(),
+    unchanged: unchanged.length,
+  }
+}
+
+function createZip(root, options = {}) {
+  const tmp = mkdtempSync(join(tmpdir(), 'codesummary-'))
+  const archive = join(tmp, 'workspace.zip')
+  const excludes = [
+    '*.git/*',
+    '*node_modules/*',
+    '*.next/*',
+    '*dist/*',
+    '*dist-*/*',
+    '*build/*',
+    '*build-*/*',
+    '*coverage/*',
+    '*.serverless/*',
+    '*.sst/*',
+    '*.turbo/*',
+    '*.vercel/*',
+    '*.cache/*',
+    '*.codesummary/*',
+    '.codesummary/*',
+    '*.env',
+    '*.env.*',
+    '*.npmrc',
+    '*.yarnrc',
+    '*.zip',
+    '*.tar',
+    '*.tar.gz',
+    '*.tgz',
+  ]
+  for (const path of options.excludePaths || []) {
+    const rel = relative(root, path).replaceAll('\\', '/')
+    if (!rel || rel.startsWith('..')) continue
+    excludes.push(rel, `${rel}/*`, `*${rel}/*`)
+  }
+  const args = ['-qr', archive, '.', ...excludes.flatMap((pattern) => ['-x', pattern])]
+  const result = spawnSync('zip', args, { cwd: root, encoding: 'utf8' })
+  if (result.status !== 0) {
+    rmSync(tmp, { recursive: true, force: true })
+    throw new Error(result.stderr || 'zip failed')
+  }
+  return { archive, cleanup: () => rmSync(tmp, { recursive: true, force: true }) }
+}
+
+function writeExportFiles(root, outputDir, manifest, options = {}) {
+  mkdirSync(outputDir, { recursive: true })
+  const generatedAt = new Date().toISOString()
+  const metadata = {
+    schemaVersion: 1,
+    generatedAt,
+    rootName: manifest.rootName,
+    fileCount: manifest.files.length,
+    totalBytes: manifest.files.reduce((sum, file) => sum + file.bytes, 0),
+    includesSourceArchive: Boolean(options.includeArchive),
+  }
+
+  writeFileSync(join(outputDir, 'codesummary-manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+  writeFileSync(join(outputDir, 'codesummary-export.json'), `${JSON.stringify(metadata, null, 2)}\n`)
+  writeFileSync(
+    join(outputDir, 'README.md'),
+    [
+      '# CodeSummary Export',
+      '',
+      'This bundle was generated by the CodeSummary CLI.',
+      '',
+      '- `codesummary-manifest.json` contains file paths, byte sizes, mtimes, and SHA-256 hashes.',
+      '- `codesummary-export.json` contains bundle metadata.',
+      options.includeArchive
+        ? '- `workspace.zip` contains the submitted workspace with default secret/build exclusions applied.'
+        : '- Source contents are not included. Re-run with `--include-archive` only when exporting to infrastructure you control.',
+      '',
+    ].join('\n')
+  )
+  return metadata
+}
+
+function syncDirectoryToS3(localDir, output) {
+  const result = spawnSync('aws', ['s3', 'sync', localDir, output], { encoding: 'utf8' })
+  if (result.status !== 0) {
+    throw new Error(result.stderr || 'aws s3 sync failed')
+  }
+}
+
+function localGenerationSchema() {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    required: ['files'],
+    properties: {
+      files: {
+        type: 'array',
+        minItems: 1,
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['path', 'content'],
+          properties: {
+            path: {
+              type: 'string',
+              pattern: '^[A-Za-z0-9][A-Za-z0-9._/ -]*\\.md$',
+            },
+            title: { type: 'string' },
+            content: { type: 'string', minLength: 20 },
+          },
+        },
+      },
+    },
+  }
+}
+
+function localGenerationSystemPrompt() {
+  return [
+    'You are CodeSummary local generation.',
+    'Generate concise, accurate Markdown documentation for the submitted codebase context.',
+    'Return only JSON matching this shape: {"files":[{"path":"README.md","title":"...","content":"# ..."}]}.',
+    'Do not include prose outside JSON.',
+    'Do not invent APIs, services, or deployment facts that are not supported by the context.',
+    'Prefer practical docs engineers can use immediately: overview, architecture, setup, important workflows, and operational notes.',
+    'Use relative Markdown links only when they point to files you are creating.',
+    'Never include secrets or credentials.',
+  ].join('\n')
+}
+
+function isLikelyTextFile(filePath) {
+  const name = basename(filePath).toLowerCase()
+  if ([
+    'readme',
+    'makefile',
+    'dockerfile',
+    'package.json',
+    'tsconfig.json',
+    'terraform.tfvars.example',
+  ].includes(name)) return true
+  return /\.(ts|tsx|js|jsx|mjs|cjs|json|md|mdx|yml|yaml|toml|tf|sh|sql|py|go|rs|java|kt|swift|rb|php|cs|css|scss|html|txt)$/i.test(filePath)
+}
+
+function priorityForFile(relPath) {
+  const lower = relPath.toLowerCase()
+  if (/(^|\/)(readme|agents|package|pnpm-workspace|turbo|next\.config|vite\.config|dockerfile)/.test(lower)) return 0
+  if (/(^|\/)(src|app|apps|packages|lib|server|api|routes)\//.test(lower)) return 1
+  if (/(^|\/)(infra|terraform|environments|modules|deploy|scripts|\.github)\//.test(lower)) return 2
+  if (/\.(md|mdx|yml|yaml|json|tf|ts|tsx|js|jsx)$/i.test(lower)) return 3
+  return 4
+}
+
+function buildLocalContext(root, manifest, options = {}) {
+  const maxBytes = Number(options['max-context-bytes'] || DEFAULT_LOCAL_CONTEXT_BYTES)
+  const maxFileBytes = Number(options['max-file-bytes'] || DEFAULT_LOCAL_FILE_BYTES)
+  const outputDir = options.outputDir ? resolve(options.outputDir) : null
+  const files = walkFiles(root, root, [], options)
+    .map((abs) => {
+      const rel = relative(root, abs).replaceAll('\\', '/')
+      return { abs, rel, priority: priorityForFile(rel), bytes: statSync(abs).size }
+    })
+    .filter((file) => {
+      if (!isLikelyTextFile(file.rel) || file.bytes <= 0) return false
+      if (!outputDir) return true
+      const relToOutput = relative(outputDir, file.abs)
+      return relToOutput.startsWith('..') || relToOutput === ''
+    })
+    .sort((a, b) => a.priority - b.priority || a.rel.localeCompare(b.rel))
+
+  const selected = []
+  let usedBytes = 0
+  for (const file of files) {
+    if (usedBytes >= maxBytes) break
+    const limit = Math.min(file.bytes, maxFileBytes, maxBytes - usedBytes)
+    let content = readFileSync(file.abs, 'utf8')
+    if (content.length > limit) {
+      content = `${content.slice(0, limit)}\n\n[truncated by CodeSummary local context pack]\n`
+    }
+    usedBytes += Buffer.byteLength(content)
+    selected.push({ path: file.rel, bytes: file.bytes, includedBytes: Buffer.byteLength(content), content })
+  }
+
+  const tree = manifest.files.map((file) => `${file.path} (${file.bytes} bytes)`).join('\n')
+  const contents = selected.map((file) => [
+    `--- FILE: ${file.path}`,
+    file.content,
+  ].join('\n')).join('\n\n')
+
+  return {
+    selected,
+    prompt: [
+      localGenerationSystemPrompt(),
+      '',
+      `Repository root name: ${manifest.rootName}`,
+      `Manifest file count: ${manifest.files.length}`,
+      '',
+      'FULL FILE MANIFEST:',
+      tree,
+      '',
+      'SELECTED LOCAL FILE CONTENTS:',
+      contents || '(no text files selected)',
+      '',
+      'Generate a useful initial documentation set. Keep it grounded in this context.',
+    ].join('\n'),
+  }
+}
+
+function extractJsonObject(text) {
+  const trimmed = String(text || '').trim()
+  if (!trimmed) throw new Error('Provider returned an empty response.')
+  try {
+    return JSON.parse(trimmed)
+  } catch {
+    const start = trimmed.indexOf('{')
+    const end = trimmed.lastIndexOf('}')
+    if (start === -1 || end === -1 || end <= start) {
+      throw new Error('Provider response did not contain a JSON object.')
+    }
+    return JSON.parse(trimmed.slice(start, end + 1))
+  }
+}
+
+function validateGeneratedDocs(payload) {
+  if (!payload || !Array.isArray(payload.files) || payload.files.length === 0) {
+    throw new Error('Generated output must include at least one file.')
+  }
+  const normalized = []
+  for (const file of payload.files) {
+    if (!file || typeof file.path !== 'string' || typeof file.content !== 'string') {
+      throw new Error('Each generated file must include path and content.')
+    }
+    const path = file.path.replaceAll('\\', '/').replace(/^\/+/, '')
+    if (path.includes('..') || !path.endsWith('.md')) {
+      throw new Error(`Unsafe generated path: ${file.path}`)
+    }
+    if (file.content.trim().length < 20) {
+      throw new Error(`Generated file is too small: ${path}`)
+    }
+    normalized.push({ path, title: file.title || null, content: file.content.trimEnd() + '\n' })
+  }
+  return { files: normalized }
+}
+
+function writeGeneratedDocs(outputDir, generated) {
+  mkdirSync(outputDir, { recursive: true })
+  for (const file of generated.files) {
+    const target = resolve(outputDir, file.path)
+    const safeOutputRoot = resolve(outputDir)
+    const rel = relative(safeOutputRoot, target)
+    if (rel.startsWith('..') || rel === '') {
+      throw new Error(`Generated path escapes output directory: ${file.path}`)
+    }
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, file.content)
+  }
+}
+
+function runCodexProvider(prompt, options) {
+  const tmp = mkdtempSync(join(tmpdir(), 'codesummary-codex-'))
+  const outputPath = join(tmp, 'last-message.txt')
+  const schemaPath = join(tmp, LOCAL_GENERATION_SCHEMA_FILE)
+  writeFileSync(schemaPath, `${JSON.stringify(localGenerationSchema(), null, 2)}\n`)
+
+  try {
+    const command = String(options['codex-command'] || 'codex')
+    const args = [
+      'exec',
+      '--skip-git-repo-check',
+      '--ephemeral',
+      '--sandbox',
+      'read-only',
+      '--ask-for-approval',
+      'never',
+      '--output-schema',
+      schemaPath,
+      '--output-last-message',
+      outputPath,
+    ]
+    if (options.model) args.push('--model', String(options.model))
+    args.push('-')
+    const result = spawnSync(command, args, {
+      input: prompt,
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024,
+    })
+    if (result.status !== 0) {
+      throw new Error(result.stderr || result.stdout || `${command} exec failed`)
+    }
+    if (!existsSync(outputPath)) {
+      throw new Error('Codex did not write an output message.')
+    }
+    return readFileSync(outputPath, 'utf8')
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+async function callOpenAiCompatible(apiUrl, apiKey, model, prompt) {
+  const response = await fetch(apiUrl, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model,
+      messages: [
+        { role: 'system', content: localGenerationSystemPrompt() },
+        { role: 'user', content: prompt },
+      ],
+      temperature: 0.2,
+      response_format: { type: 'json_object' },
+    }),
+  })
+  const body = await response.json().catch(() => ({}))
+  if (!response.ok) {
+    throw new Error(body.error?.message || body.message || `OpenAI-compatible provider failed with HTTP ${response.status}`)
+  }
+  return body.choices?.[0]?.message?.content || ''
+}
+
+async function callAnthropic(apiUrl, apiKey, model, prompt) {
+  const response = await fetch(apiUrl, {
+    method: 'POST',
+    headers: {
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: 5000,
+      temperature: 0.2,
+      system: localGenerationSystemPrompt(),
+      messages: [{ role: 'user', content: prompt }],
+    }),
+  })
+  const body = await response.json().catch(() => ({}))
+  if (!response.ok) {
+    throw new Error(body.error?.message || body.message || `Anthropic provider failed with HTTP ${response.status}`)
+  }
+  return (body.content || []).map((part) => part.type === 'text' ? part.text : '').join('\n')
+}
+
+async function runLocalProvider(provider, prompt, options) {
+  if (provider === 'mock') {
+    return JSON.stringify({
+      files: [
+        {
+          path: 'README.md',
+          title: 'Local CodeSummary Documentation',
+          content: [
+            '# Local CodeSummary Documentation',
+            '',
+            'This mock documentation was generated without calling an inference provider.',
+            '',
+            'Use this mode to verify local packaging, schema validation, and file writing.',
+          ].join('\n'),
+        },
+      ],
+    })
+  }
+
+  if (provider === 'codex') {
+    return runCodexProvider(prompt, options)
+  }
+
+  if (provider === 'openai') {
+    const envName = String(options['api-key-env'] || 'OPENAI_API_KEY')
+    const apiKey = process.env[envName]
+    if (!apiKey) throw new Error(`Missing ${envName}. The key stays local; export it before running generate.`)
+    const apiUrl = String(options['api-url'] || 'https://api.openai.com/v1/chat/completions')
+    const model = String(options.model || 'gpt-4.1')
+    return callOpenAiCompatible(apiUrl, apiKey, model, prompt)
+  }
+
+  if (provider === 'anthropic') {
+    const envName = String(options['api-key-env'] || 'ANTHROPIC_API_KEY')
+    const apiKey = process.env[envName]
+    if (!apiKey) throw new Error(`Missing ${envName}. The key stays local; export it before running generate.`)
+    const apiUrl = String(options['api-url'] || 'https://api.anthropic.com/v1/messages')
+    const model = String(options.model || 'claude-sonnet-4-20250514')
+    return callAnthropic(apiUrl, apiKey, model, prompt)
+  }
+
+  throw new Error('Invalid provider. Use --provider codex, openai, anthropic, or mock.')
+}
+
+async function generateLocal(options) {
+  const root = resolve(options.root || process.cwd())
+  const config = readConfig(root)
+  const localConfig = localGenerationConfig(config)
+  const outputDir = resolveOutputDir(root, options.output || localConfig.output || 'docs')
+  const provider = normalizeProvider(options.provider || localConfig.provider || 'codex')
+  const providerOptions = {
+    ...options,
+    model: options.model || localConfig.model,
+    'api-key-env': options['api-key-env'] || localConfig.apiKeyEnv,
+  }
+  const manifest = await writeManifest(root, { excludePaths: [outputDir] })
+  const context = buildLocalContext(root, manifest, { ...providerOptions, outputDir })
+
+  if (options['dry-run']) {
+    console.log(JSON.stringify({
+      provider,
+      root,
+      output: outputDir,
+      manifestFiles: manifest.files.length,
+      selectedFiles: context.selected.map((file) => ({
+        path: file.path,
+        bytes: file.bytes,
+        includedBytes: file.includedBytes,
+      })),
+      promptBytes: Buffer.byteLength(context.prompt),
+      sendsSourceToCodeSummary: false,
+      sendsProviderKeyToCodeSummary: false,
+    }, null, 2))
+    return
+  }
+
+  const raw = await runLocalProvider(provider, context.prompt, providerOptions)
+  const generated = validateGeneratedDocs(extractJsonObject(raw))
+  writeGeneratedDocs(outputDir, generated)
+  writeConfig({ ...config, lastLocalGenerate: { provider, output: outputDir, generatedAt: new Date().toISOString() } }, root)
+  console.log(JSON.stringify({
+    provider,
+    output: outputDir,
+    files: generated.files.map((file) => file.path),
+    sendsSourceToCodeSummary: false,
+    sendsProviderKeyToCodeSummary: false,
+  }, null, 2))
+}
+
+async function exportBundle(options) {
+  const root = resolve(options.root || process.cwd())
+  const output = options.output || join(root, CONFIG_DIR, 'export')
+  if (typeof output !== 'string') {
+    throw new Error('export requires --output <dir|s3://bucket/prefix> when --output is provided')
+  }
+  const includeArchive = options['include-archive'] === true
+  const manifest = await writeManifest(root)
+  const isS3Output = typeof output === 'string' && output.startsWith('s3://')
+  const targetDir = isS3Output ? mkdtempSync(join(tmpdir(), 'codesummary-export-')) : resolve(output)
+  let archiveCleanup = null
+  let archive = null
+
+  try {
+    if (includeArchive) {
+      const zipped = createZip(root, { excludePaths: [targetDir] })
+      archive = zipped.archive
+      archiveCleanup = zipped.cleanup
+    }
+    const metadata = writeExportFiles(root, targetDir, manifest, { includeArchive })
+    if (includeArchive) {
+      copyFileSync(archive, join(targetDir, 'workspace.zip'))
+    }
+
+    if (isS3Output) {
+      syncDirectoryToS3(targetDir, output)
+      console.log(JSON.stringify({ output, ...metadata }, null, 2))
+    } else {
+      console.log(JSON.stringify({ output: targetDir, ...metadata }, null, 2))
+    }
+  } finally {
+    if (archiveCleanup) archiveCleanup()
+    if (isS3Output) rmSync(targetDir, { recursive: true, force: true })
+  }
+}
+
+function resolveApiUrl(options, config) {
+  return (options['api-url'] || process.env.CODESUMMARY_API_URL || config.apiUrl || DEFAULT_API_URL).replace(/\/$/, '')
+}
+
+function base64Url(buffer) {
+  return Buffer.from(buffer).toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_')
+}
+
+function createPkcePair() {
+  const verifier = base64Url(randomBytes(32))
+  const challenge = base64Url(createHash('sha256').update(verifier).digest())
+  return { verifier, challenge }
+}
+
+function tokenExpiryFromResponse(body) {
+  const expiresIn = Number(body.expires_in || 3600)
+  return new Date(Date.now() + Math.max(60, expiresIn - 60) * 1000).toISOString()
+}
+
+function oauthTokenIsFresh(oauth) {
+  if (!oauth?.accessToken || !oauth.expiresAt) return false
+  return new Date(oauth.expiresAt).getTime() > Date.now() + 30 * 1000
+}
+
+function oauthSessionKey(apiUrl, resource) {
+  return `${apiUrl}|${resource || 'default'}`
+}
+
+function resolveStoredOAuth(config) {
+  const auth = readAuth()
+  const key = config.oauthKey || auth.defaultKey
+  if (key && auth.sessions?.[key]) {
+    return { auth, key, session: auth.sessions[key], source: 'global' }
+  }
+  if (config.oauth?.accessToken) {
+    return { auth, key: null, session: config.oauth, source: 'workspace' }
+  }
+  return { auth, key: null, session: null, source: null }
+}
+
+async function refreshOAuthToken(apiUrl, session, storage, config, root) {
+  const refreshToken = session?.refreshToken
+  if (!refreshToken) {
+    throw new Error('OAuth session expired. Run `codesummary login` again.')
+  }
+
+  const params = new URLSearchParams()
+  params.set('grant_type', 'refresh_token')
+  params.set('refresh_token', refreshToken)
+
+  const tokenUrl = `${apiUrl}/api/oauth/token`
+  if (process.env.CODESUMMARY_DEBUG) console.error(`[debug] POST ${tokenUrl} grant_type=refresh_token`)
+  const response = await fetch(tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: params.toString(),
+  })
+  const body = await response.json().catch(() => ({}))
+  if (process.env.CODESUMMARY_DEBUG) console.error(`[debug] oauth refresh status=${response.status} body=${JSON.stringify(body).slice(0, 500)}`)
+  if (!response.ok) {
+    throw new Error(body.error_description || body.message || `OAuth refresh failed with HTTP ${response.status}. Run \`codesummary login\` again.`)
+  }
+
+  const nextSession = {
+    ...session,
+    accessToken: body.access_token,
+    refreshToken: body.refresh_token || refreshToken,
+    expiresAt: tokenExpiryFromResponse(body),
+    scope: body.scope || session?.scope,
+  }
+
+  if (storage.source === 'global' && storage.key) {
+    const auth = {
+      ...storage.auth,
+      sessions: {
+        ...(storage.auth.sessions || {}),
+        [storage.key]: nextSession,
+      },
+      defaultKey: storage.auth.defaultKey || storage.key,
+    }
+    writeAuth(auth)
+    return { token: nextSession.accessToken, config }
+  }
+
+  const nextConfig = { ...config, oauth: nextSession }
+  writeConfig(nextConfig, root)
+  return { token: nextSession.accessToken, config: nextConfig }
+}
+
+async function resolveAuth(options, config, root) {
+  const staticToken = options.token || options['site-token'] || process.env.CODESUMMARY_API_KEY || config.siteToken
+  if (staticToken) return { token: staticToken, config }
+
+  const apiUrl = resolveApiUrl(options, config)
+  const storage = resolveStoredOAuth(config)
+  if (oauthTokenIsFresh(storage.session)) {
+    return { token: storage.session.accessToken, config }
+  }
+  if (storage.session?.refreshToken) {
+    return refreshOAuthToken(apiUrl, storage.session, storage, config, root)
+  }
+
+  throw new Error('Missing token. Run `codesummary login`, `codesummary link --site-token <token>`, or set CODESUMMARY_API_KEY.')
+}
+
+function normalizeOAuthResource(value, options = {}) {
+  const raw = value || options.site || options.target
+  if (!raw) return ''
+  if (/^https?:\/\//i.test(raw)) return raw
+  const trimmed = String(raw).replace(/^\/+|\/+$/g, '')
+  const parts = trimmed.split('/')
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error('OAuth resource must be <owner>/<site> or a full /mcp/<owner>/<site> URL.')
+  }
+  const mcpOrigin = String(options['mcp-origin'] || 'https://webhooks.codesummary.io').replace(/\/$/, '')
+  return `${mcpOrigin}/mcp/${encodeURIComponent(parts[0])}/${encodeURIComponent(parts[1])}`
+}
+
+async function registerOAuthClient(apiUrl, redirectUri) {
+  const response = await fetch(`${apiUrl}/api/oauth/register`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      client_name: 'CodeSummary CLI',
+      redirect_uris: [redirectUri],
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      token_endpoint_auth_method: 'none',
+    }),
+  })
+  const body = await response.json().catch(() => ({}))
+  if (!response.ok) {
+    throw new Error(body.error_description || body.message || `OAuth client registration failed with HTTP ${response.status}`)
+  }
+  return body
+}
+
+function openBrowser(url) {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]
+  const result = spawnSync(command, args, { stdio: 'ignore' })
+  return result.status === 0
+}
+
+function closeServer(server) {
+  if (!server.listening) return
+  server.close()
+}
+
+function waitForOAuthCallback(server, expectedState) {
+  return new Promise((resolvePromise, reject) => {
+    const timeout = setTimeout(() => {
+      closeServer(server)
+      reject(new Error('Timed out waiting for OAuth callback.'))
+    }, 10 * 60 * 1000)
+
+    server.on('request', (req, res) => {
+      try {
+        const url = new URL(req.url || '/', 'http://127.0.0.1')
+        if (url.pathname !== '/callback') {
+          res.writeHead(404)
+          res.end('Not found')
+          return
+        }
+        const error = url.searchParams.get('error')
+        const code = url.searchParams.get('code')
+        const state = url.searchParams.get('state')
+        if (state !== expectedState) {
+          throw new Error('OAuth state mismatch.')
+        }
+        if (error) {
+          throw new Error(url.searchParams.get('error_description') || error)
+        }
+        if (!code) {
+          throw new Error('OAuth callback did not include a code.')
+        }
+        clearTimeout(timeout)
+        res.writeHead(200, { 'Content-Type': 'text/html' })
+        res.end('<!doctype html><title>CodeSummary CLI</title><body style="font-family: system-ui; padding: 2rem;">CodeSummary CLI is logged in. You can close this window.</body>')
+        closeServer(server)
+        resolvePromise(code)
+      } catch (error) {
+        clearTimeout(timeout)
+        res.writeHead(400, { 'Content-Type': 'text/plain' })
+        res.end(error instanceof Error ? error.message : String(error))
+        closeServer(server)
+        reject(error)
+      }
+    })
+  })
+}
+
+async function exchangeOAuthCode(apiUrl, clientId, redirectUri, code, verifier) {
+  const params = new URLSearchParams()
+  params.set('grant_type', 'authorization_code')
+  params.set('client_id', clientId)
+  params.set('redirect_uri', redirectUri)
+  params.set('code', code)
+  params.set('code_verifier', verifier)
+
+  const response = await fetch(`${apiUrl}/api/oauth/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: params.toString(),
+  })
+  const body = await response.json().catch(() => ({}))
+  if (!response.ok) {
+    throw new Error(body.error_description || body.message || `OAuth token exchange failed with HTTP ${response.status}`)
+  }
+  return body
+}
+
+async function login(options) {
+  const root = resolve(options.root || process.cwd())
+  const existing = readConfig(root)
+  const apiUrl = resolveApiUrl(options, existing)
+  const resource = normalizeOAuthResource(options.resource, options)
+  const scope = String(options.scope || 'write:knowledge')
+  const server = createServer()
+
+  await new Promise((resolvePromise, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', resolvePromise)
+  })
+
+  const address = server.address()
+  const port = typeof address === 'object' && address ? address.port : null
+  if (!port) throw new Error('Failed to allocate OAuth callback port.')
+  try {
+    const redirectUri = `http://127.0.0.1:${port}/callback`
+    const client = await registerOAuthClient(apiUrl, redirectUri)
+    const { verifier, challenge } = createPkcePair()
+    const state = base64Url(randomBytes(18))
+
+    const authorizeUrl = new URL(`${apiUrl}/oauth/authorize`)
+    authorizeUrl.searchParams.set('response_type', 'code')
+    authorizeUrl.searchParams.set('client_id', client.client_id)
+    authorizeUrl.searchParams.set('redirect_uri', redirectUri)
+    authorizeUrl.searchParams.set('code_challenge', challenge)
+    authorizeUrl.searchParams.set('code_challenge_method', 'S256')
+    authorizeUrl.searchParams.set('state', state)
+    authorizeUrl.searchParams.set('scope', scope)
+    if (resource) authorizeUrl.searchParams.set('resource', resource)
+
+    console.error(`Opening browser for CodeSummary login: ${authorizeUrl.toString()}`)
+    if (!openBrowser(authorizeUrl.toString())) {
+      console.error(`Open this URL to continue:\n${authorizeUrl.toString()}`)
+    }
+
+    const code = await waitForOAuthCallback(server, state)
+    const tokenBody = await exchangeOAuthCode(apiUrl, client.client_id, redirectUri, code, verifier)
+    const oauth = {
+      clientId: client.client_id,
+      accessToken: tokenBody.access_token,
+      refreshToken: tokenBody.refresh_token,
+      expiresAt: tokenExpiryFromResponse(tokenBody),
+      scope: tokenBody.scope || scope,
+      resource: resource || null,
+    }
+    const key = oauthSessionKey(apiUrl, resource)
+    const auth = readAuth()
+    writeAuth({
+      ...auth,
+      sessions: {
+        ...(auth.sessions || {}),
+        [key]: oauth,
+      },
+      defaultKey: key,
+    })
+
+    const sourceName = options.name || existing.sourceName || basename(root)
+    const next = {
+      ...existing,
+      apiUrl,
+      sourceName,
+      oauthKey: key,
+      oauthResource: resource || null,
+    }
+    delete next.oauth
+
+    let linked = null
+    try {
+      linked = await fetchLinkedSite(apiUrl, oauth.accessToken)
+      next.site = linked.site || existing.site
+    } catch {
+      linked = null
+    }
+
+    writeConfig(next, root)
+    if (linked?.site) {
+      console.log(`Logged in and linked ${sourceName} to ${linked.site.name} (${linked.site.id}) at ${apiUrl}`)
+    } else {
+      console.log(`Logged in to CodeSummary at ${apiUrl}`)
+    }
+  } catch (error) {
+    closeServer(server)
+    throw error
+  }
+}
+
+async function logout(options) {
+  const root = resolve(options.root || process.cwd())
+  const existing = readConfig(root)
+  const auth = readAuth()
+  const key = existing.oauthKey || auth.defaultKey
+  if (key && auth.sessions?.[key]) {
+    const sessions = { ...auth.sessions }
+    delete sessions[key]
+    writeAuth({
+      ...auth,
+      sessions,
+      defaultKey: auth.defaultKey === key ? null : auth.defaultKey,
+    })
+  }
+  const next = { ...existing }
+  delete next.oauth
+  delete next.oauthKey
+  delete next.oauthResource
+  delete next.siteToken
+  writeConfig(next, root)
+  console.log('Logged out of CodeSummary CLI for this workspace.')
+}
+
+async function whoami(options) {
+  const root = resolve(options.root || process.cwd())
+  const config = readConfig(root)
+  const apiUrl = resolveApiUrl(options, config)
+  const auth = await resolveAuth(options, config, root)
+  const storage = resolveStoredOAuth(auth.config)
+  let linked = null
+  try {
+    linked = await fetchLinkedSite(apiUrl, auth.token)
+  } catch {
+    linked = null
+  }
+
+  console.log(JSON.stringify({
+    apiUrl,
+    workspace: root,
+    sourceName: auth.config.sourceName || basename(root),
+    auth: {
+      type: storage.session ? 'oauth' : 'token',
+      scope: storage.session?.scope || null,
+      resource: storage.session?.resource || null,
+      expiresAt: storage.session?.expiresAt || null,
+      storage: storage.source || (auth.token ? 'environment-or-config-token' : null),
+    },
+    site: linked?.site || auth.config.site || null,
+    account: linked?.account || null,
+  }, null, 2))
+}
+
+function terminalStatus(status) {
+  return status === 'completed' || status === 'failed' || status === 'cancelled'
+}
+
+function normalizeDepth(value) {
+  if (!value) return 'standard'
+  if (value === 'standard' || value === 'deep') return value
+  throw new Error('Invalid depth. Use --depth standard or --depth deep.')
+}
+
+function normalizeProvider(value) {
+  const provider = String(value || 'codex').toLowerCase()
+  if (['codex', 'openai', 'anthropic', 'mock'].includes(provider)) return provider
+  throw new Error('Invalid provider. Use codex, openai, anthropic, or mock.')
+}
+
+function localGenerationConfig(config) {
+  return config.localGeneration || {}
+}
+
+function resolveOutputDir(root, output = 'docs') {
+  const value = String(output)
+  return isAbsolute(value) ? resolve(value) : resolve(root, value)
+}
+
+async function configure(options) {
+  const root = resolve(options.root || process.cwd())
+  const existing = readConfig(root)
+  const current = localGenerationConfig(existing)
+  const nextLocal = { ...current }
+
+  if (options.provider) nextLocal.provider = normalizeProvider(options.provider)
+  if (options.output) nextLocal.output = String(options.output)
+  if (options.model) nextLocal.model = String(options.model)
+  if (options['api-key-env']) nextLocal.apiKeyEnv = String(options['api-key-env'])
+  if (options.default) {
+    throw new Error('Bare `codesummary` now starts the hosted interactive flow. Use `codesummary generate` for local inference.')
+  }
+
+  const next = {
+    ...existing,
+    localGeneration: nextLocal,
+  }
+  writeConfig(next, root)
+  console.log(JSON.stringify({
+    path: configPath(root),
+    localGeneration: nextLocal,
+    storesProviderKey: false,
+  }, null, 2))
+}
+
+async function configCommand(options) {
+  const root = resolve(options.root || process.cwd())
+  const [subcommand, key, ...valueParts] = options._
+  const existing = readConfig(root)
+
+  if (!subcommand || subcommand === 'list') {
+    console.log(JSON.stringify(existing, null, 2))
+    return
+  }
+
+  if (subcommand === 'get') {
+    if (!key) {
+      console.log(JSON.stringify(existing, null, 2))
+      return
+    }
+    if (!configKeyAllowed(key)) throw new Error(`Unsupported config key: ${key}`)
+    const value = readConfigValue(existing, key)
+    if (value === undefined) {
+      process.exitCode = 1
+      return
+    }
+    if (typeof value === 'object') {
+      console.log(JSON.stringify(value, null, 2))
+    } else {
+      console.log(String(value))
+    }
+    return
+  }
+
+  if (subcommand === 'set') {
+    if (!key || valueParts.length === 0) {
+      throw new Error('Usage: codesummary config set <key> <value>')
+    }
+    let value = valueParts.join(' ')
+    if (key === 'depth') value = normalizeDepth(value)
+    if (key === 'localGeneration.provider') value = normalizeProvider(value)
+    const next = writeConfigValue(existing, key, value)
+    writeConfig(next, root)
+    console.log(`Set ${key}.`)
+    return
+  }
+
+  if (subcommand === 'clear') {
+    if (!key) throw new Error('Usage: codesummary config clear <key>')
+    const next = clearConfigValue(existing, key)
+    writeConfig(next, root)
+    console.log(`Cleared ${key}.`)
+    return
+  }
+
+  throw new Error('Usage: codesummary config [list|get|set|clear]')
+}
+
+async function newWorkspace(options) {
+  const target = resolve(options._[0] || options.root || process.cwd())
+  const sourceName = options.name || basename(target)
+  const existingConfigPath = configPath(target)
+  const targetExists = existsSync(target)
+  const targetEntries = targetExists ? readdirSync(target) : []
+  const isCurrentDirectory = target === resolve(process.cwd())
+
+  if (targetExists && targetEntries.length > 0 && !isCurrentDirectory && !options.force) {
+    throw new Error(`Directory is not empty: ${target}. Pass --force to initialize it without deleting files.`)
+  }
+
+  mkdirSync(target, { recursive: true })
+  const existing = readConfig(target)
+  const next = {
+    ...existing,
+    apiUrl: resolveApiUrl(options, existing),
+    sourceName,
+  }
+  if (options.provider || options.output || options.model || options['api-key-env']) {
+    next.localGeneration = {
+      ...(existing.localGeneration || {}),
+      ...(options.provider ? { provider: normalizeProvider(options.provider) } : {}),
+      ...(options.output ? { output: String(options.output) } : {}),
+      ...(options.model ? { model: String(options.model) } : {}),
+      ...(options['api-key-env'] ? { apiKeyEnv: String(options['api-key-env']) } : {}),
+    }
+  }
+  writeConfig(next, target)
+
+  const readmePath = join(target, 'README.md')
+  if (!targetExists || targetEntries.length === 0) {
+    writeFileSync(
+      readmePath,
+      [
+        `# ${sourceName}`,
+        '',
+        'This workspace is ready for CodeSummary.',
+        '',
+        'Run `codesummary login`, then `codesummary` to create or update hosted knowledge.',
+        '',
+      ].join('\n')
+    )
+  }
+
+  console.log('Initialized CodeSummary workspace.')
+  console.log(`  Path: ${target}`)
+  console.log(`  Config: ${existingConfigPath}`)
+  console.log(`  Source: ${sourceName}`)
+  console.log(`  API: ${next.apiUrl}`)
+  console.log('')
+  console.log('Next: run `codesummary login`, then `codesummary`.')
+}
+
+function printVersion() {
+  const pkg = packageInfo()
+  console.log(`${pkg.name} ${pkg.version}`)
+}
+
+function printUpdateInstructions() {
+  const pkg = packageInfo()
+  const installName = pkg.name === 'codesummary' ? 'codesummary' : pkg.name
+  console.log(`Update with: npm install -g ${installName}@latest`)
+}
+
+async function fetchLinkedSite(apiUrl, token) {
+  const response = await fetch(`${apiUrl}/api/cli/site`, {
+    headers: cliAuthHeaders(token),
+  })
+  const body = await response.json().catch(() => ({}))
+  if (!response.ok) {
+    throw new Error(body.message || body.error || `Link verification failed with HTTP ${response.status}`)
+  }
+  return body
+}
+
+async function fetchJobStatus(apiUrl, token, jobId) {
+  const response = await fetch(`${apiUrl}/api/cli/jobs/${jobId}`, {
+    headers: cliAuthHeaders(token),
+  })
+  const body = await response.json().catch(() => ({}))
+  if (!response.ok) {
+    throw new Error(body.message || body.error || `Status failed with HTTP ${response.status}`)
+  }
+  return body
+}
+
+function jobStatusTitle(status) {
+  if (status === 'pending') return 'Knowledge generation is queued.'
+  if (status === 'processing') return 'Knowledge generation is running.'
+  if (status === 'completed') return 'Knowledge generation completed.'
+  if (status === 'failed') return 'Knowledge generation failed.'
+  if (status === 'cancelled') return 'Knowledge generation was cancelled.'
+  if (status === 'skipped') return 'Knowledge generation was skipped.'
+  return 'Knowledge generation status.'
+}
+
+function formatElapsed(value) {
+  if (!value) return null
+  const ms = Date.now() - new Date(value).getTime()
+  if (!Number.isFinite(ms) || ms < 0) return null
+  const seconds = Math.floor(ms / 1000)
+  if (seconds < 60) return `${seconds}s ago`
+  const minutes = Math.floor(seconds / 60)
+  if (minutes < 60) return `${minutes}m ago`
+  const hours = Math.floor(minutes / 60)
+  return `${hours}h ago`
+}
+
+function siteDashboardUrl(apiUrl, site) {
+  if (!apiUrl || !site?.id) return null
+  return `${String(apiUrl).replace(/\/$/, '')}/dashboard/sites/${site.id}`
+}
+
+function isStagingApiUrl(apiUrl) {
+  return /(^|[./-])staging([./-]|$)/i.test(String(apiUrl || ''))
+}
+
+function isZeroSpendJob(job) {
+  if (!job || job.status !== 'completed') return false
+  const cost = Number(job.cost_usd ?? 0)
+  const credits = Number(job.credits_used ?? 0)
+  const input = Number(job.input_tokens ?? 0)
+  const output = Number(job.output_tokens ?? 0)
+  return cost === 0 && credits === 0 && input === 0 && output === 0
+}
+
+function printJobStatus(body, options = {}) {
+  const job = body.job
+  if (options.verbose) {
+    console.log(JSON.stringify(body, null, 2))
+    if (job?.status === 'failed' && job.error) {
+      console.error(`Job failed: ${job.error}`)
+    }
+    return
+  }
+
+  if (!job) {
+    console.log('No knowledge generation job found.')
+    return
+  }
+
+  console.log(jobStatusTitle(job.status))
+  if (body.source?.name) console.log(`  Source: ${body.source.name}`)
+  if (body.site?.name) console.log(`  Site: ${body.site.name}`)
+  const siteUrl = siteDashboardUrl(options.apiUrl, body.site)
+  if (siteUrl) console.log(`  Open: ${siteUrl}`)
+  console.log(`  Job: ${job.id}`)
+  console.log(`  Status: ${job.status || 'unknown'}`)
+  const createdAgo = formatElapsed(job.created_at)
+  if (createdAgo) console.log(`  Created: ${createdAgo}`)
+  if (job.progress_message) console.log(`  Progress: ${job.progress_message}`)
+  if (job.credits_used) console.log(`  Credits used: ${job.credits_used}`)
+  if (job?.status === 'failed' && job.error) {
+    console.log(`  Error: ${job.error}`)
+  }
+  if (isStagingApiUrl(options.apiUrl) && isZeroSpendJob(job)) {
+    console.log('  Staging: completed without provider spend. This verifies the pipeline, not final documentation quality.')
+  }
+  if (body.siteJob?.id) {
+    console.log('')
+    console.log(`Site update: ${body.siteJob.status || 'unknown'}`)
+    console.log(`  Job: ${body.siteJob.id}`)
+    if (body.siteJob.progress_message) console.log(`  Progress: ${body.siteJob.progress_message}`)
+    if (isStagingApiUrl(options.apiUrl) && isZeroSpendJob(body.siteJob)) {
+      console.log('  Staging: site docs were produced by the no-spend test path.')
+    }
+  }
+}
+
+function printSubmitSummary(output, options = {}) {
+  const site = output.site
+  const source = output.source
+  const job = output.job
+  const generate = options.generate !== false
+  const siteUrl = siteDashboardUrl(options.apiUrl, site)
+
+  if (job?.id) {
+    console.log('Knowledge generation started.')
+    console.log(`  Source: ${source?.name || 'workspace'}`)
+    if (site?.name) console.log(`  Site: ${site.name}`)
+    if (siteUrl) console.log(`  Open: ${siteUrl}`)
+    console.log(`  Job: ${job.id}`)
+    console.log(`  Status: ${job.status || 'pending'}`)
+    console.log('')
+    console.log('Run `codesummary status --wait` to follow progress.')
+    return
+  }
+
+  if (generate) {
+    console.log('Source uploaded, but no generation job was created.')
+    if (site?.name) console.log(`  Site: ${site.name}`)
+    if (siteUrl) console.log(`  Open: ${siteUrl}`)
+    console.log('Run `codesummary status` if you already have a job id, or try again.')
+    return
+  }
+
+  const retainedArchive = source?.uploadRetained !== false
+  console.log(retainedArchive ? 'Source uploaded.' : 'Setup verified.')
+  console.log(`  Files: ${output.manifestFileCount ?? source?.manifest?.fileCount ?? 'unknown'}`)
+  if (site?.name) console.log(`  Site: ${site.name}`)
+  if (siteUrl) console.log(`  Open: ${siteUrl}`)
+  if (!retainedArchive) console.log('No source archive was retained.')
+  console.log('No generation job was started.')
+}
+
+function maybePromoteCompletedGenerationBaseline(root, config, body) {
+  const job = body?.job
+  if (!job?.id || job.status !== 'completed') return false
+  const lastSubmit = config.lastSubmit || null
+  if (!lastSubmit?.generated || lastSubmit.jobId !== job.id) return false
+
+  const attemptPath = join(root, CONFIG_DIR, LAST_GENERATION_ATTEMPT_MANIFEST_FILE)
+  if (!existsSync(attemptPath)) return false
+  const manifest = readManifestFile(attemptPath)
+  writeLastSubmittedManifest(root, manifest)
+  return true
+}
+
+async function waitForJob(apiUrl, token, jobId, options = {}) {
+  const intervalMs = Number(options['poll-interval-ms'] || 5000)
+  const timeoutMs = Number(options['timeout-ms'] || 20 * 60 * 1000)
+  const started = Date.now()
+  let lastStatus = ''
+  let lastSiteStatus = ''
+  let lastHeartbeat = 0
+
+  for (;;) {
+    const body = await fetchJobStatus(apiUrl, token, jobId)
+    const status = body.job?.status || 'unknown'
+    const now = Date.now()
+    if (status !== lastStatus || now - lastHeartbeat >= Math.max(intervalMs, 15000)) {
+      const message = body.job?.progress_message ? ` - ${body.job.progress_message}` : ''
+      const elapsed = Math.floor((now - started) / 1000)
+      console.error(`Job ${jobId}: ${status}${message} (${elapsed}s elapsed)`)
+      lastStatus = status
+      lastHeartbeat = now
+    }
+    const siteJob = body.siteJob
+    const siteStatus = siteJob?.status || ''
+    if (siteJob?.id && siteStatus !== lastSiteStatus) {
+      const message = siteJob.progress_message ? ` - ${siteJob.progress_message}` : ''
+      console.error(`Site job ${siteJob.id}: ${siteStatus}${message}`)
+      lastSiteStatus = siteStatus
+    }
+    if (terminalStatus(status)) {
+      if (status === 'completed' && siteJob?.id && !terminalStatus(siteStatus)) {
+        if (Date.now() - started > timeoutMs) {
+          throw new Error(`Timed out waiting for site job ${siteJob.id}`)
+        }
+        await sleep(intervalMs)
+        continue
+      }
+      printJobStatus(body, { ...options, apiUrl })
+      if (status !== 'completed' || (siteJob?.id && siteStatus !== 'completed')) process.exitCode = 1
+      return body
+    }
+    if (Date.now() - started > timeoutMs) {
+      throw new Error(`Timed out waiting for job ${jobId}`)
+    }
+    await sleep(intervalMs)
+  }
+}
+
+async function submit(options) {
+  const root = resolve(options.root || process.cwd())
+  const config = readConfig(root)
+  const auth = await resolveAuth(options, config, root)
+  const token = auth.token
+  const activeConfig = auth.config
+  const apiUrl = resolveApiUrl(options, activeConfig)
+  const name = options.name || activeConfig.sourceName || basename(root)
+  const depth = normalizeDepth(options.depth || activeConfig.depth)
+  const generate = options.generate !== false
+  const site = options.site || options['site-id'] || activeConfig.site?.id || activeConfig.site?.slug || null
+
+  const manifest = await writeManifest(root)
+  const { archive, cleanup } = createZip(root)
+  try {
+    const buffer = readFileSync(archive)
+    const form = new FormData()
+    form.set('name', name)
+    form.set('sourceRoot', root)
+    form.set('depth', depth)
+    form.set('generate', String(generate))
+    form.set('manifest', JSON.stringify(manifest))
+    if (site) form.set('site', String(site))
+    form.set('file', new Blob([buffer], { type: 'application/zip' }), `${name}.zip`)
+
+    const submitUrl = `${apiUrl}/api/cli/submit`
+    if (process.env.CODESUMMARY_DEBUG) console.error(`[debug] POST ${submitUrl} generate=${generate} fileBytes=${buffer.length}`)
+    const response = await fetch(submitUrl, {
+      method: 'POST',
+      headers: cliAuthHeaders(token),
+      body: form,
+    })
+    const body = await response.json().catch(() => ({}))
+    if (process.env.CODESUMMARY_DEBUG) console.error(`[debug] submit status=${response.status} body=${JSON.stringify(body).slice(0, 500)}`)
+    if (!response.ok) {
+      throw new Error(body.message || body.error || `Submit failed with HTTP ${response.status}`)
+    }
+    const output = { ...body, manifestFileCount: manifest.files.length }
+    const nextConfig = {
+      ...activeConfig,
+      apiUrl,
+      sourceName: name,
+      depth,
+      lastJobId: body.job?.id || activeConfig.lastJobId,
+      lastSourceId: body.source?.id || activeConfig.lastSourceId,
+      lastSiteId: body.site?.id || activeConfig.lastSiteId,
+      site: body.site || activeConfig.site,
+      lastSubmit: {
+        generated: Boolean(generate && body.job?.id),
+        jobId: body.job?.id || null,
+        sourceId: body.source?.id || null,
+        siteId: body.site?.id || null,
+        manifestFileCount: manifest.files.length,
+        submittedAt: new Date().toISOString(),
+      },
+    }
+    writeConfig(nextConfig, root)
+    if (generate && body.job?.id) {
+      writeLastGenerationAttemptManifest(root, manifest)
+    } else if (!generate) {
+      writeLastSourceCheckManifest(root, manifest)
+    }
+    if (options.verbose) {
+      console.log(JSON.stringify(output, null, 2))
+    } else if (!options.silent) {
+      printSubmitSummary(output, { generate, apiUrl })
+    }
+    if (options.wait && body.job?.id) {
+      const completed = await waitForJob(apiUrl, token, body.job.id, options)
+      if (completed.job?.status === 'completed') {
+        writeLastSubmittedManifest(root, manifest)
+      }
+    }
+    return output
+  } finally {
+    cleanup()
+  }
+}
+
+async function link(options) {
+  const root = resolve(options.root || process.cwd())
+  const existing = readConfig(root)
+  const apiUrl = resolveApiUrl(options, existing)
+  const siteToken = options['site-token'] || options.token || process.env.CODESUMMARY_API_KEY || existing.siteToken
+  if (!siteToken) {
+    throw new Error('link requires --site-token <token>')
+  }
+
+  const linked = options.verify === false ? null : await fetchLinkedSite(apiUrl, siteToken)
+  const sourceName = options.name || existing.sourceName || basename(root)
+  const next = {
+    ...existing,
+    apiUrl,
+    sourceName,
+    siteToken,
+    site: linked?.site || existing.site,
+  }
+  writeConfig(next, root)
+
+  if (linked?.site) {
+    console.log(`Linked ${sourceName} to ${linked.site.name} (${linked.site.id}) at ${apiUrl}`)
+  } else {
+    console.log(`Linked ${sourceName} to ${apiUrl}`)
+  }
+}
+
+async function status(options) {
+  const root = resolve(options.root || process.cwd())
+  const config = readConfig(root)
+  const auth = await resolveAuth(options, config, root)
+  const token = auth.token
+  const activeConfig = auth.config
+  const apiUrl = resolveApiUrl(options, activeConfig)
+  const jobId = options['job-id'] || activeConfig.lastJobId
+  if (!jobId) {
+    throw new Error('Missing job id. Pass --job-id <id> or run submit first.')
+  }
+
+  if (options.wait) {
+    const body = await waitForJob(apiUrl, token, jobId, options)
+    maybePromoteCompletedGenerationBaseline(root, config, body)
+    return
+  }
+
+  const body = await fetchJobStatus(apiUrl, token, jobId)
+  maybePromoteCompletedGenerationBaseline(root, config, body)
+  printJobStatus(body, { ...options, apiUrl })
+}
+
+async function diff(options) {
+  const root = resolve(options.root || process.cwd())
+  const baselinePath = resolve(
+    options.against || join(root, CONFIG_DIR, LAST_SUBMITTED_MANIFEST_FILE)
+  )
+  if (!existsSync(baselinePath)) {
+    throw new Error(
+      `Missing baseline manifest. Run submit first or pass --against <manifest.json>. Expected ${baselinePath}`
+    )
+  }
+
+  const previousManifest = readManifestFile(baselinePath)
+  const currentManifest = await writeManifest(root)
+  const summary = summarizeManifestDiff(previousManifest, currentManifest)
+  console.log(
+    JSON.stringify(
+      {
+        baseline: baselinePath,
+        current: join(root, CONFIG_DIR, MANIFEST_FILE),
+        counts: {
+          added: summary.added.length,
+          changed: summary.changed.length,
+          removed: summary.removed.length,
+          unchanged: summary.unchanged,
+        },
+        added: summary.added,
+        changed: summary.changed,
+        removed: summary.removed,
+      },
+      null,
+      2
+    )
+  )
+}
+
+function isInteractiveTerminal() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY)
+}
+
+async function promptChoice(title, choices) {
+  if (!isInteractiveTerminal()) {
+    throw new Error('Interactive mode requires a terminal. Use an explicit command such as `codesummary submit`.')
+  }
+
+  emitKeypressEvents(process.stdin)
+  const wasRaw = process.stdin.isRaw
+  if (process.stdin.setRawMode) process.stdin.setRawMode(true)
+
+  let selected = 0
+  let renderedLines = 0
+  const terminalWidth = () => Math.max(40, process.stdout.columns || 80)
+  const padLine = (value) => {
+    const visibleLength = value.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '').length
+    return `${value}${' '.repeat(Math.max(0, terminalWidth() - visibleLength))}`
+  }
+  const render = () => {
+    if (renderedLines > 0) {
+      process.stdout.write(`\x1b[${renderedLines}A`)
+      process.stdout.write('\x1b[0J')
+    }
+    const lines = [
+      title,
+      ...choices.flatMap((choice, index) => {
+        const isSelected = index === selected
+        const marker = isSelected ? '›' : ' '
+        const labelText = `${marker} ${choice.label}`
+        const label = isSelected
+          ? `${ANSI.inverse}${ANSI.bold}${padLine(labelText)}${ANSI.reset}`
+          : `  ${choice.label}`
+        if (!choice.hint) return [label]
+        const hint = isSelected
+          ? `${ANSI.inverse}${padLine(`  ${choice.hint}`)}${ANSI.reset}`
+          : `${ANSI.dim}    ${choice.hint}${ANSI.reset}`
+        return [label, hint]
+      }),
+      '',
+      `${ANSI.dim}Use ↑/↓ to move, Enter to select, Ctrl+C to cancel.${ANSI.reset}`,
+    ]
+    renderedLines = lines.length
+    process.stdout.write(`${lines.join('\n')}\n`)
+  }
+
+  return new Promise((resolvePromise, reject) => {
+    const cleanup = () => {
+      process.stdin.off('keypress', onKeypress)
+      if (process.stdin.setRawMode) process.stdin.setRawMode(Boolean(wasRaw))
+      process.stdout.write('\x1b[?25h')
+    }
+    const onKeypress = (_str, key = {}) => {
+      if (key.ctrl && key.name === 'c') {
+        cleanup()
+        process.stdout.write('\n')
+        reject(new Error('Cancelled.'))
+        return
+      }
+      if (key.name === 'up' || key.name === 'k') {
+        selected = (selected - 1 + choices.length) % choices.length
+        render()
+        return
+      }
+      if (key.name === 'down' || key.name === 'j') {
+        selected = (selected + 1) % choices.length
+        render()
+        return
+      }
+      if (key.name === 'return' || key.name === 'enter') {
+        const choice = choices[selected]
+        cleanup()
+        process.stdout.write('\n')
+        resolvePromise(choice)
+      }
+    }
+
+    process.stdout.write('\x1b[?25l')
+    render()
+    process.stdin.on('keypress', onKeypress)
+  })
+}
+
+function printInteractiveSummary({
+  apiUrl,
+  root,
+  sourceName,
+  site,
+  hasGeneratedBaseline,
+  generatedDiffSummary,
+  hasSourceCheckBaseline,
+  sourceCheckDiffSummary,
+  observedLastJob,
+}) {
+  const activeDiff = generatedDiffSummary || sourceCheckDiffSummary
+  const changed = activeDiff
+    ? activeDiff.added.length + activeDiff.changed.length + activeDiff.removed.length
+    : null
+  console.log('CodeSummary')
+  console.log(`  API: ${apiUrl}`)
+  console.log(`  Workspace: ${root}`)
+  console.log(`  Source: ${sourceName}`)
+  console.log(`  Site: ${site ? `${site.name} (${site.id})` : 'none yet; CodeSummary can create one'}`)
+  if (!hasGeneratedBaseline && observedLastJob?.status === 'pending') {
+    console.log(`  State: generation queued; job ${observedLastJob.id}`)
+  } else if (!hasGeneratedBaseline && observedLastJob?.status === 'processing') {
+    console.log(`  State: generation running; job ${observedLastJob.id}`)
+  } else if (!hasGeneratedBaseline && observedLastJob?.status === 'failed') {
+    console.log(`  State: last generation failed; job ${observedLastJob.id}`)
+    if (observedLastJob.error) console.log(`  Error: ${observedLastJob.error}`)
+  } else if (!hasGeneratedBaseline && !hasSourceCheckBaseline) {
+    console.log('  State: fresh workspace; no previous CodeSummary submit baseline')
+  } else if (!hasGeneratedBaseline) {
+    if (changed === 0) {
+      console.log(`  State: setup checked; knowledge has not been generated yet (${activeDiff.unchanged} files unchanged since setup check)`)
+    } else {
+      console.log(
+        `  State: setup checked, but ${changed} local change${changed === 1 ? '' : 's'} exist before first generation ` +
+        `(${activeDiff.added.length} added, ${activeDiff.changed.length} changed, ${activeDiff.removed.length} removed)`
+      )
+    }
+  } else if (changed === 0) {
+    console.log(`  State: up to date locally; ${generatedDiffSummary.unchanged} files unchanged since last generated knowledge`)
+  } else {
+    console.log(
+      `  State: ${changed} local change${changed === 1 ? '' : 's'} since last generated knowledge ` +
+      `(${generatedDiffSummary.added.length} added, ${generatedDiffSummary.changed.length} changed, ${generatedDiffSummary.removed.length} removed)`
+    )
+  }
+  console.log('')
+}
+
+async function ensureInteractiveAuth(options, root, config) {
+  try {
+    return await resolveAuth(options, config, root)
+  } catch (error) {
+    const choice = await promptChoice(
+      'You are not logged in to CodeSummary for this workspace.',
+      [
+        {
+          label: 'Log in with CodeSummary OAuth',
+          hint: 'Opens the browser and stores a refreshable CLI token.',
+        },
+        { label: 'Exit' },
+      ]
+    )
+    if (choice.label === 'Exit') return null
+    await login(options)
+    return resolveAuth(options, readConfig(root), root)
+  }
+}
+
+async function interactive(options = {}) {
+  const root = resolve(options.root || process.cwd())
+  let config = readConfig(root)
+  const apiUrl = resolveApiUrl(options, config)
+  const auth = await ensureInteractiveAuth(options, root, config)
+  if (!auth) return
+
+  config = auth.config
+  const token = auth.token
+  const sourceName = options.name || config.sourceName || basename(root)
+  let linked = null
+  try {
+    linked = await fetchLinkedSite(apiUrl, token)
+    if (linked?.site && !config.site) {
+      config = { ...config, site: linked.site }
+      writeConfig(config, root)
+    }
+  } catch {
+    linked = null
+  }
+  const site = linked?.site || config.site || null
+  const hasSite = Boolean(site)
+  let observedLastJob = null
+  if (config.lastSubmit?.generated && config.lastSubmit?.jobId) {
+    try {
+      const body = await fetchJobStatus(apiUrl, token, config.lastSubmit.jobId)
+      observedLastJob = body.job || null
+      if (maybePromoteCompletedGenerationBaseline(root, config, body)) {
+        observedLastJob = null
+      }
+    } catch {
+      observedLastJob = null
+    }
+  }
+
+  const baselinePath = join(root, CONFIG_DIR, LAST_SUBMITTED_MANIFEST_FILE)
+  const sourceCheckPath = join(root, CONFIG_DIR, LAST_SOURCE_CHECK_MANIFEST_FILE)
+  const hasGeneratedBaseline = existsSync(baselinePath)
+  const hasSourceCheckBaseline = existsSync(sourceCheckPath)
+  const currentManifest = await writeManifest(root)
+  const generatedDiffSummary = hasGeneratedBaseline
+    ? summarizeManifestDiff(readManifestFile(baselinePath), currentManifest)
+    : null
+  const sourceCheckDiffSummary = !hasGeneratedBaseline && hasSourceCheckBaseline
+    ? summarizeManifestDiff(readManifestFile(sourceCheckPath), currentManifest)
+    : null
+  const activeDiffSummary = generatedDiffSummary || sourceCheckDiffSummary
+  const changed = activeDiffSummary
+    ? activeDiffSummary.added.length + activeDiffSummary.changed.length + activeDiffSummary.removed.length
+    : null
+
+  printInteractiveSummary({
+    apiUrl,
+    root,
+    sourceName,
+    site,
+    hasGeneratedBaseline,
+    generatedDiffSummary,
+    hasSourceCheckBaseline,
+    sourceCheckDiffSummary,
+    observedLastJob,
+  })
+
+  const commonSubmitOptions = {
+    ...options,
+    root,
+    name: sourceName,
+    'api-url': apiUrl,
+  }
+  const runInteractiveSubmit = async (submitOptions) => {
+    const output = await submit({ ...submitOptions, silent: true })
+    printSubmitSummary(output, { generate: submitOptions.generate, apiUrl })
+  }
+
+  let choices
+  if (!hasGeneratedBaseline && (observedLastJob?.status === 'pending' || observedLastJob?.status === 'processing')) {
+    choices = [
+      {
+        label: 'Wait for current generation',
+        hint: 'Follows the job that is already queued or running.',
+        run: () => status({ ...options, root, 'api-url': apiUrl, 'job-id': observedLastJob.id, wait: true }),
+      },
+      {
+        label: 'Check status once',
+        hint: 'Shows the current job state without starting another run.',
+        run: () => status({ ...options, root, 'api-url': apiUrl, 'job-id': observedLastJob.id }),
+      },
+      { label: 'Exit', run: async () => {} },
+    ]
+  } else if (!hasGeneratedBaseline) {
+    choices = [
+      {
+        label: observedLastJob?.status === 'failed'
+          ? 'Retry knowledge generation'
+          : hasSite ? 'Generate first knowledge run' : 'Create a private docs site and generate knowledge',
+        hint: hasSourceCheckBaseline
+          ? 'Uses the checked setup and starts the first hosted generation job.'
+          : 'Uploads this workspace and starts a hosted generation job.',
+        run: () => runInteractiveSubmit({ ...commonSubmitOptions, generate: true }),
+      },
+      {
+        label: hasSite ? 'Advanced: verify setup only' : 'Advanced: create site without generation',
+        hint: 'Checks OAuth, manifest, and source/site linking without retaining source or spending credits.',
+        run: () => runInteractiveSubmit({ ...commonSubmitOptions, generate: false }),
+      },
+      { label: 'Exit', run: async () => {} },
+    ]
+  } else if (changed === 0 && hasSite) {
+    choices = [
+      {
+        label: 'Refresh knowledge anyway',
+        hint: 'Starts a hosted generation job even though the local manifest matches the last submit.',
+        run: () => runInteractiveSubmit({ ...commonSubmitOptions, generate: true }),
+      },
+      {
+        label: 'Advanced: verify setup only',
+        hint: 'Checks the manifest and source/site link without retaining source or spending credits.',
+        run: () => runInteractiveSubmit({ ...commonSubmitOptions, generate: false }),
+      },
+      { label: 'Exit', run: async () => {} },
+    ]
+  } else if (changed === 0) {
+    choices = [
+      {
+        label: 'Create a private docs site and generate knowledge',
+        hint: 'The source manifest matches the last upload, but no site is linked locally.',
+        run: () => runInteractiveSubmit({ ...commonSubmitOptions, generate: true }),
+      },
+      {
+        label: 'Advanced: create site without generation',
+        hint: 'Checks source/site linking without retaining source or spending credits.',
+        run: () => runInteractiveSubmit({ ...commonSubmitOptions, generate: false }),
+      },
+      { label: 'Exit', run: async () => {} },
+    ]
+  } else {
+    choices = [
+      {
+        label: 'Update knowledge',
+        hint: 'Uploads local changes and starts a hosted generation job.',
+        run: () => runInteractiveSubmit({ ...commonSubmitOptions, generate: true }),
+      },
+      {
+        label: 'Advanced: verify setup only',
+        hint: 'Checks the manifest and source/site link without retaining source or spending credits.',
+        run: () => runInteractiveSubmit({ ...commonSubmitOptions, generate: false }),
+      },
+      {
+        label: 'Show detailed diff',
+        hint: 'Prints added, changed, and removed files without uploading.',
+        run: () => diff({ ...options, root }),
+      },
+      { label: 'Exit', run: async () => {} },
+    ]
+  }
+
+  const choice = await promptChoice('What do you want to do?', choices)
+  await choice.run()
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2)
+  if (rawArgs.length === 0) {
+    if (isInteractiveTerminal()) {
+      await interactive({})
+      return
+    }
+    printHelp()
+    return
+  }
+  if (rawArgs[0] === '--help' || rawArgs[0] === '-h' || rawArgs[0] === 'help') {
+    printHelp()
+    return
+  }
+  if (rawArgs[0] === '--version' || rawArgs[0] === '-v' || rawArgs[0] === 'version') {
+    printVersion()
+    return
+  }
+  const command = rawArgs[0] && !rawArgs[0].startsWith('--') ? rawArgs[0] : null
+  const rest = command ? rawArgs.slice(1) : rawArgs
+  const options = parseArgs(rest)
+
+  if (!command) {
+    if (options.help || options.h) {
+      printHelp()
+      return
+    }
+    if (!isInteractiveTerminal()) {
+      printHelp()
+      return
+    }
+    await interactive(options)
+    return
+  }
+
+  if (command === 'new' || command === 'init') {
+    await newWorkspace(options)
+    return
+  }
+
+  if (command === 'configure') {
+    await configure(options)
+    return
+  }
+
+  if (command === 'config') {
+    await configCommand(options)
+    return
+  }
+
+  if (command === 'update') {
+    printUpdateInstructions()
+    return
+  }
+
+  if (command === 'link') {
+    await link(options)
+    return
+  }
+
+  if (command === 'login') {
+    await login(options)
+    return
+  }
+
+  if (command === 'whoami') {
+    await whoami(options)
+    return
+  }
+
+  if (command === 'logout') {
+    await logout(options)
+    return
+  }
+
+  if (command === 'manifest') {
+    const root = resolve(options.root || process.cwd())
+    const manifest = await writeManifest(root)
+    console.log(JSON.stringify({ path: join(root, CONFIG_DIR, MANIFEST_FILE), files: manifest.files.length }, null, 2))
+    return
+  }
+
+  if (command === 'diff') {
+    await diff(options)
+    return
+  }
+
+  if (command === 'export') {
+    await exportBundle(options)
+    return
+  }
+
+  if (command === 'generate') {
+    await generateLocal(options)
+    return
+  }
+
+  if (command === 'submit') {
+    await submit(options)
+    return
+  }
+
+  if (command === 'status') {
+    await status(options)
+    return
+  }
+
+  throw new Error(`Unknown command: ${command}`)
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})