cc-md-search-cli 1.0.0

package/CONFIGURATION.md

@@ -0,0 +1,247 @@
+# Documentation Path Configuration Guide
+
+## Overview
+
+The CC-MD-Search skill includes **configurable documentation paths** so Claude Code automatically knows where to search your documentation without you having to specify it every time.
+
+## Why Configure the Path?
+
+**Before configuration:**
+```
+You: "How do I set up authentication?"
+Claude Code: "Which directory should I search?"
+You: "./docs"
+Claude Code: [searches and answers]
+```
+
+**After configuration:**
+```
+You: "How do I set up authentication?"
+Claude Code: [automatically searches ./docs and answers]
+```
+
+## Configuration Steps
+
+### Step 1: Edit the Skill File
+
+Open `skills/SKILL.md` and find the Configuration section at the top:
+
+```bash
+# Current (placeholder)
+DOCS_PATH="./docs"
+```
+
+Change it to your actual documentation path:
+
+```bash
+# Your actual path
+DOCS_PATH="./documentation"
+```
+
+### Step 2: Copy to Claude Code Skills Directory
+
+```bash
+# Find your Claude Code skills directory
+# Usually: ~/.claude/skills/
+
+# Copy the configured skill
+cp skills/SKILL.md ~/.claude/skills/md-search.md
+```
+
+### Step 3: Verify Configuration
+
+```bash
+# Test that the CLI can find your docs
+ccmds list ./docs
+
+# Try a search
+ccmds find "setup" ./docs -l 5
+```
+
+## Configuration Examples
+
+### Single Documentation Folder
+
+```bash
+DOCS_PATH="./docs"
+```
+
+### Nested Documentation
+
+```bash
+DOCS_PATH="./documentation/markdown"
+```
+
+### Project Root
+
+```bash
+DOCS_PATH="."
+```
+
+### Monorepo Setup
+
+```bash
+# Main docs
+DOCS_PATH="./docs"
+
+# Additional paths (optional)
+WEB_DOCS_PATH="./packages/web/docs"
+API_DOCS_PATH="./packages/api/docs"
+```
+
+## How Claude Code Uses This
+
+Once configured, Claude Code will **automatically search** your documentation when you ask questions like:
+
+- "How do I set up authentication?" → Searches `./docs`
+- "What's the API for user management?" → Searches `./docs`
+- "Where is the deployment guide?" → Searches `./docs`
+- "How do I configure the database?" → Searches `./docs`
+
+**No manual path specification needed!**
+
+## Recommended Documentation Structure
+
+Organize your docs for best search results:
+
+```
+docs/
+├── setup/              # Installation & setup guides
+│   ├── quickstart.md
+│   └── environment.md
+├── api/                # API documentation
+│   ├── authentication.md
+│   ├── endpoints.md
+│   └── webhooks.md
+├── guides/             # How-to guides
+│   ├── deployment.md
+│   ├── testing.md
+│   └── configuration.md
+├── architecture/       # System design docs
+│   ├── overview.md
+│   ├── database.md
+│   └── caching.md
+├── troubleshooting/    # Common issues
+│   └── faq.md
+└── reference/          # Quick references
+    └── env-vars.md
+```
+
+## Using Frontmatter (Recommended)
+
+Add YAML frontmatter to your markdown files for better searchability:
+
+```markdown
+---
+title: API Authentication Guide
+tags: [api, auth, security, jwt, oauth]
+category: api
+updated: 2025-01-17
+difficulty: intermediate
+---
+
+# API Authentication
+
+Your content here...
+```
+
+Benefits:
+- Better fuzzy search results
+- Categorization
+- Date tracking
+- Difficulty levels
+- Related tag matching
+
+## Updating Configuration
+
+To change your configured path later:
+
+1. Edit `skills/SKILL.md` and update `DOCS_PATH`
+2. Re-copy to Claude Code skills directory
+3. Verify with `ccmds list [new-path]`
+
+## Advanced Configuration
+
+### Multiple Projects
+
+If you work on multiple projects, create separate skill files:
+
+```bash
+skills/
+├── SKILL.md              # Default: DOCS_PATH="./docs"
+├── SKILL-project-a.md    # DOCS_PATH="./project-a/docs"
+└── SKILL-project-b.md    # DOCS_PATH="./project-b/documentation"
+```
+
+Then copy the appropriate skill to Claude Code's skills directory for each project.
+
+### Project-Specific Paths
+
+For projects with multiple doc locations:
+
+```bash
+# Main documentation
+DOCS_PATH="./docs"
+
+# Additional paths (reference in queries)
+# Web: ./web-app/README.md, ./web-app/docs
+# API: ./api/docs
+# CMS: ./cms/docs
+```
+
+Claude Code can search these additional locations when specifically asked:
+```
+"Search the API-specific docs for authentication"
+→ ccmds find "authentication" ./api/docs
+```
+
+## Troubleshooting
+
+### Path Not Found
+
+```bash
+# Check if path exists
+ls ./docs
+
+# Check if it contains markdown files
+ccmds list ./docs --count
+```
+
+### Changes Not Applied
+
+```bash
+# Verify the SKILL.md was updated
+grep "DOCS_PATH" skills/SKILL.md
+
+# Should show: DOCS_PATH="./your-configured-path"
+```
+
+### Claude Code Not Using Configured Path
+
+1. Make sure you copied `skills/SKILL.md` to Claude Code's skills directory
+2. Restart your Claude Code session
+3. Verify the path in the skill file is correct
+
+## Configuration Checklist
+
+- [ ] Edit `skills/SKILL.md` and set your `DOCS_PATH`
+- [ ] Verify path with `ccmds list ./docs`
+- [ ] Check markdown file count looks correct
+- [ ] Copy `skills/SKILL.md` to Claude Code skills directory
+- [ ] Test with Claude Code: "Find setup documentation"
+- [ ] Confirm Claude Code searches automatically
+
+## Pro Tips
+
+1. **Keep docs organized** - Use subdirectories for different topics
+2. **Add frontmatter** - Improves search quality significantly
+3. **Use consistent naming** - Makes files easier to find
+4. **Regular updates** - Keep documentation current
+5. **Test searches** - Verify your docs are searchable
+6. **Add README files** - Each subdirectory should have one
+
+## Related Documentation
+
+- **[README.md](./README.md)** - Quick start and command reference
+- **[skills/SKILL.md](./skills/SKILL.md)** - Complete Claude Code skill reference
+- **[skill-template.md](./skill-template.md)** - Template for creating custom configurations

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bertram Eber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# CC-MD-Search-CLI
+
+**Claude Code Markdown Search - Efficient documentation search CLI for Claude Code integration**
+
+Fast, context-efficient markdown documentation search tool designed for [Claude Code](https://claude.ai/claude-code). Quickly find relevant information across large documentation sets without loading entire files into context.
+
+## Features
+
+- **Fuzzy Search** - Find relevant docs even with typos or variations
+- **Pattern/Regex Search** - Exact matches with regex support
+- **Frontmatter Aware** - Parses YAML metadata for better search
+- **Multiple Output Modes** - compact, detailed, files, json
+- **Claude Code Skill** - Pre-built skill template for AI integration
+- **Context Efficient** - Minimize token usage when searching docs
+
+## Installation
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) (recommended) or Node.js 18+
+- npm or pnpm
+
+### Install
+
+```bash
+# Clone the repository
+git clone https://github.com/bjeber/cc-md-search-cli.git
+cd cc-md-search-cli
+
+# Install dependencies
+bun install
+# or: npm install
+
+# Link the CLI globally
+npm link
+```
+
+After linking, the `ccmds` command will be available globally.
+
+## Quick Start
+
+```bash
+# List all markdown files in a directory
+ccmds list ./docs
+
+# Fuzzy search for relevant documents
+ccmds find "authentication" ./docs -l 5
+
+# Pattern search with regex
+ccmds grep "TODO|FIXME" ./docs -c 3
+
+# Show a specific file
+ccmds show ./docs/api/auth.md
+```
+
+## Commands
+
+### `ccmds find <query> [directory]` - Fuzzy Search
+
+Find relevant documents using fuzzy matching. Great for exploratory searches.
+
+```bash
+ccmds find "user authentication" ./docs -l 5 -o compact
+ccmds find "deploy production" ./docs -o files
+```
+
+**Options:**
+- `-l, --limit <number>` - Maximum results (default: 10)
+- `-o, --output <mode>` - Output format: compact, detailed, files, json
+
+### `ccmds grep <pattern> [directory]` - Pattern Search
+
+Search for exact text patterns with regex support.
+
+```bash
+ccmds grep "ERROR_[0-9]+" ./docs -c 3
+ccmds grep "GraphQL" ./docs --case-sensitive
+```
+
+**Options:**
+- `-c, --context <lines>` - Lines of context around matches (default: 2)
+- `-s, --case-sensitive` - Case sensitive search
+- `-o, --output <mode>` - Output format
+
+### `ccmds list [directory]` - List Files
+
+List all markdown files in a directory.
+
+```bash
+ccmds list ./docs
+ccmds list ./docs --count
+```
+
+**Options:**
+- `-c, --count` - Show only file count
+
+### `ccmds show <file>` - Display File
+
+Show the full content of a markdown file.
+
+```bash
+ccmds show ./docs/api/auth.md
+ccmds show ./docs/guide.md --frontmatter-only
+ccmds show ./docs/guide.md --body-only
+```
+
+**Options:**
+- `-f, --frontmatter-only` - Show only YAML frontmatter
+- `-b, --body-only` - Show only body content
+
+## Claude Code Integration
+
+To use this tool with Claude Code, install the skill to your Claude Code skills directory.
+
+### 1. Install the Skill
+
+```bash
+# Create the skill directory
+mkdir -p ~/.claude/skills/md-search
+
+# Copy the skill file
+cp skills/SKILL.md ~/.claude/skills/md-search/SKILL.md
+```
+
+### 2. Use with Claude Code
+
+Once installed, the skill will be available as `/md-search`. Claude Code can automatically search your documentation when you ask questions:
+
+- "How do I set up authentication?"
+- "What are the API endpoints?"
+- "Where is the deployment guide?"
+
+Claude will use `ccmds` to search your documentation with minimal context usage.
+
+### 3. Skill Structure
+
+The skill follows Claude Code's skill format:
+
+```
+~/.claude/skills/md-search/
+└── SKILL.md          # Skill definition with YAML frontmatter
+```
+
+The SKILL.md includes:
+- **YAML frontmatter** with `name` and `description` for skill registration
+- **Command reference** for all `ccmds` commands
+- **Workflow strategies** for efficient documentation search
+- **Best practices** for context-efficient searches
+
+## Output Modes
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `files` | File paths only | Quick overview, piping to other commands |
+| `compact` | Paths + snippets | Default, balanced context |
+| `detailed` | Full context | Deep investigation |
+| `json` | JSON output | Programmatic processing |
+
+## Workflow Tips
+
+### Progressive Search
+
+1. Start broad with `find` to discover relevant docs
+2. Narrow down with `grep` for specific patterns
+3. Use `show` to read the exact file you need
+
+```bash
+# Discover
+ccmds find "database" ./docs -o files
+
+# Narrow down
+ccmds grep "migration" ./docs/database -c 5
+
+# Read specific file
+ccmds show ./docs/database/migrations.md
+```
+
+### Quick Lookup
+
+```bash
+# Find and show top result
+ccmds find "installation" ./docs -l 1 -o files | xargs ccmds show
+```
+
+## Documentation Structure (Recommended)
+
+For best search results, organize your docs with clear structure:
+
+```
+docs/
+├── setup/              # Installation & setup
+├── api/                # API documentation
+├── guides/             # How-to guides
+├── architecture/       # System design
+├── troubleshooting/    # Common issues
+└── reference/          # Quick references
+```
+
+### Frontmatter
+
+Add YAML frontmatter for better search relevance:
+
+```markdown
+---
+title: API Authentication Guide
+tags: [api, auth, security]
+category: api
+---
+
+# API Authentication
+...
+```
+
+## Configuration
+
+See [CONFIGURATION.md](./CONFIGURATION.md) for detailed configuration options.
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file.
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.

package/bun.lock

@@ -0,0 +1,39 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "cc-md-search-cli",
+      "dependencies": {
+        "commander": "^11.1.0",
+        "fuse.js": "^7.0.0",
+        "gray-matter": "^4.0.3",
+      },
+    },
+  },
+  "packages": {
+    "argparse": ["argparse@1.0.10", "", { "dependencies": { "sprintf-js": "~1.0.2" } }, "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg=="],
+
+    "commander": ["commander@11.1.0", "", {}, "sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ=="],
+
+    "esprima": ["esprima@4.0.1", "", { "bin": { "esparse": "./bin/esparse.js", "esvalidate": "./bin/esvalidate.js" } }, "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="],
+
+    "extend-shallow": ["extend-shallow@2.0.1", "", { "dependencies": { "is-extendable": "^0.1.0" } }, "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug=="],
+
+    "fuse.js": ["fuse.js@7.1.0", "", {}, "sha512-trLf4SzuuUxfusZADLINj+dE8clK1frKdmqiJNb1Es75fmI5oY6X2mxLVUciLLjxqw/xr72Dhy+lER6dGd02FQ=="],
+
+    "gray-matter": ["gray-matter@4.0.3", "", { "dependencies": { "js-yaml": "^3.13.1", "kind-of": "^6.0.2", "section-matter": "^1.0.0", "strip-bom-string": "^1.0.0" } }, "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q=="],
+
+    "is-extendable": ["is-extendable@0.1.1", "", {}, "sha512-5BMULNob1vgFX6EjQw5izWDxrecWK9AM72rugNr0TFldMOi0fj6Jk+zeKIt0xGj4cEfQIJth4w3OKWOJ4f+AFw=="],
+
+    "js-yaml": ["js-yaml@3.14.2", "", { "dependencies": { "argparse": "^1.0.7", "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg=="],
+
+    "kind-of": ["kind-of@6.0.3", "", {}, "sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw=="],
+
+    "section-matter": ["section-matter@1.0.0", "", { "dependencies": { "extend-shallow": "^2.0.1", "kind-of": "^6.0.0" } }, "sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA=="],
+
+    "sprintf-js": ["sprintf-js@1.0.3", "", {}, "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g=="],
+
+    "strip-bom-string": ["strip-bom-string@1.0.0", "", {}, "sha512-uCC2VHvQRYu+lMh4My/sFNmF2klFymLX1wHJeXnbEJERpV/ZsVuonzerjfrGpIGF7LBVa1O7i9kjiWvJiFck8g=="],
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "cc-md-search-cli",
+  "version": "1.0.0",
+  "description": "Claude Code Markdown Search - Efficient documentation search CLI for Claude Code integration",
+  "type": "module",
+  "bin": {
+    "ccmds": "./src/cli.js"
+  },
+  "scripts": {
+    "build": "echo 'No build needed for Bun'",
+    "link": "npm link"
+  },
+  "keywords": [
+    "markdown",
+    "search",
+    "cli",
+    "claude-code",
+    "documentation",
+    "fuzzy-search"
+  ],
+  "author": "Bertram Eber",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bjeber/cc-md-search-cli.git"
+  },
+  "homepage": "https://github.com/bjeber/cc-md-search-cli#readme",
+  "bugs": {
+    "url": "https://github.com/bjeber/cc-md-search-cli/issues"
+  },
+  "dependencies": {
+    "commander": "^11.1.0",
+    "gray-matter": "^4.0.3",
+    "fuse.js": "^7.0.0"
+  }
+}

package/skill-template.md

@@ -0,0 +1,77 @@
+---
+name: md-search
+description: This skill enables efficient searching of markdown documentation using the ccmds CLI. Use this skill when the user asks about documentation, needs to find information across many markdown files, or wants to discover content without knowing exact file names. Provides fuzzy search, regex pattern matching, and context-efficient output modes.
+---
+
+# Markdown Search CLI Skill - Configuration Template
+
+## ⚙️ CONFIGURATION - EDIT THIS SECTION
+
+**IMPORTANT: Set your documentation path here before using this skill:**
+
+```
+DOCS_PATH="./your-docs-folder-here"
+```
+
+Replace `./your-docs-folder-here` with the actual path to your documentation.
+
+### Common Configuration Examples:
+
+```bash
+# Single docs folder:
+DOCS_PATH="./docs"
+
+# Project-specific:
+DOCS_PATH="./my-project-docs"
+
+# Documentation subfolder:
+DOCS_PATH="./documentation/markdown"
+
+# Nested in project:
+DOCS_PATH="./src/docs"
+```
+
+### Project-Specific Paths (Optional):
+
+If you have documentation scattered across multiple locations, you can define additional paths:
+
+```bash
+# Additional paths (optional)
+WEB_DOCS_PATH="./web-app/docs"
+API_DOCS_PATH="./api/docs"
+CMS_DOCS_PATH="./cms/docs"
+```
+
+### Auto-Search Behavior:
+
+When configured, Claude Code will **automatically search** the configured `DOCS_PATH` when the user asks questions about:
+- Setup, installation, configuration
+- API endpoints, usage
+- Architecture, design decisions
+- Troubleshooting, debugging
+- Guides, tutorials, how-tos
+- Any project documentation
+
+**No need to ask** - just search immediately using the configured path.
+
+---
+
+## 📋 Quick Start Checklist
+
+Before using this skill:
+- [ ] Replace `./your-docs-folder-here` with your actual docs path
+- [ ] Verify the path exists: `ls ./your-docs-folder-here`
+- [ ] Test the search: `ccmds list ./your-docs-folder-here`
+- [ ] (Optional) Configure additional project-specific paths
+- [ ] Save this file to your Claude Code skills directory
+
+---
+
+Once configured, see the full SKILL.md file for:
+- Complete command reference
+- Workflow strategies
+- Output mode selection
+- Best practices
+- Example interactions
+
+**After configuration, copy the configured DOCS_PATH to the main SKILL.md file.**

package/skills/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: md-search
+description: This skill enables efficient searching of markdown documentation using the ccmds CLI. Use this skill when the user asks about documentation, needs to find information across many markdown files, or wants to discover content without knowing exact file names. Provides fuzzy search, regex pattern matching, and context-efficient output modes.
+---
+
+# Markdown Search CLI Skill
+
+## Overview
+This skill enables efficient searching of markdown documentation databases using the `ccmds` CLI tool. Use this to find relevant information in large documentation sets without loading entire files into context.
+
+## When to Use
+- User asks about documentation, guides, or references
+- Need to find specific information across many files
+- Want to discover related content without knowing exact file names
+- Need to minimize context usage when working with large doc bases
+
+## Tool: `ccmds`
+
+### Available Commands
+
+#### 1. `ccmds find <query> [directory]` - Fuzzy/Semantic Search
+**Use when**: You need to discover relevant documents but don't know exact terms.
+
+**Options**:
+- `-l, --limit <number>`: Max results (default: 10)
+- `-o, --output <mode>`: Output format (compact, detailed, files, json)
+
+**Examples**:
+```bash
+# Find docs about authentication
+ccmds find "user authentication" ./docs -l 5 -o compact
+
+# Discover deployment guides
+ccmds find "deploy production" ./docs -o files
+```
+
+**Best for**:
+- Exploratory searches
+- Finding related topics
+- When user's question is conceptual
+- Tolerant of typos/variations
+
+#### 2. `ccmds grep <pattern> [directory]` - Pattern/Regex Search
+**Use when**: You need exact matches or specific patterns.
+
+**Options**:
+- `-c, --context <lines>`: Lines of context (default: 2)
+- `-s, --case-sensitive`: Case sensitive matching
+- `-o, --output <mode>`: Output format
+
+**Examples**:
+```bash
+# Find exact error codes
+ccmds grep "ERROR_[0-9]+" ./docs -c 3
+
+# Find all TODO items
+ccmds grep "TODO|FIXME" ./docs -o files
+
+# Case-sensitive API search
+ccmds grep "GraphQL" ./docs --case-sensitive
+```
+
+**Best for**:
+- Finding specific terms/codes
+- Regex pattern matching
+- Code snippets or examples
+- Known terminology
+
+#### 3. `ccmds list [directory]` - List Files
+**Use when**: You need an overview of available documentation.
+
+**Options**:
+- `-c, --count`: Show only count
+
+**Examples**:
+```bash
+# List all markdown files
+ccmds list ./docs
+
+# Count files
+ccmds list ./docs --count
+```
+
+#### 4. `ccmds show <file>` - Display File
+**Use when**: You've identified the right file and need full content.
+
+**Options**:
+- `-f, --frontmatter-only`: Show only YAML frontmatter
+- `-b, --body-only`: Show only body content
+
+**Examples**:
+```bash
+# Show full file
+ccmds show ./docs/api/auth.md
+
+# Show only metadata
+ccmds show ./docs/guides/setup.md --frontmatter-only
+```
+
+## Workflow Strategies
+
+### Strategy 1: Progressive Search
+1. Start with `find` to discover relevant docs (compact output)
+2. Use `grep` on specific files/directories for details
+3. Use `show` only when you've identified the exact file needed
+
+```bash
+# Step 1: Discover
+ccmds find "database migration" ./docs -o files
+
+# Step 2: Narrow down (if needed)
+ccmds grep "migration.*schema" ./docs/database -c 5
+
+# Step 3: Read specific file
+ccmds show ./docs/database/migrations.md
+```
+
+### Strategy 2: Quick Answer
+For simple lookups, combine commands:
+
+```bash
+# Find and show the top result
+ccmds find "installation steps" ./docs -l 1 -o files | xargs ccmds show
+```
+
+### Strategy 3: Comprehensive Research
+For complex questions requiring multiple sources:
+
+```bash
+# Find all relevant docs
+ccmds find "error handling" ./docs -l 10 -o json > results.json
+
+# Then grep for specific patterns across those files
+ccmds grep "catch.*Error" ./docs/api ./docs/guides -o compact
+```
+
+## Output Mode Selection
+
+Choose output mode based on context needs:
+
+| Mode | Use Case | Context Size |
+|------|----------|--------------|
+| `files` | Just need file paths | Minimal |
+| `compact` | Quick overview + snippets | Small |
+| `detailed` | Need full context around matches | Medium |
+| `json` | Programmatic processing | Variable |
+
+## Best Practices
+
+### ✅ DO:
+- Start with `find` for broad queries
+- Use `compact` output by default
+- Limit results to stay within context (`-l` flag)
+- Use `files` output when just identifying sources
+- Chain commands for efficiency
+- Search specific subdirectories when possible
+
+### ❌ DON'T:
+- Don't load entire files unless necessary
+- Don't use `detailed` output for many results
+- Don't search everything when topic is localized
+- Don't ignore frontmatter (may contain useful metadata)
+- Don't forget regex special characters need escaping in `grep`
+
+## Example User Interactions
+
+### Example 1: Finding Setup Instructions
+**User**: "How do I set up the development environment?"
+
+**Approach**:
+```bash
+ccmds find "development environment setup" ./docs -l 3 -o compact
+```
+
+### Example 2: Looking for API Endpoints
+**User**: "What are the authentication endpoints?"
+
+**Approach**:
+```bash
+# First find API docs
+ccmds find "authentication endpoints" ./docs/api -l 5 -o files
+
+# Then grep for specific patterns
+ccmds grep "POST|GET.*auth" ./docs/api -c 2
+```
+
+### Example 3: Finding Error Codes
+**User**: "What does error code E404 mean?"
+
+**Approach**:
+```bash
+ccmds grep "E404" ./docs -c 5 -o compact
+```
+
+### Example 4: Research Topic
+**User**: "Tell me everything about caching strategies"
+
+**Approach**:
+```bash
+# Discover all caching docs
+ccmds find "caching strategy" ./docs -l 5 -o compact
+
+# Review, then show most relevant
+ccmds show ./docs/architecture/caching.md
+```
+
+## Integration Tips
+
+### For Claude Code Users:
+1. **Set up alias** in your project directory
+2. **Document location**: Tell Claude where docs are (`./docs`, `./documentation`, etc.)
+3. **Use in skill**: Reference this skill in your Claude Code configuration
+4. **Combine with context**: Use search results to decide what to load fully
+
+### Configuration Example:
+```json
+{
+  "tools": {
+    "ccmds": {
+      "command": "ccmds",
+      "docs_path": "./docs"
+    }
+  }
+}
+```
+
+## Performance Notes
+
+- **Fast**: Searches hundreds of files in milliseconds
+- **Memory efficient**: Streams file reading
+- **Regex cache**: Pattern compilation is optimized
+- **Fuzzy search**: Fuse.js provides quick relevance scoring
+
+## Troubleshooting
+
+**No results found?**
+- Try fuzzy search (`find`) instead of exact (`grep`)
+- Check directory path
+- Verify file extensions (.md or .markdown)
+
+**Too many results?**
+- Use `-l` to limit
+- Search in specific subdirectory
+- Make query more specific
+- Use `grep` instead of `find`
+
+**Results not relevant?**
+- Use `grep` for exact matches
+- Check frontmatter with `--frontmatter-only`
+- Try different search terms
+
+## Summary
+
+The `ccmds` CLI is designed for **efficient documentation search** with **minimal context usage**. Use progressive discovery (`find` → `grep` → `show`) to navigate large doc bases intelligently.

package/src/cli.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, relative } from 'path';
+import matter from 'gray-matter';
+import Fuse from 'fuse.js';
+
+const program = new Command();
+
+// Recursively find all markdown files
+function findMarkdownFiles(dir, baseDir = dir) {
+  let files = [];
+  const items = readdirSync(dir);
+
+  for (const item of items) {
+    const fullPath = join(dir, item);
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      files = files.concat(findMarkdownFiles(fullPath, baseDir));
+    } else if (item.endsWith('.md') || item.endsWith('.markdown')) {
+      files.push({
+        path: fullPath,
+        relativePath: relative(baseDir, fullPath)
+      });
+    }
+  }
+
+  return files;
+}
+
+// Parse markdown file with frontmatter
+function parseMarkdownFile(filePath) {
+  const content = readFileSync(filePath, 'utf-8');
+  const { data: frontmatter, content: body } = matter(content);
+  
+  return {
+    filePath,
+    frontmatter,
+    body,
+    fullContent: content
+  };
+}
+
+// Grep-style search
+function grepSearch(files, query, options) {
+  const results = [];
+  const regex = new RegExp(query, options.caseSensitive ? 'g' : 'gi');
+
+  for (const file of files) {
+    const parsed = parseMarkdownFile(file.path);
+    const lines = parsed.body.split('\n');
+    const matches = [];
+
+    lines.forEach((line, index) => {
+      if (regex.test(line)) {
+        const start = Math.max(0, index - options.context);
+        const end = Math.min(lines.length, index + options.context + 1);
+        
+        matches.push({
+          lineNumber: index + 1,
+          line: line.trim(),
+          context: lines.slice(start, end).join('\n')
+        });
+      }
+    });
+
+    if (matches.length > 0) {
+      results.push({
+        file: file.relativePath,
+        matches,
+        frontmatter: parsed.frontmatter
+      });
+    }
+  }
+
+  return results;
+}
+
+// Fuzzy search for finding relevant documents
+function fuzzySearch(files, query, options) {
+  const documents = files.map(file => {
+    const parsed = parseMarkdownFile(file.path);
+    return {
+      file: file.relativePath,
+      title: parsed.frontmatter.title || file.relativePath,
+      body: parsed.body,
+      frontmatter: parsed.frontmatter,
+      tags: parsed.frontmatter.tags || []
+    };
+  });
+
+  const fuse = new Fuse(documents, {
+    keys: [
+      { name: 'title', weight: 2 },
+      { name: 'body', weight: 1 },
+      { name: 'tags', weight: 1.5 }
+    ],
+    threshold: 0.4,
+    includeScore: true,
+    minMatchCharLength: 2
+  });
+
+  const results = fuse.search(query);
+  return results.slice(0, options.limit).map(result => ({
+    file: result.item.file,
+    score: result.score,
+    title: result.item.title,
+    frontmatter: result.item.frontmatter,
+    preview: result.item.body.substring(0, 200) + '...'
+  }));
+}
+
+// Format output
+function formatOutput(results, mode) {
+  if (mode === 'json') {
+    return JSON.stringify(results, null, 2);
+  }
+
+  if (mode === 'files') {
+    return results.map(r => r.file).join('\n');
+  }
+
+  if (mode === 'compact') {
+    return results.map(r => {
+      let output = `\n📄 ${r.file}`;
+      if (r.score !== undefined) {
+        output += ` (relevance: ${(1 - r.score).toFixed(2)})`;
+      }
+      if (r.matches) {
+        output += `\n   ${r.matches.length} match(es)`;
+        r.matches.slice(0, 3).forEach(m => {
+          output += `\n   Line ${m.lineNumber}: ${m.line.substring(0, 80)}`;
+        });
+      } else if (r.preview) {
+        output += `\n   ${r.preview}`;
+      }
+      return output;
+    }).join('\n');
+  }
+
+  // Default: detailed
+  return results.map(r => {
+    let output = `\n${'='.repeat(60)}\n📄 ${r.file}\n${'='.repeat(60)}`;
+    
+    if (r.frontmatter && Object.keys(r.frontmatter).length > 0) {
+      output += '\n\nFrontmatter:\n' + JSON.stringify(r.frontmatter, null, 2);
+    }
+
+    if (r.matches) {
+      r.matches.forEach(m => {
+        output += `\n\n--- Line ${m.lineNumber} ---\n${m.context}`;
+      });
+    } else if (r.preview) {
+      output += `\n\nPreview:\n${r.preview}`;
+    }
+
+    return output;
+  }).join('\n');
+}
+
+// Main CLI
+program
+  .name('ccmds')
+  .description('Claude Code Markdown Search - CLI for efficient document querying')
+  .version('1.0.0');
+
+program
+  .command('grep')
+  .description('Search for exact text patterns (regex supported)')
+  .argument('<query>', 'Search query (regex pattern)')
+  .argument('[directory]', 'Directory to search', '.')
+  .option('-c, --context <lines>', 'Lines of context around matches', '2')
+  .option('-s, --case-sensitive', 'Case sensitive search', false)
+  .option('-o, --output <mode>', 'Output mode: detailed, compact, files, json', 'compact')
+  .action((query, directory, options) => {
+    const files = findMarkdownFiles(directory);
+    const results = grepSearch(files, query, {
+      context: parseInt(options.context),
+      caseSensitive: options.caseSensitive
+    });
+    
+    console.log(formatOutput(results, options.output));
+    console.log(`\n✓ Found ${results.length} file(s) with matches`);
+  });
+
+program
+  .command('find')
+  .description('Fuzzy search for relevant documents')
+  .argument('<query>', 'Search query')
+  .argument('[directory]', 'Directory to search', '.')
+  .option('-l, --limit <number>', 'Maximum results to return', '10')
+  .option('-o, --output <mode>', 'Output mode: detailed, compact, files, json', 'compact')
+  .action((query, directory, options) => {
+    const files = findMarkdownFiles(directory);
+    const results = fuzzySearch(files, query, {
+      limit: parseInt(options.limit)
+    });
+    
+    console.log(formatOutput(results, options.output));
+    console.log(`\n✓ Found ${results.length} relevant document(s)`);
+  });
+
+program
+  .command('list')
+  .description('List all markdown files')
+  .argument('[directory]', 'Directory to search', '.')
+  .option('-c, --count', 'Show only count', false)
+  .action((directory, options) => {
+    const files = findMarkdownFiles(directory);
+    
+    if (options.count) {
+      console.log(files.length);
+    } else {
+      files.forEach(f => console.log(f.relativePath));
+    }
+  });
+
+program
+  .command('show')
+  .description('Show full content of a markdown file')
+  .argument('<file>', 'File path')
+  .option('-f, --frontmatter-only', 'Show only frontmatter', false)
+  .option('-b, --body-only', 'Show only body content', false)
+  .action((file, options) => {
+    const parsed = parseMarkdownFile(file);
+    
+    if (options.frontmatterOnly) {
+      console.log(JSON.stringify(parsed.frontmatter, null, 2));
+    } else if (options.bodyOnly) {
+      console.log(parsed.body);
+    } else {
+      console.log(parsed.fullContent);
+    }
+  });
+
+program.parse();