@llmkb/claude-code 0.1.0 → 0.1.1

package/README.md

@@ -3,50 +3,210 @@
 [![npm version](https://img.shields.io/npm/v/@llmkb/claude-code)](https://www.npmjs.com/package/@llmkb/claude-code)
 [![License](https://img.shields.io/npm/l/@llmkb/claude-code)](LICENSE)
 
-Claude Code plugin for **llmkb** — search, read, and write your knowledge base via MCP tools directly from Claude Code.
+**llmkb** (LLM Knowledge Base) is a SaaS AI knowledge platform that transforms raw documents into an organized, interlinked knowledge graph. This plugin connects Claude Code to your llmkb spaces — search, read, and write your knowledge base directly from your editor.
 
-## Install
+> **Prerequisites:** Node.js >= 20, a running llmkb server (local Docker stack or remote deployment).
 
-```bash
-npm install -g @llmkb/claude-code
-```
+---
 
 ## Quick Start
 
 ```bash
-# Initialize llmkb in your project
+# 1. Install the CLI
+npm install -g @llmkb/claude-code
+
+# 2. Scaffold config in your project
+cd my-project
 llmkb init
 
-# Log in to your llmkb server
-llmkb login --space my-space
+# 3. Authenticate with your access token
+llmkb login --project-space <space-uuid>
+
+# 4. Verify everything works
+llmkb doctor
 
-# Sync local files as knowledge sources
+# 5. Sync local files to your llmkb space (optional)
 llmkb sync
+```
 
-# Verify connection
-llmkb doctor
+---
+
+## Commands
+
+### `llmkb init` — Scaffold configuration
+
+Sets up `.claude-plugin/`, `.mcp.json`, `.llmkb/spaces.yml`, and skills in your project. Run this first.
+
+```bash
+llmkb init                                    # Interactive setup — prompts for space config
+llmkb init --platform cursor                  # Generate Cursor rules instead of Claude Code config
+llmkb init --platform claude                  # Generate Claude Code config (default)
+llmkb init --with-skills                      # Install Claude Code skills
+llmkb init --without-skills                   # Skip skill installation
+llmkb init --with-hooks                       # Install Claude Code hooks for context enrichment
+llmkb init --non-interactive                  # Skip prompts (for CI/headless)
+llmkb init /path/to/project                   # Scaffold in a specific directory
+```
+
+### `llmkb login` — Authenticate
+
+Authenticates with a user-level access token, stores it in your OS keychain, discovers accessible spaces, and writes `.llmkb/spaces.yml`.
+
+```bash
+llmkb login --project-space <space-uuid>      # Authenticate and set project space
+```
+
+The CLI will:
+1. Prompt you to paste your access token (generate one from your llmkb dashboard at Settings → Access Tokens)
+2. Validate the token against the server
+3. Store the token in your OS keychain
+4. Discover all spaces you have access to
+5. Write `.llmkb/spaces.yml`
+
+### `llmkb logout` — Remove credentials
+
+```bash
+llmkb logout                                  # Remove access token from keychain
+```
+
+### `llmkb sync` — Sync local files
+
+Uploads local files to your llmkb space as knowledge sources. Uses content-addressed sync — only new and changed files are uploaded.
+
+```bash
+llmkb sync                                    # Sync current directory
+llmkb sync src/                               # Sync a specific directory or file
+llmkb sync --dry-run                          # Preview what would be uploaded
+llmkb sync --force                            # Re-upload everything, bypassing cache
+llmkb sync --watch                            # Watch for file changes and auto-sync
+llmkb sync --debounce 500                     # Watch debounce in milliseconds (default: 300)
+llmkb sync --json                             # Machine-readable JSON output
+llmkb sync --verbose                          # Detailed output including skipped files
+llmkb sync --space <space-uuid>               # Override target space
+```
+
+### `llmkb query` — Search your knowledge base
+
+Searches an llmkb space and prints ranked results from the knowledge graph.
+
+```bash
+llmkb query "your search text"                # Search the project space
+llmkb query "search text" --space <space-id>  # Search a specific space
+llmkb query "search text" --limit 20          # Max results (default: 10)
+llmkb query "search text" --json              # Machine-readable JSON output
+```
+
+### `llmkb doctor` — Diagnose configuration
+
+Run all configuration and permission checks to verify your setup is healthy.
+
+```bash
+llmkb doctor                                  # Run full diagnostic
+```
+
+Checks performed:
+- Config file validity (`.llmkb/config.yml`, `.llmkb/spaces.yml`)
+- Backend server connectivity
+- Access token validity
+- Space access permissions for all configured spaces
+- Related spaces synced from backend
+
+### `llmkb status` — Display current state
+
+Shows version stamps, configuration summary, and access token status.
+
+```bash
+llmkb status
+```
+
+### `llmkb use` — Switch project space
+
+Sets the active project space in `.llmkb/spaces.yml`.
+
+```bash
+llmkb use <space-uuid>                        # Set project space
+```
+
+### `llmkb whoami` — Show current user
+
+Displays the currently authenticated user's identity.
+
+```bash
+llmkb whoami
+```
+
+### `llmkb add` — Register a space
+
+Adds a space to `.llmkb/spaces.yml` without authenticating.
+
+```bash
+llmkb add --space <space-uuid>                # Add a space
+llmkb add --space <uuid> --name "My Space"    # Add with a display name
+```
+
+### `llmkb remove` — Unregister a space
+
+Removes a space from `.llmkb/spaces.yml`.
+
+```bash
+llmkb remove --space <space-uuid>             # Remove a space
 ```
 
-## CLI Commands
+### `llmkb update` — Update project space
+
+Updates the project space configuration in `.llmkb/spaces.yml`.
 
-| Command | Description |
-|---------|-------------|
-| `llmkb init` | Scaffold `.claude-plugin/`, `.mcp.json`, and skills |
-| `llmkb login --space <name>` | Store credentials in OS keychain |
-| `llmkb logout` | Remove stored credentials |
-| `llmkb sync` | Sync local files to llmkb server |
-| `llmkb query "..."` | Query your knowledge base |
-| `llmkb doctor` | Diagnose connection and configuration |
-| `llmkb status` | Show current space status |
-| `llmkb use <space>` | Switch active space |
-| `llmkb add/remove <space>` | Manage space registrations |
-| `llmkb spaces` | List configured spaces |
-| `llmkb hooks` | Manage Claude Code hooks |
+```bash
+llmkb update --project-space <space-uuid>     # Update project space
+```
 
-## MCP Configuration
+### `llmkb spaces` — List configured spaces
+
+Lists all spaces registered in `.llmkb/spaces.yml`.
+
+```bash
+llmkb spaces                                  # List spaces
+llmkb spaces --delete-all                     # Remove all space entries (requires confirmation)
+```
+
+### `llmkb hooks` — Manage Claude Code hooks
+
+Manages hooks that enrich Claude Code context with llmkb data and check sync freshness.
+
+```bash
+llmkb hooks install                           # Install hooks
+llmkb hooks install --force                   # Overwrite existing hook files
+llmkb hooks remove                            # Remove hooks
+llmkb hooks check                             # Check whether hooks are installed
+```
 
-The plugin registers an MCP server so Claude Code can interact with your llmkb spaces. By default it uses Docker stdio transport:
+---
 
+## Environment Variables (Headless / CI)
+
+In environments without a keychain (Linux servers, CI), use environment variables:
+
+| Variable | Purpose |
+|----------|---------|
+| `LLMKB_ENDPOINT` | Server URL (e.g., `https://llmkb.your-server.com`) |
+| `LLMKB_SPACE` | Default space name for operations |
+| `LLMKB_TOKEN` | Space access token |
+| `LLMKB_ADMIN_TOKEN` | Admin token for admin operations |
+
+Example:
+```bash
+export LLMKB_ENDPOINT=https://llmkb.example.com
+export LLMKB_SPACE=my-project
+export LLMKB_TOKEN=llmkb_abc123...
+```
+
+---
+
+## MCP Integration
+
+The plugin registers an MCP server so Claude Code can interact with your llmkb spaces during chat sessions.
+
+**Docker stdio transport** (local development — requires Docker Compose running):
 ```json
 {
   "mcpServers": {
@@ -59,24 +219,48 @@ The plugin registers an MCP server so Claude Code can interact with your llmkb s
 }
 ```
 
-For production deployments, configure HTTP transport targeting your deployed llmkb server.
+**HTTP transport** (remote/production deployment):
+```json
+{
+  "mcpServers": {
+    "llmkb": {
+      "type": "url",
+      "url": "https://llmkb.your-server.com/mcp"
+    }
+  }
+}
+```
 
-## Environment Variables (Headless / CI)
+---
 
-In environments without a keychain (Linux servers, CI), use environment variables:
+## Typical Workflow
 
 ```bash
-export LLMKB_ENDPOINT=https://your-server.llmkb.ai
-export LLMKB_SPACE=my-space
-export LLMKB_TOKEN=your-space-token
-export LLMKB_ADMIN_TOKEN=your-admin-token
+# First-time setup
+cd my-project
+llmkb init
+llmkb login --project-space abc123...
+
+# Daily use
+llmkb sync src/                # Sync code changes
+llmkb query "auth patterns"    # Search knowledge base
+llmkb doctor                   # Check everything is healthy
 ```
 
-## Requirements
+## Configuration Files
+
+After `llmkb init`, the following files are created in your project:
+
+| File | Purpose |
+|------|---------|
+| `.claude-plugin/plugin.json` | Plugin metadata for Claude Code |
+| `.mcp.json` | MCP server registration |
+| `.llmkb/spaces.yml` | Space configuration (without tokens) |
+| `.llmkb/config.yml` | General plugin configuration |
+| `.claude/skills/llmkb/*/SKILL.md` | Claude Code skills (if installed with `--with-skills`) |
+| `.claude/hooks/llmkb/hooks.json` | Claude Code hooks (if installed with `--with-hooks`) |
 
-- **Node.js** >= 20
-- **Docker** (for local MCP stdio transport)
-- **llmkb server** (local Docker stack or remote deployment)
+**Tokens are never stored in config files.** They are stored in your OS keychain, with environment variable fallback for headless environments.
 
 ## License
 

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llmkb/claude-code",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Claude Code plugin for llmkb — search, read, and write your knowledge base via MCP tools",
   "license": "MIT",
   "type": "module",