Initial commit

skills/candlekeep/README.md

@@ -0,0 +1,197 @@
+# Candlekeep Skill
+
+A personal knowledge base system that gives AI agents direct access to your books.
+
+## Quick Start
+
+### Installation
+
+1. **Install Python dependencies**:
+   ```bash
+   cd plugins/candlekeep/skills/candlekeep
+   uv sync
+   ```
+
+2. **Initialize Candlekeep**:
+   ```bash
+   uv run candlekeep init
+   ```
+   
+   This creates `~/.candlekeep/` with database and configuration.
+
+## Usage
+
+### Add Books to Your Library
+
+**Add a PDF:**
+```bash
+uv run candlekeep add-pdf ~/Documents/my-book.pdf \
+  --title "Book Title" \
+  --author "Author Name" \
+  --tags "programming,reference"
+```
+
+**Add a Markdown file:**
+```bash
+uv run candlekeep add-markdown ~/Documents/notes.md \
+  --title "My Notes" \
+  --tags "documentation"
+```
+
+### List Your Books
+
+```bash
+uv run candlekeep list
+```
+
+**Output:**
+```
+Books in library:
+ID: 1
+Title: The Pragmatic Programmer
+Author: David Thomas, Andrew Hunt
+Pages: 352
+Format: pdf
+Tags: programming, software-engineering
+```
+
+### Query Your Library
+
+Once books are added, simply ask Claude questions in natural language:
+
+**Example Questions:**
+- "Do I have any books on Python? Show me what they say about decorators"
+- "What does my software architecture book say about microservices?"
+- "List all books tagged with 'machine-learning'"
+
+**Claude will automatically:**
+1. List available books
+2. Show table of contents
+3. Extract relevant pages
+4. Provide answers with page citations
+
+## Available Commands
+
+All commands use `uv run candlekeep` from the skill directory.
+
+### `init`
+Initialize the Candlekeep database and configuration.
+
+### `add-pdf <file_path>`
+Add a PDF book to your library.
+
+**Options:**
+- `--title` - Book title (optional, extracted from metadata if not provided)
+- `--author` - Author name (optional)
+- `--tags` - Comma-separated tags (optional)
+
+### `add-markdown <file_path>`
+Add a Markdown document to your library.
+
+**Options:**
+- `--title` - Document title (required)
+- `--author` - Author name (optional)
+- `--tags` - Comma-separated tags (optional)
+
+### `list`
+List all books in your library with metadata.
+
+### `toc <book_id>`
+Show the table of contents for a specific book.
+
+```bash
+uv run candlekeep toc 1
+```
+
+### `query <book_id> <start_page> <end_page>`
+Extract content from specific pages of a book.
+
+```bash
+uv run candlekeep query 1 10 15
+```
+
+**Returns:** Text content from pages 10-15 with page markers.
+
+## How It Works
+
+### Progressive Disclosure Pattern
+
+Candlekeep uses a token-efficient approach:
+
+1. **Discovery** - Lists book titles/metadata (~20-50 tokens per book)
+2. **Navigation** - Shows table of contents when needed
+3. **Extraction** - Fetches only requested page ranges
+4. **Citation** - Includes page markers for precise references
+
+This keeps context usage minimal while providing comprehensive access.
+
+### Privacy & Storage
+
+- **All data stored locally** in `~/.candlekeep/candlekeep.db` (SQLite)
+- **No external API calls** - purely local processing
+- **Content stored as chunks** with page-level granularity
+- **Efficient indexing** by title, author, tags, and content
+
+## File Structure
+
+```
+~/.candlekeep/
+├── candlekeep.db       # SQLite database
+└── config.json         # Configuration
+
+plugins/candlekeep/skills/candlekeep/
+├── SKILL.md            # Skill definition for Claude
+├── README.md           # This file
+├── pyproject.toml      # Python dependencies
+├── alembic/            # Database migrations
+└── src/
+    └── candlekeep/
+        ├── cli.py              # Command-line interface
+        ├── commands/           # Command implementations
+        ├── db/                 # Database models
+        ├── parsers/            # PDF/Markdown parsers
+        └── utils/              # Utilities
+```
+
+## Requirements
+
+- **Python**: >=3.10
+- **UV**: >=0.1.0 (package manager)
+
+## Troubleshooting
+
+### "Database not found"
+
+Run `uv run candlekeep init` to initialize the database.
+
+### "PDF parsing failed"
+
+Ensure the PDF is not corrupted and has extractable text. Some scanned PDFs without OCR won't work.
+
+### "Dependencies not installed"
+
+Run `uv sync` from the skill directory to install all dependencies.
+
+### "Command not found: candlekeep"
+
+Make sure you're running commands with `uv run candlekeep` prefix from the skill directory.
+
+## Tips for Great Results
+
+1. **Use descriptive tags** - Makes it easier for Claude to find relevant books
+2. **Add complete metadata** - Helps with discovery and citation
+3. **Break large documents** - Consider splitting very large books into volumes
+4. **Regular queries** - Reference books frequently to maximize value
+5. **Organize by topic** - Use consistent tagging schemes
+
+## Support
+
+For issues or questions:
+- Review the [Plugin README](../../README.md) for installation help
+- Check the SKILL.md for Claude's internal documentation
+- Verify database exists at `~/.candlekeep/candlekeep.db`
+
+---
+
+**Created by**: Sahar Carmel  
+**License**: MIT