claude-brain 0.3.1 → 0.3.3

package/README.md

@@ -22,55 +22,82 @@ A locally-running development assistant that bridges Obsidian knowledge vaults w
 - Runs completely locally with zero cloud dependencies
 - Compiles to single portable executable
 
-## Prerequisites
-
-- [Bun](https://bun.sh) >= 1.0.0
-- An Obsidian vault (or any markdown folder)
-
-## Installation
+## Quick Start
 
 ```bash
-# Clone the repository
-git clone <repo-url>
-cd claude-brain
+# Install globally (requires Bun)
+bun install -g claude-brain
 
-# Install dependencies
-bun install
+# Interactive setup (vault path, log level, installs ~/CLAUDE.md)
+claude-brain setup
 
-# Run setup to create directories and validate config
-bun run setup
+# Register with Claude Code
+claude mcp add claude-brain -- bunx claude-brain@latest
 ```
 
-## Configuration
+That's it. Every Claude Code session now has 25 brain tools available.
 
-Copy `.env.example` to `.env` and update with your settings:
+## Zero-Install Alternative
+
+Skip the global install — just register with Claude Code directly:
 
 ```bash
-cp .env.example .env
+claude mcp add claude-brain -- bunx claude-brain@latest
 ```
 
-Required configuration:
-- `VAULT_PATH`: Absolute path to your Obsidian vault
+On first run, `~/.claude-brain/` is auto-created with default config.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0.0
+- An Obsidian vault (or any markdown folder)
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `claude-brain` | Start MCP server (default) |
+| `claude-brain setup` | Interactive setup wizard (run once per machine) |
+| `claude-brain install` | Register as MCP server in Claude Code |
+| `claude-brain health` | Run health checks |
+| `claude-brain diagnose` | Run diagnostics |
+| `claude-brain version` | Show version |
+| `claude-brain help` | Show help |
+
+## Configuration
+
+Configuration lives in `~/.claude-brain/.env`. Created automatically by `claude-brain setup`, or on first run with defaults.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `VAULT_PATH` | Path to your Obsidian vault | `~/.claude-brain/vault` |
+| `LOG_LEVEL` | Log level (debug/info/warn/error) | `info` |
+| `NODE_ENV` | Environment | `production` |
+| `CLAUDE_BRAIN_HOME` | Override home directory | `~/.claude-brain/` |
 
 ## Development
 
 ```bash
-# Start development server with hot reload
+# Clone and install dependencies
+git clone <repo-url>
+cd claude-brain
+bun install
+
+# Start dev server (uses local ./data, ./logs)
 bun run dev
 
 # Run tests
-bun run test
+bun test
 
 # Run tests in watch mode
-bun run test:watch
+bun test --watch
 ```
 
+The `dev` script sets `CLAUDE_BRAIN_HOME=.` so all data stays in the project directory.
+
 ## Building
 
 ```bash
-# Build for production (bundled JS)
-bun run build
-
 # Build standalone executable for current platform
 bun run build:binary
 
@@ -83,7 +110,15 @@ bun run build:all
 ```
 claude-brain/
 ├── src/
-│   ├── index.ts              # Main entry point + orchestrator init
+│   ├── index.ts              # Entry point (thin wrapper)
+│   ├── cli/
+│   │   ├── bin.ts            # CLI entry point (claude-brain command)
+│   │   ├── auto-setup.ts     # First-run home directory initialization
+│   │   └── commands/         # serve, install-mcp
+│   ├── config/
+│   │   ├── home.ts           # ~/.claude-brain/ path resolution
+│   │   ├── loader.ts         # Config loading (defaults → file → env)
+│   │   └── schema.ts         # Zod config schemas
 │   ├── server/               # MCP server code
 │   │   └── handlers/tools/   # 25 tool handlers with Zod validation
 │   ├── vault/                # Obsidian integration
@@ -94,27 +129,24 @@ claude-brain/
 │   ├── knowledge/            # Knowledge graph & entity extraction
 │   │   └── graph/            # In-memory graph with search & auto-population
 │   ├── retrieval/            # Hybrid search (BM25 + semantic + reranking)
-│   │   ├── bm25/             # BM25 keyword search engine
-│   │   ├── fusion/           # RRF/linear/max fusion strategies
-│   │   ├── reranker/         # Cross-encoder neural reranking
-│   │   ├── query/            # Intent classification & query expansion
-│   │   └── feedback/         # Feedback collection & adaptive learning
 │   ├── temporal/             # Timeline construction & trend detection
 │   ├── reasoning/            # Multi-hop chain retrieval & what-if analysis
 │   ├── prediction/           # Decision prediction & recommendations
 │   ├── cross-project/        # Cross-project pattern discovery & transfer
 │   ├── optimization/         # Semantic caching & precomputation
 │   ├── orchestrator/         # Event-driven coordination system
+│   ├── setup/                # Interactive setup wizard
 │   ├── context/              # Context assembly
 │   ├── tools/                # MCP tool definitions & registry
-│   ├── config/               # Configuration management
-│   ├── utils/                # Shared utilities
-│   ├── types/                # TypeScript definitions
-│   └── scripts/              # CLI scripts
-├── data/                     # Local data storage
-├── logs/                     # Log files
+│   └── utils/                # Shared utilities
+├── assets/
+│   └── CLAUDE.md             # Protocol file (shipped with npm package)
 ├── tests/                    # 750+ tests
-└── dist/                     # Build output
+└── ~/.claude-brain/          # User data (created at runtime)
+    ├── .env                  # Configuration
+    ├── data/                 # SQLite + ChromaDB
+    ├── logs/                 # Log files
+    └── vault/                # Default vault location
 ```
 
 ## Architecture Highlights

package/VERSION

@@ -1 +1 @@
-0.3.0
+0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-brain",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Local development assistant bridging Obsidian vaults with Claude Code via MCP",
   "type": "module",
   "main": "src/index.ts",
@@ -57,6 +57,7 @@
     "@chroma-core/default-embed": "0.1.9",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@xenova/transformers": "2.17.2",
+    "chalk": "5.6.2",
     "chromadb": "3.2.2",
     "chromadb-default-embed": "2.14.0",
     "chrono-node": "2.9.0",
@@ -66,6 +67,7 @@
     "hono": "4.11.5",
     "lru-cache": "11.2.5",
     "minisearch": "^6.3.0",
+    "ora": "9.2.0",
     "pino": "^10.1.1",
     "pino-pretty": "^13.1.3",
     "prompts": "2.4.2",

package/src/cli/bin.ts

@@ -3,6 +3,7 @@
 import { readFileSync } from 'node:fs'
 import { resolve, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { renderLogo, theme, dimText, box, errorText } from '@/cli/ui/index.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -19,33 +20,50 @@ function getVersion(): string {
 
 function printHelp() {
   const version = getVersion()
-  console.log(`
-claude-brain v${version} - Local Development Assistant with Memory
-
-Usage: claude-brain [command]
-
-Commands:
-  serve       Start the MCP server (default)
-  setup       Run interactive setup wizard
-  install     Register as MCP server in Claude Code
-  health      Run health checks
-  diagnose    Run diagnostics
-  version     Show version
-  help        Show this help message
-
-Options:
-  -v          Show version
-  -h          Show help
-
-Examples:
-  claude-brain                 Start MCP server
-  claude-brain setup           Configure Claude Brain
-  claude-brain install         Register with Claude Code
-  claude-brain health          Check system health
-
-Environment:
-  CLAUDE_BRAIN_HOME   Override home directory (default: ~/.claude-brain/)
-`)
+
+  console.log()
+  console.log(renderLogo())
+  console.log()
+
+  const commands = [
+    ['serve', 'Start the MCP server (default)'],
+    ['setup', 'Run interactive setup wizard'],
+    ['install', 'Register as MCP server in Claude Code'],
+    ['uninstall', 'Remove MCP server from Claude Code'],
+    ['health', 'Run health checks'],
+    ['diagnose', 'Run diagnostics'],
+    ['version', 'Show version'],
+    ['help', 'Show this help message'],
+  ]
+
+  const cmdLines = commands
+    .map(([cmd, desc]) => `  ${theme.primary(cmd!.padEnd(12))} ${dimText(desc!)}`)
+    .join('\n')
+
+  const content = [
+    `${dimText('v' + version)}  ${dimText('Local Development Assistant with Memory')}`,
+    '',
+    `${theme.bold('Usage:')} ${dimText('claude-brain [command]')}`,
+    '',
+    theme.bold('Commands:'),
+    cmdLines,
+    '',
+    theme.bold('Options:'),
+    `  ${theme.primary('-v'.padEnd(12))} ${dimText('Show version')}`,
+    `  ${theme.primary('-h'.padEnd(12))} ${dimText('Show help')}`,
+    '',
+    theme.bold('Examples:'),
+    `  ${dimText('claude-brain')}                 ${dimText('Start MCP server')}`,
+    `  ${dimText('claude-brain setup')}           ${dimText('Configure Claude Brain')}`,
+    `  ${dimText('claude-brain install')}         ${dimText('Register with Claude Code')}`,
+    `  ${dimText('claude-brain health')}          ${dimText('Check system health')}`,
+    '',
+    theme.bold('Environment:'),
+    `  ${theme.primary('CLAUDE_BRAIN_HOME')}   ${dimText('Override home directory (default: ~/.claude-brain/')}`,
+  ].join('\n')
+
+  console.log(content)
+  console.log()
 }
 
 async function main() {
@@ -70,6 +88,12 @@ async function main() {
       break
     }
 
+    case 'uninstall': {
+      const { runUninstall } = await import('./commands/uninstall-mcp')
+      await runUninstall()
+      break
+    }
+
     case 'health': {
       const { runHealthCheck } = await import('@/health')
       await runHealthCheck()
@@ -97,7 +121,8 @@ async function main() {
     }
 
     default: {
-      console.error(`Unknown command: ${command}\n`)
+      console.log()
+      console.log(errorText(`Unknown command: ${command}`))
       printHelp()
       process.exit(1)
     }
@@ -105,6 +130,7 @@ async function main() {
 }
 
 main().catch((error) => {
-  console.error('Fatal error:', error)
+  console.log()
+  console.log(box(errorText(`Fatal error: ${error instanceof Error ? error.message : String(error)}`), 'Error'))
   process.exit(1)
 })

package/src/cli/commands/install-mcp.ts

@@ -1,4 +1,8 @@
 import { execSync } from 'node:child_process'
+import {
+  renderLogo, theme, heading, successText, warningText, errorText, dimText,
+  box, withSpinner,
+} from '@/cli/ui/index.js'
 
 function isGloballyInstalled(): boolean {
   const cmd = process.platform === 'win32' ? 'where claude-brain' : 'which claude-brain'
@@ -11,41 +15,59 @@ function isGloballyInstalled(): boolean {
 }
 
 export async function runInstall() {
-  console.log('\nClaude Brain - MCP Installation\n')
+  console.log()
+  console.log(renderLogo())
+  console.log()
+  console.log(heading('MCP Installation'))
+  console.log()
 
-  if (isGloballyInstalled()) {
-    console.log('claude-brain is globally installed. Registering with Claude Code...\n')
+  const installed = isGloballyInstalled()
+
+  if (installed) {
+    console.log(successText('claude-brain is globally installed'))
+    console.log()
 
     try {
-      execSync('claude mcp add claude-brain -- claude-brain serve', {
-        encoding: 'utf-8',
-        stdio: 'inherit'
+      await withSpinner('Registering with Claude Code', async () => {
+        execSync('claude mcp add claude-brain -- claude-brain serve', {
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe']
+        })
       })
-      console.log('\nClaude Brain registered as MCP server in Claude Code.')
-    } catch (error) {
-      console.error('\nFailed to register automatically. Run manually:')
-      console.log('\n  claude mcp add claude-brain -- claude-brain serve\n')
+      console.log()
+      console.log(box(successText('Claude Brain registered as MCP server in Claude Code.'), 'Success'))
+    } catch {
+      console.log()
+      console.log(box([
+        errorText('Failed to register automatically.'),
+        '',
+        dimText('Run manually:'),
+        `  ${theme.bold('claude mcp add claude-brain -- claude-brain serve')}`,
+      ].join('\n'), 'Error'))
     }
   } else {
-    console.log('claude-brain is not globally installed.')
-    console.log('You can either install globally or use bunx.\n')
-
-    console.log('Option 1: Install globally, then register:')
-    console.log('  bun install -g claude-brain')
-    console.log('  claude mcp add claude-brain -- claude-brain serve\n')
-
-    console.log('Option 2: Use bunx (zero-install):')
-    console.log('  claude mcp add claude-brain -- bunx claude-brain@latest\n')
+    console.log(warningText('claude-brain is not globally installed'))
+    console.log()
 
-    console.log('Option 3: Add to Claude Code config manually:')
-    console.log(`  {
-    "mcpServers": {
-      "claude-brain": {
-        "command": "bunx",
-        "args": ["claude-brain@latest"]
-      }
-    }
-  }
-`)
+    console.log(box([
+      `${theme.primary('Option 1:')} Install globally, then register`,
+      `  ${theme.bold('bun install -g claude-brain')}`,
+      `  ${theme.bold('claude mcp add claude-brain -- claude-brain serve')}`,
+      '',
+      `${theme.primary('Option 2:')} Use bunx ${dimText('(zero-install)')}`,
+      `  ${theme.bold('claude mcp add claude-brain -- bunx claude-brain@latest')}`,
+      '',
+      `${theme.primary('Option 3:')} Add to Claude Code config manually`,
+      dimText('  Add to your Claude Code MCP settings:'),
+      `  ${theme.dim('{')}`,
+      `    ${theme.dim('"mcpServers": {')}`,
+      `      ${theme.dim('"claude-brain": {')}`,
+      `        ${theme.dim('"command": "bunx",')}`,
+      `        ${theme.dim('"args": ["claude-brain@latest"]')}`,
+      `      ${theme.dim('}')}`,
+      `    ${theme.dim('}')}`,
+      `  ${theme.dim('}')}`,
+    ].join('\n'), 'Install Options'))
   }
+  console.log()
 }

package/src/cli/commands/uninstall-mcp.ts

@@ -0,0 +1,41 @@
+import { execSync } from 'node:child_process'
+import {
+  renderLogo, theme, heading, successText, errorText, dimText,
+  box, withSpinner,
+} from '@/cli/ui/index.js'
+
+export async function runUninstall() {
+  console.log()
+  console.log(renderLogo())
+  console.log()
+  console.log(heading('MCP Uninstall'))
+  console.log()
+
+  try {
+    await withSpinner('Removing Claude Brain from Claude Code', async () => {
+      try {
+        execSync('claude mcp remove claude-brain', {
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        })
+      } catch {
+        // Falls back to scoped removal when registered in multiple scopes
+        execSync('claude mcp remove claude-brain -s local', {
+          encoding: 'utf-8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        })
+      }
+    })
+    console.log()
+    console.log(box(successText('Claude Brain MCP server removed from Claude Code.'), 'Success'))
+  } catch {
+    console.log()
+    console.log(box([
+      errorText('Failed to remove automatically.'),
+      '',
+      dimText('Run manually:'),
+      `  ${theme.bold('claude mcp remove claude-brain')}`,
+    ].join('\n'), 'Error'))
+  }
+  console.log()
+}

package/src/cli/ui/animations.ts

@@ -0,0 +1,80 @@
+import ora from 'ora'
+import { theme } from './theme.js'
+
+const isTTY = process.stdout.isTTY === true
+
+// Async delay utility
+export function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+// Character-by-character text output with configurable speed
+export async function typewrite(text: string, speed = 30): Promise<void> {
+  if (!isTTY) {
+    process.stdout.write(text + '\n')
+    return
+  }
+  for (const char of text) {
+    process.stdout.write(char)
+    await delay(speed)
+  }
+  process.stdout.write('\n')
+}
+
+// Wraps async operations with ora spinner, auto succeed/fail
+export async function withSpinner<T>(label: string, fn: () => Promise<T>): Promise<T> {
+  if (!isTTY) {
+    process.stdout.write(`${label}...`)
+    try {
+      const result = await fn()
+      process.stdout.write(' done\n')
+      return result
+    } catch (error) {
+      process.stdout.write(' failed\n')
+      throw error
+    }
+  }
+
+  const spinner = ora({
+    text: label,
+    color: 'magenta',
+  }).start()
+
+  try {
+    const result = await fn()
+    spinner.succeed(theme.success(label))
+    return result
+  } catch (error) {
+    spinner.fail(theme.error(label))
+    throw error
+  }
+}
+
+// Pause between sections for visual breathing room
+export async function transition(ms = 300): Promise<void> {
+  if (!isTTY) return
+  await delay(ms)
+}
+
+// Progress bar that fills over time
+export async function animateProgress(label: string, durationMs = 1000, width = 30): Promise<void> {
+  if (!isTTY) {
+    console.log(`${label}... done`)
+    return
+  }
+
+  const steps = 20
+  const stepDelay = durationMs / steps
+
+  for (let i = 0; i <= steps; i++) {
+    const percent = Math.round((i / steps) * 100)
+    const filled = Math.round((percent / 100) * width)
+    const empty = width - filled
+    const bar = theme.primary('='.repeat(Math.max(0, filled - 1)) + (filled > 0 ? '>' : '')) +
+      ' '.repeat(empty)
+    const pct = theme.dim(`${percent}%`)
+    process.stdout.write(`\r  ${label} [${bar}] ${pct}`)
+    await delay(stepDelay)
+  }
+  process.stdout.write('\n')
+}

package/src/cli/ui/components.ts

@@ -0,0 +1,82 @@
+import { theme, dimText, heading } from './theme.js'
+
+const BOX_WIDTH = 60
+
+// Unicode box-drawing panel with optional title
+export function box(content: string, title?: string): string {
+  const innerWidth = BOX_WIDTH - 2
+  const lines = content.split('\n')
+
+  let top: string
+  if (title) {
+    const titleText = ` ${title} `
+    const remaining = innerWidth - titleText.length - 1
+    top = theme.secondary('╭─') + theme.primary.bold(titleText) + theme.secondary('─'.repeat(Math.max(0, remaining)) + '╮')
+  } else {
+    top = theme.secondary('╭' + '─'.repeat(innerWidth) + '╮')
+  }
+
+  const bottom = theme.secondary('╰' + '─'.repeat(innerWidth) + '╯')
+
+  const body = lines.map(line => {
+    // Strip ANSI codes to calculate visible length
+    const visible = stripAnsi(line)
+    const padding = Math.max(0, innerWidth - visible.length)
+    return theme.secondary('│') + ' ' + line + ' '.repeat(padding - 1) + theme.secondary('│')
+  })
+
+  return [top, ...body, bottom].join('\n')
+}
+
+// Step indicator: [Step 2/5]  Configuring Vault
+export function stepIndicator(current: number, total: number, label: string): string {
+  const badge = theme.secondary(`[Step ${current}/${total}]`)
+  const text = heading(label)
+  return `\n${badge}  ${text}\n`
+}
+
+// Progress bar: [========>          ] 40%
+export function progressBar(percent: number, width = 30): string {
+  const filled = Math.round((percent / 100) * width)
+  const empty = width - filled
+  const bar = theme.primary('='.repeat(Math.max(0, filled - 1)) + (filled > 0 ? '>' : '')) +
+    dimText(' '.repeat(empty))
+  const pct = theme.dim(`${Math.round(percent)}%`)
+  return `[${bar}] ${pct}`
+}
+
+// Info panel: key-value list in a box
+export function infoPanel(title: string, items: Record<string, string>): string {
+  const lines = Object.entries(items).map(([key, value]) => {
+    return `${theme.dim(key + ':')}  ${theme.white(value)}`
+  })
+  return box(lines.join('\n'), title)
+}
+
+// Styled horizontal divider
+export function divider(): string {
+  return theme.secondary('─'.repeat(BOX_WIDTH))
+}
+
+// Summary panel with status icons
+export function summaryPanel(title: string, items: Array<{ label: string; value: string; status?: 'success' | 'warning' | 'error' | 'info' }>): string {
+  const statusIcons: Record<string, string> = {
+    success: theme.success('+'),
+    warning: theme.warning('!'),
+    error: theme.error('x'),
+    info: theme.primary('*'),
+  }
+
+  const lines = items.map(item => {
+    const icon = item.status ? statusIcons[item.status] ?? ' ' : ' '
+    return `  ${icon} ${theme.dim(item.label + ':')}  ${theme.white(item.value)}`
+  })
+
+  return box(lines.join('\n'), title)
+}
+
+// Strip ANSI escape codes for length calculation
+function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\u001B\[[0-9;]*m/g, '')
+}

package/src/cli/ui/index.ts

@@ -0,0 +1,4 @@
+export * from './theme.js'
+export * from './components.js'
+export * from './logo.js'
+export * from './animations.js'

package/src/cli/ui/logo.ts

@@ -0,0 +1,36 @@
+import chalk from 'chalk'
+import { box } from './components.js'
+import { dimText } from './theme.js'
+
+// 5-shade gradient from light purple to dark violet
+const gradientColors = [
+  '#A78BFA', // light purple
+  '#8B5CF6', // medium purple
+  '#7C3AED', // deep purple (primary)
+  '#6D28D9', // dark purple
+  '#5B21B6', // dark violet (secondary)
+]
+
+const logoLines = [
+  '  ██████╗ ██████╗  █████╗ ██╗███╗   ██╗ ',
+  '  ██╔══██╗██╔══██╗██╔══██╗██║████╗  ██║ ',
+  '  ██████╔╝██████╔╝███████║██║██╔██╗ ██║ ',
+  '  ██╔══██╗██╔══██╗██╔══██║██║██║╚██╗██║ ',
+  '  ██████╔╝██║  ██║██║  ██║██║██║ ╚████║ ',
+  '  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝ ',
+]
+
+export function renderLogo(): string {
+  return logoLines
+    .map((line, i) => chalk.hex(gradientColors[i] ?? gradientColors[gradientColors.length - 1]!)(line))
+    .join('\n')
+}
+
+export function renderBanner(version: string): string {
+  const logo = renderLogo()
+  const tagline = dimText('  Local Development Assistant with Memory')
+  const ver = dimText(`  v${version}`)
+
+  const content = [logo, '', tagline, ver].join('\n')
+  return box(content, 'Claude Brain')
+}

package/src/cli/ui/theme.ts

@@ -0,0 +1,55 @@
+import chalk from 'chalk'
+
+// Color palette
+export const colors = {
+  deepPurple: '#7C3AED',
+  darkViolet: '#5B21B6',
+  charcoal: '#1A1A1A',
+  nearBlack: '#0A0A0A',
+  darkRed: '#B91C1C',
+  green: '#22C55E',
+  amber: '#F59E0B',
+  white: '#FFFFFF',
+  gray: '#6B7280',
+} as const
+
+// Pre-built chalk instances
+export const theme = {
+  primary: chalk.hex(colors.deepPurple),
+  secondary: chalk.hex(colors.darkViolet),
+  error: chalk.hex(colors.darkRed),
+  success: chalk.hex(colors.green),
+  warning: chalk.hex(colors.amber),
+  dim: chalk.hex(colors.gray),
+  bold: chalk.bold,
+  white: chalk.white,
+}
+
+// Styled text helpers
+export function heading(text: string): string {
+  return theme.primary.bold(text)
+}
+
+export function successText(text: string): string {
+  return theme.success(`  ${text}`)
+}
+
+export function errorText(text: string): string {
+  return theme.error(`  ${text}`)
+}
+
+export function warningText(text: string): string {
+  return theme.warning(`  ${text}`)
+}
+
+export function dimText(text: string): string {
+  return theme.dim(text)
+}
+
+export function highlight(text: string): string {
+  return theme.primary(text)
+}
+
+export function keyValue(key: string, value: string): string {
+  return `${theme.dim(key + ':')} ${theme.white(value)}`
+}

package/src/setup/index.ts

@@ -2,12 +2,37 @@ import { createLogger } from '@/utils/logger'
 import { resolveHomePath } from '@/config/home'
 import { ensureHomeDirectory } from '@/cli/auto-setup'
 import { SetupWizard } from './wizard'
+import { renderBanner, typewrite, transition, box, errorText, theme } from '@/cli/ui/index.js'
+import { readFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 export * from './wizard'
 
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PACKAGE_ROOT = resolve(__dirname, '..', '..')
+
+function getVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(PACKAGE_ROOT, 'package.json'), 'utf-8'))
+    return pkg.version || 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
 export async function runSetup() {
   ensureHomeDirectory()
 
+  const version = getVersion()
+  console.log()
+  console.log(renderBanner(version))
+  console.log()
+
+  await typewrite(theme.dim('Welcome! Let\'s configure Claude Brain for your system.'))
+  await transition(400)
+
   const logger = createLogger('info', resolveHomePath('./logs/setup.log'))
 
   try {
@@ -16,7 +41,8 @@ export async function runSetup() {
     await wizard.applyConfiguration(answers)
 
   } catch (error) {
-    console.error('\nSetup failed:', error)
+    console.log()
+    console.log(box(errorText(`Setup failed: ${error instanceof Error ? error.message : String(error)}`), 'Error'))
     process.exit(1)
   }
 }

package/src/setup/wizard.ts

@@ -6,6 +6,11 @@ import os from 'os'
 import { fileURLToPath } from 'url'
 import type { Logger } from 'pino'
 import { getHomePaths } from '@/config/home'
+import {
+  theme, heading, successText, errorText, warningText, dimText,
+  box, stepIndicator, summaryPanel,
+  withSpinner, transition,
+} from '@/cli/ui/index.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -28,12 +33,26 @@ export class SetupWizard {
   }
 
   async run(): Promise<SetupAnswers> {
-    console.log('\nClaude Brain - Setup Wizard\n')
-    console.log('Welcome! Let\'s configure Claude Brain for your system.\n')
+    // Step 1: Detect Vaults
+    console.log(stepIndicator(1, 5, 'Detecting Obsidian Vaults'))
+    await transition()
+
+    const suggestedPaths = await withSpinner('Scanning for Obsidian vaults', () =>
+      this.detectVaultLocations()
+    )
+
+    if (suggestedPaths.length > 0) {
+      console.log(successText(`Found ${suggestedPaths.length} vault${suggestedPaths.length > 1 ? 's' : ''}`))
+    } else {
+      console.log(warningText('No vaults auto-detected — enter path manually'))
+    }
+    console.log()
 
-    const suggestedPaths = await this.detectVaultLocations()
+    // Step 2: Vault Configuration
+    console.log(stepIndicator(2, 5, 'Vault Configuration'))
+    await transition()
 
-    const answers = await prompts([
+    const vaultAnswers = await prompts([
       {
         type: 'select',
         name: 'vaultPathChoice',
@@ -57,18 +76,37 @@ export class SetupWizard {
           }
         }
       },
-      {
-        type: 'select',
-        name: 'logLevel',
-        message: 'Select log level:',
-        choices: [
-          { title: 'Error (production)', value: 'error' },
-          { title: 'Warn (recommended)', value: 'warn' },
-          { title: 'Info', value: 'info' },
-          { title: 'Debug (verbose)', value: 'debug' }
-        ],
-        initial: 1
-      },
+    ])
+
+    if (!vaultAnswers.vaultPathChoice) {
+      console.log('\n' + errorText('Setup cancelled.'))
+      process.exit(0)
+    }
+
+    const finalVaultPath = vaultAnswers.vaultPath || vaultAnswers.vaultPathChoice
+
+    // Step 3: Logging
+    console.log(stepIndicator(3, 5, 'Logging Configuration'))
+    await transition()
+
+    const loggingAnswers = await prompts({
+      type: 'select',
+      name: 'logLevel',
+      message: 'Select log level:',
+      choices: [
+        { title: 'Error (production)', value: 'error' },
+        { title: 'Warn (recommended)', value: 'warn' },
+        { title: 'Info', value: 'info' },
+        { title: 'Debug (verbose)', value: 'debug' }
+      ],
+      initial: 1
+    })
+
+    // Step 4: Features
+    console.log(stepIndicator(4, 5, 'Feature Selection'))
+    await transition()
+
+    const featureAnswers = await prompts([
       {
         type: 'confirm',
         name: 'enableFileWatch',
@@ -89,20 +127,40 @@ export class SetupWizard {
       }
     ])
 
-    if (!answers.vaultPathChoice) {
-      console.log('\n Setup cancelled.')
-      process.exit(0)
-    }
-
-    const finalVaultPath = answers.vaultPath || answers.vaultPathChoice
+    // Step 5: Review
+    console.log(stepIndicator(5, 5, 'Review Configuration'))
+    await transition()
 
-    return {
+    const answers: SetupAnswers = {
       vaultPath: finalVaultPath,
-      logLevel: answers.logLevel,
-      enableFileWatch: answers.enableFileWatch,
-      createSampleProject: answers.createSampleProject,
-      installClaudeMd: answers.installClaudeMd ?? true
+      logLevel: loggingAnswers.logLevel ?? 'warn',
+      enableFileWatch: featureAnswers.enableFileWatch ?? true,
+      createSampleProject: featureAnswers.createSampleProject ?? true,
+      installClaudeMd: featureAnswers.installClaudeMd ?? true,
     }
+
+    console.log(summaryPanel('Configuration Summary', [
+      { label: 'Vault Path', value: answers.vaultPath, status: 'success' },
+      { label: 'Log Level', value: answers.logLevel, status: 'info' },
+      { label: 'File Watching', value: answers.enableFileWatch ? 'Enabled' : 'Disabled', status: answers.enableFileWatch ? 'success' : 'warning' },
+      { label: 'Sample Project', value: answers.createSampleProject ? 'Yes' : 'No', status: 'info' },
+      { label: 'Install CLAUDE.md', value: answers.installClaudeMd ? 'Yes' : 'No', status: 'info' },
+    ]))
+    console.log()
+
+    const { confirm } = await prompts({
+      type: 'confirm',
+      name: 'confirm',
+      message: 'Apply this configuration?',
+      initial: true
+    })
+
+    if (!confirm) {
+      console.log('\n' + errorText('Setup cancelled.'))
+      process.exit(0)
+    }
+
+    return answers
   }
 
   private async detectVaultLocations(): Promise<string[]> {
@@ -134,7 +192,7 @@ export class SetupWizard {
   }
 
   async applyConfiguration(answers: SetupAnswers): Promise<void> {
-    console.log('\nApplying configuration...\n')
+    console.log('\n' + heading('Applying configuration...') + '\n')
 
     const homePaths = getHomePaths()
 
@@ -147,34 +205,48 @@ LOG_FILE_PATH=./logs/claude-brain.log
 SERVER_NAME=claude-brain
 `
 
-    await fs.writeFile(homePaths.env, envContent, 'utf-8')
-    console.log('Created .env configuration file')
+    await withSpinner('Writing .env configuration', async () => {
+      await fs.writeFile(homePaths.env, envContent, 'utf-8')
+    })
 
-    await fs.mkdir(homePaths.data, { recursive: true })
-    await fs.mkdir(homePaths.logs, { recursive: true })
-    console.log('Created data and log directories')
+    await withSpinner('Creating data and log directories', async () => {
+      await fs.mkdir(homePaths.data, { recursive: true })
+      await fs.mkdir(homePaths.logs, { recursive: true })
+    })
 
     if (answers.createSampleProject) {
-      await this.createSampleProject(answers.vaultPath)
+      await withSpinner('Creating sample project in vault', async () => {
+        await this.createSampleProject(answers.vaultPath)
+      })
     }
 
     if (answers.installClaudeMd) {
-      await this.installClaudeMd()
+      const shouldInstall = await this.confirmClaudeMdInstall()
+      if (shouldInstall) {
+        await withSpinner('Installing CLAUDE.md', async () => {
+          await this.copyClaudeMd()
+        })
+      }
     }
 
-    console.log('\nSetup complete!')
-    console.log('\nNext steps:')
-    console.log('1. Run: claude-brain install   (register MCP with Claude Code)')
-    console.log('2. Run: claude-brain health     (verify everything works)')
+    console.log()
+    console.log(box([
+      heading('Setup complete!'),
+      '',
+      dimText('Next steps:'),
+      `  ${theme.primary('1.')} Run: ${theme.bold('claude-brain install')}   ${dimText('Register MCP with Claude Code')}`,
+      `  ${theme.primary('2.')} Run: ${theme.bold('claude-brain health')}    ${dimText('Verify everything works')}`,
+    ].join('\n'), 'Done'))
+    console.log()
   }
 
-  private async installClaudeMd(): Promise<void> {
+  private async confirmClaudeMdInstall(): Promise<boolean> {
     const sourcePath = path.join(PACKAGE_ROOT, 'assets', 'CLAUDE.md')
     const destPath = path.join(os.homedir(), 'CLAUDE.md')
 
     if (!existsSync(sourcePath)) {
-      console.log('CLAUDE.md asset not found, skipping')
-      return
+      console.log(warningText('CLAUDE.md asset not found, skipping'))
+      return false
     }
 
     if (existsSync(destPath)) {
@@ -182,31 +254,31 @@ SERVER_NAME=claude-brain
         type: 'confirm',
         name: 'overwrite',
         message: '~/CLAUDE.md already exists. Overwrite?',
-        initial: false
+        initial: false,
       })
       if (!overwrite) {
-        console.log('Skipped CLAUDE.md installation')
-        return
+        console.log(dimText('  Skipped CLAUDE.md installation'))
+        return false
       }
     }
 
-    try {
-      await fs.copyFile(sourcePath, destPath)
-      console.log('Installed CLAUDE.md to ~/CLAUDE.md')
-    } catch (error) {
-      console.error('Failed to install CLAUDE.md:', error)
-    }
+    return true
+  }
+
+  private async copyClaudeMd(): Promise<void> {
+    const sourcePath = path.join(PACKAGE_ROOT, 'assets', 'CLAUDE.md')
+    const destPath = path.join(os.homedir(), 'CLAUDE.md')
+    await fs.copyFile(sourcePath, destPath)
   }
 
   private async createSampleProject(vaultPath: string): Promise<void> {
     const projectPath = path.join(vaultPath, 'Projects', 'sample-project')
 
-    try {
-      await fs.mkdir(projectPath, { recursive: true })
+    await fs.mkdir(projectPath, { recursive: true })
 
-      await fs.writeFile(
-        path.join(projectPath, 'context.md'),
-        `---
+    await fs.writeFile(
+      path.join(projectPath, 'context.md'),
+      `---
 type: project-context
 project: sample-project
 status: active
@@ -233,12 +305,12 @@ This is a sample project created by Claude Brain setup wizard.
 - Test Claude Brain integration
 - Learn the workflow
 `,
-        'utf-8'
-      )
+      'utf-8'
+    )
 
-      await fs.writeFile(
-        path.join(projectPath, 'progress.md'),
-        `---
+    await fs.writeFile(
+      path.join(projectPath, 'progress.md'),
+      `---
 type: progress-tracker
 project: sample-project
 status: in-progress
@@ -253,12 +325,12 @@ completion_percentage: 0
 - [ ] Test MCP integration
 - [ ] Try all tools
 `,
-        'utf-8'
-      )
+      'utf-8'
+    )
 
-      await fs.writeFile(
-        path.join(projectPath, 'decisions.md'),
-        `---
+    await fs.writeFile(
+      path.join(projectPath, 'decisions.md'),
+      `---
 type: decision-log
 project: sample-project
 decision_count: 0
@@ -268,12 +340,12 @@ decision_count: 0
 
 This file will track important decisions for the project.
 `,
-        'utf-8'
-      )
+      'utf-8'
+    )
 
-      await fs.writeFile(
-        path.join(projectPath, 'standards.md'),
-        `---
+    await fs.writeFile(
+      path.join(projectPath, 'standards.md'),
+      `---
 type: coding-standards
 project: sample-project
 ---
@@ -284,19 +356,19 @@ project: sample-project
 - Use strict mode
 - Prefer const over let
 `,
-        'utf-8'
-      )
+      'utf-8'
+    )
 
-      const globalPath = path.join(vaultPath, 'Global')
-      await fs.mkdir(globalPath, { recursive: true })
+    const globalPath = path.join(vaultPath, 'Global')
+    await fs.mkdir(globalPath, { recursive: true })
 
-      const globalStandardsPath = path.join(globalPath, 'standards.md')
-      try {
-        await fs.access(globalStandardsPath)
-      } catch {
-        await fs.writeFile(
-          globalStandardsPath,
-          `---
+    const globalStandardsPath = path.join(globalPath, 'standards.md')
+    try {
+      await fs.access(globalStandardsPath)
+    } catch {
+      await fs.writeFile(
+        globalStandardsPath,
+        `---
 type: global-standards
 last_updated: ${new Date().toISOString().split('T')[0]}
 ---
@@ -308,14 +380,8 @@ last_updated: ${new Date().toISOString().split('T')[0]}
 - Prefer const over let
 - Add JSDoc comments for public APIs
 `,
-          'utf-8'
-        )
-      }
-
-      console.log('Created sample project in vault')
-
-    } catch (error) {
-      console.error('Failed to create sample project:', error)
+        'utf-8'
+      )
     }
   }
 }