### Getting Started with ck: New Users

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/choosing-interface.md

This path is for new ck users, recommending starting with the TUI for interactive exploration, then moving to the CLI for scripting, and finally the editor extension.

```bash
# Launch interactive interface
ck-tui

# Experiment with queries
# Learn what works

# Add CLI for scripts
ck --sem "pattern" . -l > files.txt

# Install editor extension when comfortable
# code --install-extension ck-search
```

--------------------------------

### Discover Application Entry Point with ck

Source: https://github.com/beaconbay/ck/blob/main/docs-site/recipes/explore-codebase.md

Find the application's starting point, such as main functions or server setup code. Limits results to 5.

```bash
ck --sem "application entry point main function" . --limit 5
```

--------------------------------

### Cross-Platform Testing Setup

Source: https://github.com/beaconbay/ck/blob/main/docs-site/contributing/development.md

Instructions to install 'cross' and run tests on different target platforms. This ensures your code functions correctly across various operating systems and architectures.

```bash
# Install cross
cargo install cross

# Test on different platforms
cross test --target x86_64-unknown-linux-gnu
cross test --target x86_64-pc-windows-gnu
cross test --target aarch64-apple-darwin
```

--------------------------------

### Test installation from GitHub release

Source: https://github.com/beaconbay/ck/blob/main/docs/npm-distribution.md

Manually run the install script and test the binary. This is useful for debugging the installation process without publishing.

```bash
# Clear any previous dist
rm -rf dist/

# Run install script manually
node scripts/install.js

# Test the binary
node cli/ck.js --version
```

--------------------------------

### MCP Server Setup

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/ai-agent-setup.md

Instructions for starting the ck MCP server and configuring it in Claude Desktop. The MCP server enables integration with MCP-compatible AI agents.

```bash
# Start MCP server
ck --serve

# Configure in Claude Desktop
claude mcp add ck-search -s user -- ck --serve
```

--------------------------------

### Benchmark Setup with Criterion

Source: https://github.com/beaconbay/ck/blob/main/docs-site/contributing/testing.md

Set up performance benchmarks using the Criterion crate, typically located in the `benches/` directory. This example shows how to benchmark the `semantic_search` function.

```rust
use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn benchmark_search(c: &mut Criterion) {
    c.bench_function("semantic_search", |b| {
        b.iter(|| semantic_search(black_box("pattern"), black_box(path)))
    });
}

criterion_group!(benches, benchmark_search);
criterion_main!(benches);

```

```bash
cargo bench
```

--------------------------------

### Install ck Extension for Cursor

Source: https://github.com/beaconbay/ck/blob/main/ck-vscode/README.md

Navigate to the extension directory and run the install script. Restart Cursor after installation.

```bash
cd ck-vscode
./install-cursor.sh
```

--------------------------------

### Partial Directory Indexing Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/limitations.md

Demonstrates an attempt to index a subdirectory which fails. Indexing always starts from the repository root.

```bash
ck --index ./docs  # Still indexes from repository root
```

--------------------------------

### Install ck Binary

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/editor-integration.md

Install the ck binary using cargo. Verify the installation by checking the version.

```bash
cargo install ck-search
ck --version
```

--------------------------------

### Install ck from source

Source: https://github.com/beaconbay/ck/blob/main/docs-site/index.md

Install ck by cloning the repository and building from source using Cargo. This method is useful for development or if you need the latest unreleased changes.

```bash
git clone https://github.com/BeaconBay/ck
cd ck
cargo install --path ck-cli
```

--------------------------------

### Complete Example Session: Get Complete Code Sections

Source: https://github.com/beaconbay/ck/blob/main/docs-site/public/AGENTS.md

Retrieves entire code sections related to 'retry logic' using semantic search. This is useful for understanding the full context of a pattern.

```bash
ck --sem --full-section "retry logic" src/
```

--------------------------------

### Claude Desktop AI Agent Setup

Source: https://github.com/beaconbay/ck/blob/main/README.md

Install the ck-search tool for Claude Desktop using the Claude Code CLI. Restart Claude Code after installation.

```bash
claude mcp add ck-search -s user -- ck --serve
```

--------------------------------

### Example .ckignore for Go

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/configuration.md

A sample .ckignore file for Go projects, excluding vendor directories and build output.

```txt
# .ckignore for Go projects
vendor/
*.mod
*.sum
bin/
```

--------------------------------

### Example .ckignore File Content

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/basic-usage.md

This is an example of a .ckignore file, demonstrating various patterns for excluding images, media, configuration files, build artifacts, and custom patterns.

```txt
# Images and media
*.png
*.jpg
*.mp4
*.mp3

# Config files
*.json
*.yaml

# Build artifacts
target/
dist/
build/
node_modules/

# Custom patterns
temp/
*.bak
```

--------------------------------

### Install and Run ck

Source: https://github.com/beaconbay/ck/blob/main/README.md

Install ck from crates.io and perform basic semantic, keyword, and hybrid searches.

```bash
cargo install ck-search
```

```bash
ck --sem "error handling" src/
ck --sem "authentication logic" src/
ck --sem "database connection pooling" src/
```

```bash
ck -n "TODO" *.rs
ck -R "TODO|FIXME" .
```

```bash
ck --hybrid "connection timeout" src/
```

--------------------------------

### Install ck Binary

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/editor-integration.md

Install the ck-search binary using cargo if it's missing from your system.

```bash
cargo install ck-search
```

--------------------------------

### Migration Path: From grep/ripgrep to ck CLI

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/choosing-interface.md

This guide helps users transition from grep or ripgrep to the ck CLI, starting with familiar syntax and gradually incorporating semantic search capabilities.

```bash
# Familiar grep syntax
ck "pattern" src/

# Add semantic search when needed
ck --sem "concept" src/

# Graduate to TUI for exploration
ck-tui
```

--------------------------------

### Build and Test Project

Source: https://github.com/beaconbay/ck/blob/main/README.md

Clone the repository, build the entire workspace, and run the test suite. This is a common setup for new contributors.

```bash
git clone https://github.com/BeaconBay/ck
cd ck
cargo build --workspace
cargo test --workspace
```

--------------------------------

### Install Dependencies and Compile

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/editor-integration.md

Install project dependencies using npm and compile the TypeScript code.

```bash
# Install dependencies
npm install

# Compile TypeScript
npm run compile
```

--------------------------------

### Command Mode Examples

Source: https://github.com/beaconbay/ck/blob/main/TUI.md

Examples of commands to use in the TUI's command mode, accessed by typing '/'.

```bash
/open <filename>    - Open specific file
/config             - Show current configuration
/help               - Show help message
```

--------------------------------

### Indexing Progress Example

Source: https://github.com/beaconbay/ck/blob/main/TUI.md

An example of the detailed progress tracking displayed by the TUI during repository indexing.

```bash
Indexing repository for semantic search...
src/main.rs • 23/145 files • 5/12 chunks
[████████████░░░░░░░░] 67%
```

--------------------------------

### Example .ckignore File

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/ai-agent-setup.md

An example `.ckignore` file to optimize indexing for AI-assisted development by excluding build artifacts, dependencies, media files, and other non-code assets.

```ignore
# .ckignore

# Build artifacts (not useful for understanding code)
target/
dist/
build/
*.o
*.so
*.dylib

# Dependencies (too large, low signal)
node_modules/
vendor/
virtualenv/
.venv/

# Media files (not code)
*.png
*.jpg
*.gif
*.mp4
*.pdf

# Large data files
*.csv
*.json
*.xml
*.log

# Test fixtures (unless you search them)
fixtures/
__snapshots__/
*.snap

# Generated code (if not relevant)
*_pb2.py
*.generated.*

# Documentation (include if you want AI to reference docs)
# docs/
# *.md
```

--------------------------------

### Install ck from crates.io

Source: https://github.com/beaconbay/ck/blob/main/docs-site/index.md

Install the ck search tool globally using Cargo from crates.io. This is an alternative installation method for Rust projects.

```bash
cargo install ck-search
```

--------------------------------

### Install ck Extension for VS Code

Source: https://github.com/beaconbay/ck/blob/main/ck-vscode/README.md

Navigate to the extension directory, install dependencies, compile the extension, and then install it into VS Code. A restart of VS Code might be necessary.

```bash
cd ck-vscode
npm install
npm run compile
code --install-extension . --force
```

--------------------------------

### Troubleshooting: Verify Tool Installation

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/mcp-integration.md

Verify that the ck-search tool is correctly installed and registered with the MCP.

```bash
# Verify installation
claude mcp list | grep ck
```

--------------------------------

### Install MCP Server in Claude Desktop

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/mcp-integration.md

Instructions for installing the ck MCP server in Claude Desktop, both recommended (CLI) and manual methods.

```APIDOC
## Install MCP Server in Claude Desktop

### Description
Provides instructions for integrating the ck MCP server with Claude Desktop.

### Method
CLI Command / Manual Configuration

### Endpoint
N/A

### Parameters
None

### Request Example
**Using Claude Code CLI (Recommended):**
```bash
claude mcp add ck-search -s user -- ck --serve

# Restart Claude Code if needed
# Verify with:
claude mcp list
```

**Manual Configuration:**
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or equivalent and add the following:

```json
{
  "mcpServers": {
    "ck": {
      "command": "ck",
      "args": ["--serve"],
      "cwd": "/path/to/your/codebase"
    }
  }
}
```

### Response
N/A

### Tool Permissions
Approve permissions for ck-search tools when prompted by Claude Code.
```

--------------------------------

### Documentation: Finding Usage Examples and API Patterns

Source: https://github.com/beaconbay/ck/blob/main/examples/README.md

Leverages semantic search to locate examples of code usage and identify common API patterns such as REST APIs.

```bash
# Find examples of usage
ck --sem "example usage" examples/
```

```bash
# Locate API patterns
ck --sem "rest api" examples/
```

--------------------------------

### Install pnpm and Project Dependencies

Source: https://github.com/beaconbay/ck/blob/main/docs-site/README.md

Installs pnpm globally if not already present, then installs project dependencies using pnpm.

```bash
# Install pnpm if you haven't already
npm install -g pnpm

# Install dependencies
pnpm install
```

--------------------------------

### Install and Run CK Search

Source: https://github.com/beaconbay/ck/blob/main/README.md

Install the CK search tool using cargo and run a basic search query.

```bash
cargo install ck-search
```

```bash
ck --sem "the code you're looking for"
```

--------------------------------

### Install ck from NPM

Source: https://github.com/beaconbay/ck/blob/main/docs-site/index.md

Install the ck search tool globally using NPM. This command makes the `ck` and `ck-tui` executables available on your system.

```bash
npm install -g @beaconbay/ck-search
```

--------------------------------

### Install ck Extension

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/editor-integration.md

Install the compiled ck extension into VS Code.

```bash
code --install-extension . --force
```

--------------------------------

### Start Local Development Server

Source: https://github.com/beaconbay/ck/blob/main/docs-site/README.md

Starts the local development server with hot reload enabled for the VitePress site.

```bash
pnpm dev
```

--------------------------------

### Standard Output Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/installation.md

Example of the standard output format when searching for a keyword, showing the filename, line number, and the matching line of code.

```bash
$ ck "error" src/main.rs
src/main.rs:42:    let result = risky_operation().map_err(|e| {
src/main.rs:43:        eprintln!("Error: {}", e);
```

--------------------------------

### Example .ckignore for Rust

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/configuration.md

A sample .ckignore file for Rust projects, excluding the build output directory and common configuration files.

```txt
# .ckignore for Rust projects
target/
Cargo.lock
*.json
*.toml
*.log
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/beaconbay/ck/blob/main/benchmarks/swe-bench/README.md

Installs the necessary Python packages for the SWE-bench benchmark. Navigate to the 'benchmarks/swe-bench' directory before running.

```bash
cd benchmarks/swe-bench
pip install -r requirements.txt
```

--------------------------------

### Start Indexing with Default Settings

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/models.md

Begin with the default indexing behavior. Use the `--sem` flag to index based on a specific pattern.

```bash
ck --index .
ck --sem "pattern" src/
```

--------------------------------

### Example .ckignore for Python

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/configuration.md

A sample .ckignore file for Python projects, excluding virtual environments, compiled files, and build artifacts.

```txt
# .ckignore for Python projects
__pycache__/
*.pyc
virtualenv/
.venv/
dist/
build/
*.egg-info/
.pytest_cache/
```

--------------------------------

### Troubleshooting: Check ck Installation

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/mcp-integration.md

Verify if the ck command-line tool is installed and accessible in your system's PATH.

```bash
# Check if ck is installed
which ck
```

--------------------------------

### Verify Publication and Test Installation

Source: https://github.com/beaconbay/ck/blob/main/docs-site/contributing/release-process.md

Check the published crates on crates.io and test the installation of the CLI tool.

```bash
# Check crates.io
open https://crates.io/crates/ck-search

# Test installation
cargo install ck-search --force
ck --version
```

--------------------------------

### Fixture Setup for Tests

Source: https://github.com/beaconbay/ck/blob/main/docs-site/contributing/testing.md

Use fixtures for complex test setups, such as creating a temporary index directory. The `setup_test_index` function demonstrates creating and indexing a temporary directory.

```rust
fn setup_test_index() -> TempDir {
    let dir = TempDir::new().unwrap();
    // Create test index
    index_directory(dir.path()).unwrap();
    dir
}

#[test]
fn test_with_fixture() {
    let temp_dir = setup_test_index();
    // Test using temp_dir
}
```

--------------------------------

### Rust Code Block Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/README.md

Demonstrates a basic Rust 'Hello, world!' program within a code block.

```rust
fn main() {
    println!(“Hello, world!”);
}
```

--------------------------------

### Example .ckignore for JavaScript/Node.js

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/configuration.md

A sample .ckignore file tailored for JavaScript and Node.js projects, excluding common build artifacts and dependency directories.

```txt
# .ckignore for JavaScript/Node.js projects
node_modules/
dist/
build/
*.json
*.yaml
*.log
.next/
.nuxt/
coverage/
```

--------------------------------

### Example Login Function

Source: https://github.com/beaconbay/ck/blob/main/docs-site/recipes/find-auth.md

An example of a Rust login function that verifies credentials and creates a session token. Ensure your project has similar structures for authentication.

```rust
pub async fn login(credentials: Credentials) -> Result<Token> {
    let user = verify_credentials(&credentials).await?;
    create_session_token(&user)
}
```

--------------------------------

### Start Interactive TUI

Source: https://github.com/beaconbay/ck/blob/main/README.md

Launch the interactive Terminal User Interface for ck. You can start with an initial query.

```bash
ck --tui
```

```bash
ck --tui "error handling"
```

--------------------------------

### Install CK Editor Extension

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/installation.md

Install the CK search extension for VSCode/Cursor to enable in-editor search functionality. Refer to documentation for detailed setup.

```bash
# Install extension (see docs for details)
code --install-extension ck-search
```

```bash
# Then use:
# - Cmd+Shift+; to open search
# - Cmd+Shift+' to search selection
```

--------------------------------

### Start MCP Server

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/mcp-integration.md

Command to start the ck MCP server. The server listens on stdio and communicates via JSON-RPC 2.0.

```APIDOC
## Start MCP Server

### Description
Starts the ck MCP server, which listens on stdio and communicates via JSON-RPC 2.0.

### Method
CLI Command

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
ck --serve
```

### Response
N/A
```

--------------------------------

### Test local package build

Source: https://github.com/beaconbay/ck/blob/main/docs/npm-distribution.md

Before publishing, test the package locally by packing it, installing it globally, and verifying its version. Remember to uninstall it afterwards.

```bash
# Build and test the package locally
npm pack
npm install -g beaconbay-ck-search-0.7.0.tgz
ck --version
npm uninstall -g @beaconbay/ck-search
```

--------------------------------

### Clone and Build ck

Source: https://github.com/beaconbay/ck/blob/main/docs-site/contributing/development.md

Clone the repository, navigate to the directory, and build the workspace. Ensure Rust 1.89+ is installed.

```bash
git clone https://github.com/BeaconBay/ck
cd ck
cargo build --workspace
cargo test --workspace
```

--------------------------------

### Keyword Search Examples

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/grep-compatibility.md

Use keyword search for exact string matches, variable/function names, file paths, configuration values, and log analysis.

```bash
ck "TODO" src/                  # Find exact TODO markers
```

```bash
ck "fn main" src/               # Find main functions
```

```bash
ck "import.*React" src/         # Find React imports
```

--------------------------------

### Start CK MCP Server for AI Agents

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/installation.md

Start the MCP server to integrate with AI tools like Claude Desktop. Configure the server within your chosen AI tool.

```bash
# Start MCP server
ck --serve
```

```bash
# Then configure in Claude Desktop
```

--------------------------------

### Verify Clipboard Tools (Linux)

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/tui-mode.md

Ensure 'xclip' or 'xsel' is installed on Linux for clipboard functionality. Use 'sudo apt install xclip' if needed.

```bash
# Install xclip or xsel
sudo apt install xclip
# Verify installation
which xclip
```

--------------------------------

### Create Test Project Files

Source: https://github.com/beaconbay/ck/blob/main/EXAMPLES.md

Sets up a demo project with sample code files in Rust, Python, and JavaScript for testing ck's features.

```bash
mkdir ck-demo && cd ck-demo

# Create sample files
cat > auth.rs << EOF
use std::collections::HashMap;

pub struct AuthService {
    users: HashMap<String, User>,
}

impl AuthService {
    pub fn authenticate(&self, username: &str, password: &str) -> Result<Token, AuthError> {
        match self.users.get(username) {
            Some(user) if user.verify_password(password) => {
                Ok(Token::new(user.id))
            }
            _ => Err(AuthError::InvalidCredentials)
        }
    }

    pub fn handle_login_error(&self, error: AuthError) {
        log::error!("Authentication failed: {:?}", error);
    }
}
EOF

cat > database.py << EOF
import sqlite3
from typing import Optional

class DatabaseConnection:
    def __init__(self, db_path: str):
        self.connection = sqlite3.connect(db_path)
        
    def authenticate_user(self, username: str, password_hash: str) -> Optional[dict]:
        cursor = self.connection.cursor()
        try:
            cursor.execute(
                "SELECT id, username FROM users WHERE username = ? AND password_hash = ?",
                (username, password_hash)
            )
            return cursor.fetchone()
        except Exception as e:
            print(f"Database error: {e}")
            return None
            
    def handle_connection_error(self, error):
        log.error(f"Database connection failed: {error}")
EOF

cat > server.js << EOF
const express = require('express');
const bcrypt = require('bcrypt');

class AuthController {
    async login(req, res) {
        try {
            const { username, password } = req.body;
            const user = await this.findUser(username);
            
            if (!user || !bcrypt.compare(password, user.password)) {
                return res.status(401).json({ error: 'Authentication failed' });
            }
            
            const token = this.generateToken(user);
            res.json({ token });
        } catch (error) {
            this.handleError(error, res);
        }
    }
    
    handleError(error, res) {
        console.error('Login error:', error);
        res.status(500).json({ error: 'Internal server error' });
    }
}
EOF

cat > README.md << EOF
# Authentication Service

A multi-language authentication system with:

- Rust backend service
- Python database layer  
- JavaScript API endpoints

## Error Handling

All components implement proper error handling for authentication failures.
EOF
```

--------------------------------

### Keyword Search Examples

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/cli.md

Demonstrates basic keyword searching, including case-insensitive and whole-word matching. Use these for direct text matching within files.

```bash
ck "pattern" [paths]
```

```bash
ck -i "case-insensitive" src/
```

```bash
ck -w "whole-word" src/
```

```bash
# Keyword search
ck "TODO" src/
```

```bash
# Case-insensitive
ck -i "error" src/
```

```bash
# With line numbers
ck -n "pattern" file.txt
```

--------------------------------

### ck CLI Exclusion Examples

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/configuration.md

Demonstrates how to use command-line flags to control which exclusion layers are active and to add custom exclusions.

```bash
# All layers active (default)
ck --sem "pattern" .

# Skip .gitignore only
ck --no-ignore --sem "pattern" .

# Skip .ckignore only
ck --no-ckignore --sem "pattern" .

# Skip both ignore files
ck --no-ignore --no-ckignore --sem "pattern" .

# Add CLI exclusions
ck --exclude "temp/" --sem "pattern" .

# Multiple CLI exclusions
ck --exclude "*.test.js" --exclude "fixtures/" --sem "pattern" .
```

--------------------------------

### TUI Interface Layout Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/tui-mode.md

An example of the TUI interface layout, illustrating the search box, results pane, and preview pane with their respective elements and indicators.

```text
┌─────────────────────────────────────────────────────┐
│ Search: error handling              [Semantic] [●] │  ← Search box with mode indicator
├─────────────────────────────────────────────────────┤
│ Results (234)                                       │
│ ● src/lib.rs:45 (0.92)                            │  ← Results list with:
│   src/error.rs:12 (0.88)                          │    - Selection indicator
│   src/handler.rs:89 (0.85)                        │    - File path and line number
│   tests/error_test.rs:23 (0.82)                   │    - Relevance score (semantic)
│   docs/errors.md:5 (0.79)                         │
├─────────────────────────────────────────────────────┤
│ Preview: src/lib.rs:45-60              [Chunks]    │  ← Preview pane with:
│                                                     │    - File location
│ ┌─ function handle_error • 45 tokens ─┐           │    - Preview mode indicator
│ │                                      │           │    - Syntax highlighting
│ │  pub fn handle_error(e: Error) -> Result<()> {  │    - Code structure
│ │      match e {
│ │          Error::Io(err) => {...}
│ │          Error::Parse(err) => {...}
│ │      }
│ │  }
│ └──────────────────────────────────────┘           │
└─────────────────────────────────────────────────────┘
```

--------------------------------

### Performance Profiling with Flamegraph

Source: https://github.com/beaconbay/ck/blob/main/docs-site/contributing/development.md

Build the release version, install `flamegraph`, and use it to profile the application's performance. The output can help identify performance bottlenecks.

```bash
# Build with profiling
cargo build --release

# Profile with flamegraph
cargo install flamegraph
cargo flamegraph -- --index large_project/

# Profile with perf
perf record --call-graph dwarf ./target/release/ck --index .
perf report
```

--------------------------------

### Broad Semantic Search for Authentication

Source: https://github.com/beaconbay/ck/blob/main/docs-site/recipes/find-auth.md

Start with a broad semantic search for 'authentication' to get an initial overview of relevant code. Adjust the threshold for more precise or inclusive results.

```bash
# 1. Broad semantic search
ck --sem "authentication" . --limit 20 --threshold 0.6
```

--------------------------------

### Switching .ckignore Files and Indexing

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/advanced.md

Demonstrates how to switch between development and production .ckignore files and then re-index the project using the 'ck' command.

```bash
# Development
cp .ckignore.dev .ckignore && ck --index .

# Production
cp .ckignore.prod .ckignore && ck --index .
```

--------------------------------

### Preview Production Build

Source: https://github.com/beaconbay/ck/blob/main/docs-site/README.md

Builds the documentation site for production and then previews the build locally.

```bash
pnpm build
pnpm preview
```

--------------------------------

### Build Documentation Site

Source: https://github.com/beaconbay/ck/blob/main/docs-site/README.md

Builds the documentation site for production. Output will be placed in the .vitepress/dist directory.

```bash
pnpm build
```

--------------------------------

### Configure .ckignore File Syntax

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/configuration.md

Uses gitignore-style patterns to control which files are excluded from indexing. Comments start with '#'.

```txt
# .ckignore syntax
# Comments start with #

# Exclude directories
node_modules/
target/
dist/
.git/

# Exclude file patterns
*.log
*.tmp
*.bak

# Exclude specific files
.env
config/secrets.yaml

# Negation (include despite parent exclusion)
!.important.log

# Wildcards
temp_*.txt
**/*.test.js
```

--------------------------------

### Minimal Test Data Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/contributing/testing.md

Create small, focused test files to ensure tests run quickly and efficiently. This example shows a minimal Rust file for testing purposes.

```rust
// test_files/rust/minimal.rs
fn simple_function() {
    println!("test");
}
```

--------------------------------

### Hybrid Search Example Queries

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/tui-mode.md

Use these example queries to understand how Hybrid Search combines keyword filtering with semantic relevance ranking. Results must contain the keyword and are ranked by semantic relevance.

```bash
"timeout"                  → Finds: Code with "timeout" keyword, ranked by relevance
```

```bash
"connect"                  → Finds: Code with "connect", prioritizes connection logic
```

```bash
"parse"                    → Finds: Code with "parse", ranks parsing functions higher
```

--------------------------------

### Secrets Management Examples

Source: https://github.com/beaconbay/ck/blob/main/docs-site/recipes/security-review.md

Demonstrates the insecure practice of hardcoding secrets and the secure practice of loading them from environment variables.

```javascript
// Hardcoded secrets (never do this!)
const API_KEY = "sk_live_abc123xyz";
const DB_PASSWORD = "SuperSecret123!";

// Good: from environment
const API_KEY = process.env.API_KEY;
```

--------------------------------

### Codebase Onboarding Workflows

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/ai-agent-setup.md

Common commands for helping AI agents understand new projects, including indexing, finding entry points, understanding architecture, and mapping components.

```bash
# Index the project
ck --index .

# Find entry points
ck --sem "main entry point" .
ck --sem "application initialization" .

# Understand architecture
ck --sem "dependency injection" src/
ck --sem "data flow" src/

# Map out key components
ck --sem "authentication" .
ck --sem "database queries" .
ck --sem "API endpoints" .
```

--------------------------------

### Python Example: Get Default .ckignore Patterns

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/mcp-integration.md

Retrieve the default .ckignore patterns used by ck. This is useful for editor extensions or tools needing to understand ck's exclusion rules.

```python
patterns = await client.call_tool("default_ckignore", {})
# Returns multi-line string with default patterns:
# *.png
# *.jpg
# node_modules/
# ...
```

--------------------------------

### Direct Replacement of grep with ck

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/grep-compatibility.md

Demonstrates how to directly replace grep with ck using shell aliases or by modifying scripts. The provided example shows a direct alias setup and a script modification suggestion.

```bash
# In shell aliases
alias grep='ck'

# In scripts
#!/bin/bash
# sed 's/grep/ck/g' old_script.sh > new_script.sh

# No changes needed - works immediately
ck -rn "TODO" src/
```

--------------------------------

### JSON Output with Top K Results

Source: https://github.com/beaconbay/ck/blob/main/EXAMPLES.md

Retrieve a specified number of top results in JSON format using the `--topk` flag. This example gets the top 3 lexical search results.

```bash
ck --json --topk 3 --lex "user login" .
```

--------------------------------

### Real-World Example: Rust Web Service Exploration

Source: https://github.com/beaconbay/ck/blob/main/docs-site/recipes/explore-codebase.md

A sequence of commands to explore a Rust web service, covering entry point, core models, API routes, database layer, and authentication.

```bash
# 1. Entry point
ck --sem "main function server startup" . --limit 3
```

```bash
# 2. Core models
ck --sem "user model struct" . --limit 5
```

```bash
# 3. API routes
ck --sem "http routes endpoints" . --limit 10
```

```bash
# 4. Database layer
ck --sem "database queries repository" . --limit 10
```

```bash
# 5. Authentication
ck --sem "authentication jwt token validation" . --limit 5
```

--------------------------------

### Run Quick Demo Script

Source: https://github.com/beaconbay/ck/blob/main/examples/README.md

Executes a quick demonstration script to showcase ck's functionality. Ensure the script is executable.

```bash
./examples/quick_demo.sh
```

--------------------------------

### Build and Open Documentation

Source: https://github.com/beaconbay/ck/blob/main/docs-site/contributing/development.md

Commands to build the documentation for the entire workspace and open it in a browser. '--no-deps' skips dependency documentation.

```bash
# Build documentation
cargo doc --workspace --no-deps

# Open in browser
cargo doc --workspace --no-deps --open
```

--------------------------------

### Real-World ck Usage Examples

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/ai-agent-setup.md

Demonstrates practical ck commands for indexing, semantic search, and refining results with thresholds and limits. Useful for understanding common workflows.

```bash
# Initial setup
ck --index .

# Semantic search for concepts
ck --sem "error handling" src/
ck --sem "database connection pooling" lib/

# High-confidence matches only
ck --sem --threshold 0.8 "authentication logic" src/

# Limited result set
ck --sem --limit 10 "caching strategy" .
```

--------------------------------

### Developer Workflow: Combining ck Interfaces

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/choosing-interface.md

This example illustrates a typical developer workflow using different ck interfaces throughout the day, from initial exploration with TUI to in-editor search and scripting.

```bash
# Morning: Explore codebase with TUI
ck-tui
# Search: "new features from last sprint"

# During coding: Use editor extension
# Cmd+Shift+; → search as you code

# Scripting: Use CLI for automation
ck --sem "TODO" . -l > todos.txt

# AI assistance: Use MCP via Claude Desktop
# "Explain the architecture of this module"
```

--------------------------------

### Run ck CLI with Index

Source: https://github.com/beaconbay/ck/blob/main/README.md

Execute the ck command-line interface to index a specified directory. This command is used for initial setup or re-indexing.

```bash
./target/debug/ck --index test_files/
```

--------------------------------

### Install ck via cargo

Source: https://github.com/beaconbay/ck/blob/main/docs/npm-distribution.md

Rust developers can install ck directly using Cargo, the Rust package manager. This installs the same binary but through a different distribution channel.

```bash
# Via cargo (Rust developers)
car go install ck-search
```

--------------------------------

### TUI Query Refinement Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/choosing-interface.md

Demonstrates refining search queries interactively within the TUI. Allows for iterative discovery and precise targeting.

```bash
ck-tui
# Start broad: "auth"
# Refine: "authentication flow"
# Switch to hybrid: Ctrl+H
# Adjust threshold: increase for precision
```

--------------------------------

### Run ck from Source

Source: https://github.com/beaconbay/ck/blob/main/docs-site/contributing/development.md

Build and run the ck CLI with a specified semantic pattern and test files, or execute the binary directly.

```bash
# Build and run
cargo run --package ck-cli -- --sem "pattern" test_files/

# Or use the binary directly
./target/debug/ck --sem "pattern" test_files/
```

--------------------------------

### Build ck Extension for Development

Source: https://github.com/beaconbay/ck/blob/main/ck-vscode/README.md

Install npm dependencies and compile the extension code. This is typically done during development to prepare the extension for testing or packaging.

```bash
cd ck-vscode
npm install
npm run compile
```

--------------------------------

### Markdown Table Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/README.md

Provides an example of a simple markdown table with a header and one row of data.

```markdown
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
```

--------------------------------

### Understand Architecture with ck

Source: https://github.com/beaconbay/ck/blob/main/docs-site/recipes/explore-codebase.md

Search for common architectural patterns like dependency injection or the repository pattern. Limits results to 10.

```bash
ck --sem "dependency injection service layer" . --limit 10
```

--------------------------------

### Codebase Onboarding Commands

Source: https://github.com/beaconbay/ck/blob/main/docs-site/public/AGENTS.md

Commands to help onboard a new codebase by indexing and searching for key entry points and concepts.

```bash
ck --index .
```

```bash
ck --sem "main entry point" .
```

```bash
ck --sem "application initialization" .
```

```bash
ck --sem "authentication" .
```

```bash
ck --sem "database queries" .
```

--------------------------------

### Custom Container Examples

Source: https://github.com/beaconbay/ck/blob/main/docs-site/README.md

Shows examples of custom containers in VitePress markdown for tips, warnings, and danger notices.

```markdown
::: tip
This is a tip
:::

::: warning
This is a warning
:::

::: danger
This is a danger notice
:::
```

--------------------------------

### Code Group Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/README.md

Illustrates how VitePress supports code groups, showing placeholders for Rust and Python examples.

```markdown
// Rust example

# Python example
```

--------------------------------

### Install Tarpaulin for Coverage Analysis

Source: https://github.com/beaconbay/ck/blob/main/docs-site/contributing/testing.md

Install the Tarpaulin tool globally using Cargo to enable code coverage analysis.

```bash
cargo install cargo-tarpaulin
```

--------------------------------

### Install Dependencies for ck VS Code Extension

Source: https://github.com/beaconbay/ck/blob/main/ck-vscode/GETTING_STARTED.md

Run this command in the `ck-vscode` directory to install necessary Node.js dependencies.

```bash
cd ck-vscode
npm install
```

--------------------------------

### CORS Configuration Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/recipes/security-review.md

Shows an example of an insecurely permissive CORS configuration using `origin: '*'` and a more secure configuration specifying a particular origin.

```javascript
// Too permissive!
app.use(cors({ origin: '*' }));

// Better: specific origins
app.use(cors({ origin: 'https://yourapp.com' }));
```

--------------------------------

### Example Authorization Middleware

Source: https://github.com/beaconbay/ck/blob/main/docs-site/recipes/find-auth.md

An example of a TypeScript middleware function that checks if a user has the 'admin' role. This demonstrates how authorization can be implemented in request handling.

```typescript
export function requireAdmin(req: Request, res: Response, next: Next) {
  if (!req.user?.roles.includes('admin')) {
    return res.status(403).json({ error: 'Forbidden' });
  }
  next();
}
```

--------------------------------

### Complete Example Session: Structured Output for Search

Source: https://github.com/beaconbay/ck/blob/main/docs-site/public/AGENTS.md

Executes a semantic search and outputs the results in JSON Lines (jsonl) format for easy parsing. Includes threshold and limit options.

```bash
ck --jsonl --sem --threshold 0.7 --limit 20 "authentication" src/
```

--------------------------------

### Package Manager Installation Status

Source: https://github.com/beaconbay/ck/blob/main/README.md

Information on current and upcoming package manager installations for ck-search. Cargo is currently available, while Homebrew and APT are in development.

```bash
# Currently available:
cargo install ck-search    # ✅ Available now via crates.io

# Coming soon:
brew install ck-search     # 🚧 In development (use cargo for now)
apt install ck-search      # 🚧 In development
```

--------------------------------

### Editor: Install ck VSCode/Cursor extension

Source: https://github.com/beaconbay/ck/blob/main/docs-site/index.md

Install the ck search extension for VSCode or Cursor. Access search functionality via a keyboard shortcut.

```bash
code --install-extension ck-search
```

--------------------------------

### Package ck VS Code Extension for Distribution

Source: https://github.com/beaconbay/ck/blob/main/ck-vscode/GETTING_STARTED.md

Installs the `vsce` tool globally and then packages the extension into a `.vsix` file for local installation or distribution.

```bash
# Install vsce if not already installed
npm install -g @vscode/vsce

# Package the extension
npm run package
```

--------------------------------

### Faster Indexing with .ckignore and Model Selection

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/configuration.md

Demonstrates how to optimize indexing speed by excluding large directories first, using a smaller embedding model, and specifying paths to index.

```bash
# Exclude large directories first
echo "node_modules/" > .ckignore
echo "target/" >> .ckignore

# Use smaller model
ck --index --model bge-small .

# Index specific paths
ck --index src/ lib/
```

--------------------------------

### Index Small Projects with BGE-Small

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/models.md

For small projects, use the BGE-Small model for fast indexing and sufficient understanding.

```bash
ck --index --model bge-small .
# Fast, sufficient for small codebases
```

--------------------------------

### Install Packaged VSIX Extension Locally

Source: https://github.com/beaconbay/ck/blob/main/ck-vscode/GETTING_STARTED.md

Command to install a locally packaged VS Code extension file (`.vsix`) using the VS Code CLI.

```bash
code --install-extension ck-search-0.1.0.vsix
```

--------------------------------

### Build CK Binary

Source: https://github.com/beaconbay/ck/blob/main/benchmarks/swe-bench/README.md

Compiles the CK (Code Knowledge) tool from source. Ensure you are in the repository root directory.

```bash
cargo build --release
```

--------------------------------

### Find Configuration Settings with ck

Source: https://github.com/beaconbay/ck/blob/main/docs-site/recipes/explore-codebase.md

Locate how the application is configured, including environment variables and config file loading. Limits results to 5.

```bash
ck --sem "configuration settings environment variables" . --limit 5
```

--------------------------------

### Understand Architecture

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/semantic-search.md

Use semantic search to find code related to architectural concepts like dependency injection.

```bash
# Understand architecture
ck --sem "dependency injection" src/
```

--------------------------------

### Check ck NPM package updates

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/installation.md

Commands to check the current installed version, identify available updates, and upgrade the ck search package installed via NPM.

```bash
# Check current version
npm list -g @beaconbay/ck-search

# Check if updates are available
npm outdated -g @beaconbay/ck-search

# Upgrade to the latest version
npm update -g @beaconbay/ck-search
```

--------------------------------

### Complete Example Session: Semantic Search for Authentication

Source: https://github.com/beaconbay/ck/blob/main/docs-site/public/AGENTS.md

Performs a semantic search for 'authentication' within the 'src/' directory, using a confidence threshold of 0.7 and limiting results to 20.

```bash
ck --sem --threshold 0.7 --limit 20 "authentication" src/
```

--------------------------------

### Semantic Search Examples

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/tui-mode.md

Examples of semantic search queries to find code by meaning and concept. Useful for discovering similar patterns across different implementations or exploring unfamiliar code.

```bash
"error handling"          → Finds: try/catch, Result<>, match arms, panic!
```

```bash
"database connection pool" → Finds: connection management code
```

```bash
"retry mechanism"          → Finds: backoff, retry loops, circuit breakers
```

```bash
"authentication logic"     → Finds: login, auth middleware, token validation
```

--------------------------------

### Indexing Supported Languages First in Mixed Repos

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/advanced.md

In mixed-language repositories, first index supported languages by adding their file extensions to .ckignore, then use keyword search for unsupported languages.

```bash
# Index supported languages first
echo "*.java" >> .ckignore
echo "*.php" >> .ckignore
ck --index .

# Use keyword search for unsupported
ck "pattern" **/*.java
```

--------------------------------

### Regex Search Examples

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/tui-mode.md

Examples of regex search queries for exact text pattern matching. Useful for finding specific syntax, identifiers, or markers like TODOs. No indexing is required, making it suitable for performance-critical searches.

```bash
"fn \w+_test"              → Finds: fn test_parse, fn integration_test
```

```bash
"TODO|FIXME"               → Finds: TODO and FIXME comments
```

```bash
"impl .* for"              → Finds: trait implementations in Rust
```

```bash
"async fn.*Error"          → Finds: async functions returning errors
```

--------------------------------

### Complete Example Session: Lexical Search for TODOs

Source: https://github.com/beaconbay/ck/blob/main/docs-site/public/AGENTS.md

Performs a lexical (keyword-based) search for 'TODO' across the entire project. This is useful for finding specific comments or markers.

```bash
ck --lex "TODO" .
```

--------------------------------

### Chunks Mode Visual Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/tui-mode.md

This Rust code example demonstrates Chunks Mode, which displays matched code chunks with semantic boundaries, showing complete functions or logical blocks. It highlights features like token counts and syntax highlighting.

```rust
┌─ function handle_request • 45 tokens ─┐
│                                        │
│  async fn handle_request(req: Request) -> Result<Response> {
│      let result = match req.method {
│          Method::GET => handle_get(req).await?,
│          Method::POST => handle_post(req).await?,
│          Method::DELETE => handle_delete(req).await?,
│          _ => return Err(Error::MethodNotAllowed),
│      };
│      Ok(result)
│  }
└────────────────────────────────────────┘
```

--------------------------------

### Heatmap Mode Visual Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/tui-mode.md

This example illustrates Heatmap Mode, which colors code lines by semantic relevance to a query. It shows line-by-line relevance scores and uses a color scale to indicate importance, from extremely relevant (bright green) to low relevance (gray).

```bash
│ 🟢  pub fn process_timeout(duration: Duration) -> Result<()> {  (0.95)
│ 🟢      let elapsed = start.elapsed();                          (0.89)
│ 🟡      if elapsed > duration {                                 (0.72)
│ 🟡          log::warn!("Operation timed out");                  (0.68)
│ 🟠          return Err(Error::Timeout);                         (0.58)
│ ⚪      }                                                        (0.35)
│ ⚪      Ok(())
│ ⚪  }                                                            (0.15)
```

--------------------------------

### Package ck Extension

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/editor-integration.md

Package the ck extension into a .vsix file for distribution or manual installation.

```bash
npm run package  # Creates .vsix file
```

--------------------------------

### Release Build and Test

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/architecture.md

Perform a full build and test cycle for release. This includes running tests, linting, and checking formatting.

```bash
cargo test --workspace
cargo clippy --workspace --all-features
cargo fmt --all --check
```

--------------------------------

### Troubleshooting: Reinstall ck-search Tool

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/mcp-integration.md

Remove and then re-add the ck-search tool to resolve potential installation issues.

```bash
# Reinstall
claude mcp remove ck-search
claude mcp add ck-search -s user -- ck --serve
```

--------------------------------

### Index Management Examples

Source: https://github.com/beaconbay/ck/blob/main/docs-site/reference/cli.md

Commands for managing the search index. Includes checking status, building, cleaning, and rebuilding the index, as well as switching embedding models.

```bash
# Check status
ck --status .
```

```bash
# Build index
ck --index .
```

```bash
# Rebuild from scratch
ck --clean .
ck --index .
```

```bash
# Switch models
ck --switch-model nomic-v1.5 .
```

--------------------------------

### Image Reference Example

Source: https://github.com/beaconbay/ck/blob/main/docs-site/README.md

Shows how to reference images placed in the public directory within VitePress markdown.

```markdown
![Alt text](/image.png)
```

--------------------------------

### Gradual Adoption of ck

Source: https://github.com/beaconbay/ck/blob/main/docs-site/features/grep-compatibility.md

Illustrates a strategy for adopting ck gradually by using grep for simple tasks and ck for more complex code search or semantic pattern matching. The hybrid mode is also mentioned.

```bash
# Keep grep for basic tasks
grep "simple pattern" file.txt

# Use ck for code search
ck --sem "authentication" src/

# Use ck hybrid for complex patterns
ck --hybrid "connection timeout" src/
```

--------------------------------

### Hybrid Search Queries

Source: https://github.com/beaconbay/ck/blob/main/TUI.md

Examples of queries for hybrid search, which combines semantic understanding with keyword precision.

```text
"async timeout"
"cache invalidation"
```

--------------------------------

### Hybrid Search Examples

Source: https://github.com/beaconbay/ck/blob/main/README.md

Demonstrates different ways to perform hybrid searches using the ck command. Includes options for showing relevance scores and filtering results by a minimum relevance threshold.

```bash
ck --hybrid "async timeout" src/    # Best of both worlds
```

```bash
ck --hybrid --scores "cache" src/   # Show relevance scores with color highlighting
```

```bash
ck --hybrid --threshold 0.02 query  # Filter by minimum relevance
```

--------------------------------

### Semantic Search Queries

Source: https://github.com/beaconbay/ck/blob/main/TUI.md

Examples of conceptual queries for semantic search, which finds code by meaning using embeddings.

```text
"error handling"
"database connection pooling"
"user authentication"
```

--------------------------------

### Understanding Unfamiliar Codebase with Search

Source: https://github.com/beaconbay/ck/blob/main/docs-site/guide/choosing-interface.md

Navigate and understand a new codebase by performing targeted searches for keywords related to specific functionalities. This helps in mapping out different parts of the code.

```bash
1. Open search panel
2. Search: "authentication"
   → See all auth-related code
3. Search: "database queries"
   → Understand data layer
4. Search: "API endpoints"
   → Map out interfaces
```

--------------------------------

### Run Full SWE-bench Benchmark

Source: https://github.com/beaconbay/ck/blob/main/benchmarks/swe-bench/README.md

Executes the complete SWE-bench benchmark. This process includes downloading the dataset, cloning repositories, running CK searches, and generating results.

```bash
python run.py
```