@tastehub/ckb-darwin-arm64 7.0.0 → 7.2.0

package/bin/README.md

@@ -1,5 +1,8 @@
 # CKB — Code Knowledge Backend
 
+[![npm version](https://img.shields.io/npm/v/@tastehub/ckb.svg)](https://www.npmjs.com/package/@tastehub/ckb)
+[![Documentation](https://img.shields.io/badge/docs-wiki-blue.svg)](https://github.com/SimplyLiz/CodeMCP/wiki)
+
 **The missing link between your codebase and AI assistants.**
 
 CKB gives AI assistants deep understanding of your code. Instead of grepping through files, your AI can now *navigate* code like a senior engineer—with knowledge of who owns what, what's risky to change, and how everything connects.
@@ -61,22 +64,39 @@ CKB provides:
 
 ## Quick Start
 
+### Option 1: npm (Recommended)
+
+```bash
+# Install globally
+npm install -g @tastehub/ckb
+
+# Or run directly with npx (no install needed)
+npx @tastehub/ckb init
+```
+
+### Option 2: Build from Source
+
 ```bash
-# 1. Build
 git clone https://github.com/SimplyLiz/CodeMCP.git
 cd CodeMCP
 go build -o ckb ./cmd/ckb
+```
+
+### Setup
 
-# 2. Initialize in your project
+```bash
+# 1. Initialize in your project
 cd /path/to/your/project
-/path/to/ckb init
+ckb init   # or: npx @tastehub/ckb init
 
-# 3. Generate index (Go example)
-go install github.com/sourcegraph/scip-go/cmd/scip-go@latest
-scip-go --repository-root=.
+# 2. Generate SCIP index (optional but recommended)
+ckb index  # auto-detects language and runs appropriate indexer
 
-# 4. Connect to Claude Code
-claude mcp add --transport stdio ckb -- /path/to/ckb mcp
+# 3. Connect to Claude Code
+ckb setup  # creates .mcp.json automatically
+
+# Or manually:
+claude mcp add --transport stdio ckb -- npx @tastehub/ckb mcp
 ```
 
 Now Claude can answer questions like:
@@ -101,9 +121,9 @@ Now Claude can answer questions like:
 
 | Interface | Best For |
 |-----------|----------|
-| **Claude Code (MCP)** | AI-assisted development — Claude queries your codebase directly |
-| **CLI** | Quick lookups from terminal, scripting |
-| **HTTP API** | IDE plugins, CI integration, custom tooling |
+| **[MCP](https://github.com/SimplyLiz/CodeMCP/wiki/MCP-Integration)** | AI-assisted development — Claude, Cursor, Windsurf, VS Code, OpenCode |
+| **[CLI](https://github.com/SimplyLiz/CodeMCP/wiki/User-Guide)** | Quick lookups from terminal, scripting |
+| **[HTTP API](https://github.com/SimplyLiz/CodeMCP/wiki/API-Reference)** | IDE plugins, CI integration, custom tooling |
 
 ## Features
 
@@ -144,6 +164,25 @@ Now Claude can answer questions like:
 - **LLM Export** — Token-efficient codebase summaries with importance ranking
 - **Risk Audit** — 8-factor scoring (complexity, coverage, bus factor, security, staleness, errors, coupling, churn)
 
+### Zero-Friction UX (v7.0)
+- **npm Distribution** — `npm install -g @tastehub/ckb` or `npx @tastehub/ckb`
+- **Auto-Setup** — `ckb setup` configures Claude Code integration automatically
+
+### Zero-Index Operation (v7.1)
+- **Tree-sitter Fallback** — Symbol search works without SCIP index (8 languages)
+- **Auto-Index** — `ckb index` detects language and runs the right SCIP indexer
+- **Install Guidance** — Shows indexer install commands when missing
+- **Universal MCP Docs** — Setup for Claude Code, Cursor, Windsurf, VS Code, OpenCode, Claude Desktop
+
+### Smart Indexing & Explicit Tiers (v7.2)
+- **Skip-if-Fresh** — `ckb index` automatically skips if index is current with HEAD
+- **Freshness Tracking** — Tracks commits behind HEAD + uncommitted changes
+- **Index Status** — `ckb status` shows index freshness with commit hash
+- **Watch Mode** — `ckb mcp --watch` polls every 30s and auto-reindexes when stale
+- **Lock File** — Prevents concurrent indexing with flock-based locking
+- **Explicit Tiers** — Control analysis mode: `--tier=fast|standard|full` or `CKB_TIER` env var
+- **Tier Diagnostics** — `ckb doctor --tier enhanced` shows exactly what's missing and how to fix it
+
 ## MCP Tools (58 Available)
 
 CKB exposes code intelligence through the Model Context Protocol:
@@ -263,6 +302,9 @@ ckb decisions
 # Run diagnostics
 ckb doctor
 
+# Check tier-specific requirements
+ckb doctor --tier enhanced
+
 # Start MCP server for AI assistants
 ckb mcp
 ```
@@ -311,23 +353,25 @@ ckb serve --port 8080
 # Example calls
 curl http://localhost:8080/health
 curl http://localhost:8080/status
-curl http://localhost:8080/search?q=NewServer
+curl "http://localhost:8080/search?q=NewServer"
 curl http://localhost:8080/architecture
 curl "http://localhost:8080/ownership?path=internal/api"
 curl http://localhost:8080/hotspots
 ```
 
-## MCP Server (Claude Code)
+## MCP Integration
 
-```bash
-# Add to current project
-claude mcp add --transport stdio ckb --scope project -- /path/to/ckb mcp
+CKB works with any MCP-compatible AI coding tool.
+
+<details>
+<summary><strong>Claude Code</strong></summary>
 
-# Or add globally
-claude mcp add --transport stdio ckb --scope user -- /path/to/ckb mcp
+```bash
+# Auto-configure for current project
+npx @tastehub/ckb setup
 
-# Verify
-claude mcp list
+# Or add globally for all projects
+npx @tastehub/ckb setup --global
 ```
 
 Or manually add to `.mcp.json`:
@@ -335,13 +379,122 @@ Or manually add to `.mcp.json`:
 {
   "mcpServers": {
     "ckb": {
-      "command": "/path/to/ckb",
-      "args": ["mcp"]
+      "command": "npx",
+      "args": ["@tastehub/ckb", "mcp"]
     }
   }
 }
 ```
 
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+```json
+{
+  "mcpServers": {
+    "ckb": {
+      "command": "npx",
+      "args": ["@tastehub/ckb", "mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "ckb": {
+      "command": "npx",
+      "args": ["@tastehub/ckb", "mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>VS Code</strong></summary>
+
+Add to your VS Code `settings.json`:
+```json
+{
+  "mcp": {
+    "servers": {
+      "ckb": {
+        "type": "stdio",
+        "command": "npx",
+        "args": ["@tastehub/ckb", "mcp"]
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>OpenCode</strong></summary>
+
+Add to `opencode.json` in project root:
+```json
+{
+  "mcp": {
+    "ckb": {
+      "type": "local",
+      "command": ["npx", "@tastehub/ckb", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+```json
+{
+  "mcpServers": {
+    "ckb": {
+      "command": "npx",
+      "args": ["@tastehub/ckb", "mcp"],
+      "cwd": "/path/to/your/repo"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Windows</strong></summary>
+
+Use `cmd /c` wrapper in any config above:
+```json
+{
+  "mcpServers": {
+    "ckb": {
+      "command": "cmd",
+      "args": ["/c", "npx", "@tastehub/ckb", "mcp"]
+    }
+  }
+}
+```
+
+</details>
+
 ## Under the Hood
 
 CKB orchestrates multiple code intelligence backends:
@@ -372,16 +525,28 @@ See the **[Full Documentation Wiki](https://github.com/SimplyLiz/CodeMCP/wiki)**
 
 - [Quick Start](https://github.com/SimplyLiz/CodeMCP/wiki/Quick-Start) — Step-by-step installation
 - [Prompt Cookbook](https://github.com/SimplyLiz/CodeMCP/wiki/Prompt-Cookbook) — Real prompts for real problems
+- [Language Support](https://github.com/SimplyLiz/CodeMCP/wiki/Language-Support) — SCIP indexers and support tiers
 - [Practical Limits](https://github.com/SimplyLiz/CodeMCP/wiki/Practical-Limits) — Accuracy notes, blind spots
 - [User Guide](https://github.com/SimplyLiz/CodeMCP/wiki/User-Guide) — CLI commands and best practices
+- [MCP Integration](https://github.com/SimplyLiz/CodeMCP/wiki/MCP-Integration) — Claude Code setup, 58 tools
 - [API Reference](https://github.com/SimplyLiz/CodeMCP/wiki/API-Reference) — HTTP API documentation
 - [Configuration](https://github.com/SimplyLiz/CodeMCP/wiki/Configuration) — All options including MODULES.toml
+- [Telemetry](https://github.com/SimplyLiz/CodeMCP/wiki/Telemetry) — Runtime observability, dead code detection
+- [Federation](https://github.com/SimplyLiz/CodeMCP/wiki/Federation) — Cross-repository queries
+- [CI/CD Integration](https://github.com/SimplyLiz/CodeMCP/wiki/CI-CD-Integration) — GitHub Actions, PR analysis
 
 ## Requirements
 
+**Using npm (recommended):**
+- Node.js 16+
+- Git
+
+**Building from source:**
 - Go 1.21+
 - Git
-- Optional: gopls (for LSP support), scip-go (for SCIP indexing)
+
+**Optional (for enhanced analysis):**
+- SCIP indexer for your language (scip-go, scip-typescript, etc.) — run `ckb index` to auto-install
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tastehub/ckb-darwin-arm64",
-  "version": "7.0.0",
+  "version": "7.2.0",
   "description": "CKB binary for darwin-arm64",
   "os": ["darwin"],
   "cpu": ["arm64"],