- Add GitHub Actions workflow for automatic deployment
- Configure VitePress base path for GitHub Pages (/ck/)
- Remove quotes from hero title and text
- Deploy to gh-pages branch on push to docs-site

This enables preview of documentation at:
https://charleswiltgen.github.io/ck/

- Update tagline to emphasize LLM integration
- Change "Supercharge" to "Supercharges" for grammatical correctness
- Fix typographic apostrophe in "you're"
- Replace SVG logo with PNG version
- Add public directory for static assets

- Use logo PNG as favicon instead of .ico
- Replace colon-space with en-dash in bulleted lists
- Change pattern from "**Title**: Description" to "**Title** – Description"
- Updated 47 instances across 9 documentation files (including front page)
- Preserve user's manual tagline edit ("Supercharge" without 's')

- Add lighter font weight for "(seek)" pronunciation in hero
- Update "How It Works" list to use en-dashes instead of colons
- Style 'ck' references with inline code formatting in limitations page

Hybrid search uses RRF (Reciprocal Rank Fusion) scoring which produces
values in the 0.01-0.05 range, not 0.0-1.0 like semantic search. This
was causing confusion for users trying to use semantic-style thresholds
with hybrid search.

Changes:
- Add prominent warning section explaining RRF threshold scale difference
- Update all hybrid threshold examples from 0.3-0.7 to 0.015-0.03 range
- Add "Threshold Quick Reference" comparison table
- Create troubleshooting section for threshold confusion
- Update CLI reference to clarify different scales for semantic vs hybrid
- Add inline comments explaining RRF score ranges in examples

Affected files:
- features/hybrid-search.md: Major update with warning, table, and troubleshooting
- reference/cli.md: Updated threshold documentation and added hybrid examples
- guide/getting-started.md: Fixed hybrid threshold example (0.5 → 0.02)
- guide/basic-usage.md: Fixed hybrid threshold example (0.5 → 0.025)

Addresses reviewer feedback about counterintuitive RRF threshold scale.

…eatures

Major documentation overhaul to make docs-site the authoritative source:

## New Documentation Pages
- features/tui-mode.md: Complete Terminal UI documentation (~800 lines)
  * Interface layout, keyboard shortcuts, search modes, preview modes
  * Common workflows and troubleshooting
- features/editor-integration.md: VSCode/Cursor extension guide (~400 lines)
  * Installation, features, commands, configuration, development
- guide/choosing-interface.md: Interface selection guide (~500 lines)
  * Decision matrix for CLI/TUI/Editor/MCP with workflows and examples
- guide/changelog.md: Complete changelog from CHANGELOG.md (~300 lines)
  * All releases v0.1.0 to v0.5.3, version timeline, breaking changes policy

## Updated Documentation
- guide/getting-started.md: Added interface selection section
- guide/basic-usage.md: Added TUI and Editor workflow examples
- features/mcp-integration.md: Added default_ckignore tool, RRF threshold warnings
- reference/advanced.md: Added intelligent code chunking section (~200 lines)
  * Tree-sitter query-based chunking, chunk-level incremental indexing (v0.7.0)
  * Supported languages, trivia handling, chunk inspection
- index.md: Updated hero, features grid, quick start with all interfaces
- .vitepress/config.ts: Reorganized navigation with Interface/Capabilities groups

## Key Improvements
- Documented all four interfaces: CLI, TUI, Editor, MCP
- Added RRF threshold warnings throughout (hybrid: 0.01-0.05, not 0-1)
- Comprehensive cross-references between related docs
- User-centric organization with "Choosing an Interface" decision guide
- Build verified: pnpm run build succeeds

Documentation site now serves as the authoritative, comprehensive source for ck
with excellent navigation and user guidance for all interface options.

## Added

- **AI Agent Setup Guide** (guide/ai-agent-setup.md): Complete configuration guide for AI coding assistants like Claude Code
  - Claude Code integration with tool permissions example from issue BeaconBay#36
  - Search mode selection guidance (--sem, --lex, --hybrid, --regex)
  - Performance tuning recommendations (thresholds, limits, output formats)
  - Embedding model selection for AI agents
  - Recommended .ckignore patterns for AI-assisted development
  - Common workflows (onboarding, code review, refactoring, documentation)
  - MCP integration best practices
  - Troubleshooting guide and performance benchmarks

- **AGENTS.md** (public/AGENTS.md): Quick reference guide for AI agents
  - Concise command patterns and examples
  - Essential flags and optimal defaults
  - Quick troubleshooting reference
  - Complete example session
  - Token-efficient format for rapid agent parsing

## Updated

- **Navigation** (.vitepress/config.ts): Added "AI Agent Setup" to Getting Started section
- **MCP Integration** (features/mcp-integration.md): Added cross-links to AI agent configuration guide
- **Choosing Interface** (guide/choosing-interface.md): Added AI agent setup references
- **Getting Started** (guide/getting-started.md): Added AI agent setup link in MCP section and Next Steps

## Context

Addresses the need for AI coding assistants to effectively use ck semantic search capabilities. Based on real-world usage patterns from BeaconBay#36 showing Claude Code integration.

AGENTS.md is in public/ folder which gets copied as-is, so relative
links don't work. Replaced with absolute URL to docs site.

Improve documentation typography by replacing straight quotes (', ") with proper typographical quotes (', ", ") in all narrative text, while preserving straight quotes in code blocks, inline code, and technical content for accurate copy-paste functionality.

Ignore Claude Code local settings directory to prevent committing personal configuration files.

Add callout boxes throughout documentation for better scannability:
- Added 14 callout boxes (12 tips, 2 warnings) across 5 key files
- Tips highlight helpful information and best practices
- Warnings flag time-wasting mistakes (destructive operations, performance issues)
- Improved visual hierarchy and information discoverability

Rename getting-started.md to installation.md for clarity:
- File now matches sidebar label "Installation"
- Updated page H1 title from "Getting Started" to "Installation"
- Fixed heading hierarchy (H3 -> H2 for main sections)
- Updated all internal links (6 files) and config

Add npm installation option:
- Added npm install instructions to installation page
- Included update/upgrade commands for npm users
- Updated homepage to show npm as second installation option
- Links to npmjs.com package page

Files modified:
- guide/installation.md (renamed from getting-started.md)
- features/semantic-search.md
- guide/ai-agent-setup.md
- guide/faq.md
- features/mcp-integration.md (verified existing callouts)
- index.md
- .vitepress/config.ts
- guide/introduction.md
- guide/choosing-interface.md
- README.md

Improved documentation formatting and consistency:

**Code Block Language Hints:**
- Added syntax highlighting hints to 264 code blocks across 8 files
- Applied bash, json, python, markdown, gitignore as appropriate
- Used context-aware detection to assign correct language identifiers
- Improves readability and helps readers understand code context

Files updated with language hints:
- features/editor-integration.md
- features/hybrid-search.md
- features/tui-mode.md
- guide/advanced-usage.md
- guide/basic-usage.md
- guide/choosing-interface.md
- guide/installation.md

**NPM Capitalization:**
- Capitalized "npm" to "NPM" in prose text (headings and descriptions)
- Kept lowercase in commands and code blocks (correct usage)
- Files: guide/installation.md, index.md

Phase 1, Item 2 of documentation improvements complete.

Clarified default top-k behavior in CLI reference to resolve discrepancy
between changelog (topk=10 default) and CLI docs (max 100).

**Changes:**
- Updated CLI reference to distinguish between semantic/hybrid defaults
  (10 results) vs maximum limit (100) and keyword behavior (all matches)
- Verified top-k prose standardization is already correct throughout docs:
  - Prose uses hyphenated "top-k" ✓
  - Code examples use exact flag names (--topk, top_k) ✓
  - Parameter assignments use compact format (topk=10) ✓

Phase 1, Item 3 of documentation improvements complete.

Created new reference page documenting JSON and JSONL output schemas,
addressing missing structured output documentation.

**New Documentation:**
- reference/output-formats.md: Complete JSON/JSONL reference
  - Detailed field schemas (file, line, content, score)
  - Field type documentation and value ranges
  - Semantic vs hybrid score scale differences
  - JSON array vs JSONL format comparison
  - Processing examples (Bash, Python, Node.js, jq)
  - Use cases (AI agents, data analysis, CI/CD, custom tooling)
  - Performance considerations and optimization tips
  - Error handling patterns

**Integration:**
- Updated CLI reference to link to new output formats page
- Added "Output Formats" to Reference section in navigation
- Maintains consistency with existing MCP response format docs

**Benefits:**
- AI agents have clear schema documentation
- Users understand score ranges and field meanings
- Stream processing examples for JSONL workflows
- Complete reference for automation and tooling

Phase 1, Item 4 of documentation improvements complete.

Added title and description metadata to improve SEO, search functionality,
and documentation discoverability.

**Frontmatter Added:**
- Guide pages (10): Introduction, Installation, Choosing Interface, Basic/Advanced Usage, AI Agent Setup, Changelog, FAQ, Limitations, Roadmap
- Feature pages (6): Semantic Search, Hybrid Search, grep Compatibility, TUI Mode, Editor Integration, MCP Integration
- Reference pages (6): CLI Reference, Output Formats, Embedding Models, Configuration, Advanced Configuration, Architecture
- Contributing pages (3): Development Guide, Release Process, Testing Guidelines

**Benefits:**
- Better SEO with proper title/description meta tags
- Improved VitePress local search (indexes titles/descriptions)
- Enhanced social sharing (og:title, og:description auto-populated)
- Clearer browser tabs with custom titles
- Better documentation discovery for users

**Metadata Format:**
- title: Concise, keyword-rich page titles
- description: 140-160 character summaries optimized for search snippets
- All descriptions include key search terms and actionable content

Phase 1, Item 5 of documentation improvements complete.

Replaced site logo (logo.png) with new ASCII art text design.

**Changes:**
- Updated public/logo.png with ascii-art-text.png
- Logo appears in header navigation and homepage hero section
- File size reduced from 344K to 58K
- Build verified successful

Old logo backed up as public/logo.png.bak (not committed).

Add new "Recipes" section to documentation with goal-oriented,
task-based guides for common workflows:

- Exploring New Codebases: Understand unfamiliar projects in 15 minutes
- Finding Authentication Code: Locate and audit auth implementations
- Refactoring Similar Patterns: Find and deduplicate code patterns
- Security Code Review: Comprehensive security audit workflows
- AI Agent Search Workflows: Integrate ck with AI agents (MCP, LangChain)
- Debugging Production Issues: Trace bugs using semantic search

Each recipe includes:
- Clear goals and time estimates
- Step-by-step commands with example outputs
- Real-world examples and use cases
- Language-specific patterns
- Cross-links to relevant documentation
- Tips and best practices
- YAML frontmatter for SEO

Updated navigation to add Recipes between Guide and Features.

Related to Phase 2 improvements and TASKS.md strategic feedback
about AI-first positioning.

- Replace triple backticks in Python f-string with concatenated strings
- Add language hint (text) to example output code block
- Add blank lines around headings and lists per markdownlint
- Fixes page rendering issue that made content appear empty

Break long function signature across multiple lines for better
readability in documentation

Restore original Python f-string with embedded triple backticks and
use 4-backtick code fences to properly escape them in markdown.

This is the correct solution for including code that contains triple
backticks within markdown code blocks.

Set siteTitle: false in VitePress config since the logo is a logotype
that already includes the 'ck' text. This prevents redundant text
display next to the logo.

Enables automatic typography improvements:
- Straight quotes to curly quotes
- -- to em-dashes
- ... to ellipsis
- Other common typographic replacements

This improves the professional appearance of prose content.

Major messaging updates to address creator feedback from TASKS.md:

Rebranding:
- Change "Semantic Code Search" to "Hybrid Code Search" site-wide
- New technical tagline emphasizing BM25/grep + embeddings fusion
- Update site description, introduction, AI agent setup, and README

Homepage improvements:
- Reorder feature cards: grep replacement → semantic → hybrid → AI
- Add <code> styling to "grep" in card title

Typography fixes:
- Fix typographer configuration (move from md.set() to top-level property)
- Add typographical quotes to hero tagline and feature cards
- Enable automatic smart quotes in markdown body content

Addresses TASKS.md item BeaconBay#1: Position as grep-first with hybrid capabilities
rather than semantic-only tool to avoid "semantic sucks for code" perception.

Changes:
- Homepage Quick Start: Use NPM instead of cargo
- Homepage Installation: Move NPM to top, mark as recommended
- Installation page: Reorder to put NPM first with "(Recommended)"
- Update description to mention NPM before crates.io

NPM is now the recommended installation method for easier setup
and broader accessibility.

Critical fixes:
- Add lang='en-US' attribute for screen readers (WCAG 3.1.1)
- Make logo accessible with visually-hidden site title (WCAG 1.1.1, 2.4.4)
- Fix code block syntax warnings (gitignore → txt)

Changes:
- .vitepress/config.ts: Add lang attribute and siteTitle
- .vitepress/theme/: Custom theme with accessible CSS
- Multiple .md files: Replace gitignore code blocks with txt

- Reorder introduction to lead with AI agents (per creator feedback)
- Document PDF support with limitations and privacy trade-offs
- Add near-miss threshold hints for AI agent troubleshooting
- Fix code block language tag (gitignore → txt)

Addresses feedback from TASKS.md about AI-first identity and missing
feature documentation.