## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# KOGRAL Documentation

Welcome to the KOGRAL documentation! This directory contains comprehensive documentation for KOGRAL (KOwledge GRAphs, Local-first), built with mdBook.

## 📚 Reading the Documentation

You have several options for reading the documentation:

### Option 1: Serve Locally with mdBook (Recommended)

The best reading experience with navigation, search, and live reload:

    # Serve documentation at http://localhost:3000
    just docs::serve

This will:

- Build the mdBook
- Start a local web server on port 3000
- Open your browser automatically
- Watch for changes and auto-reload

### Option 2: Build Static HTML

Generate static HTML files you can browse offline:

    # Build mdBook to docs/book/
    just docs::build

Then open `docs/book/index.html` in your browser.

### Option 3: Read Markdown Files Directly

All documentation is written in Markdown and can be read directly:

- Browse via GitHub/GitLab web interface
- Use your editor's Markdown preview
- Read from terminal with `bat`, `glow`, or similar tools

Navigation: See SUMMARY.md for the complete table of contents.

## 🛠️ Documentation Commands

We use `just` recipes for documentation tasks. All commands assume you're in the project root directory.

### Build and Serve

    # Serve documentation locally (recommended)
    just docs::serve

    # Build static HTML
    just docs::build

    # Watch and rebuild on file changes
    just docs::watch

### Validation

    # Test code examples in documentation
    just docs::test

    # Check for broken links
    just docs::check-links

### Cleanup

    # Remove build artifacts
    just docs::clean

### View All Documentation Commands

    just docs::help

## 📦 Installing mdBook

mdBook is required to build and serve the documentation.

### Install via Cargo

    cargo install mdbook

### Install Optional Tools

For enhanced functionality:

    # Link checker (validates internal/external links)
    cargo install mdbook-linkcheck

    # Mermaid diagram support
    cargo install mdbook-mermaid

    # PlantUML diagram support
    cargo install mdbook-plantuml

### Verify Installation

    mdbook --version
    # Should output: mdbook v0.4.x or later

## 📖 Documentation Structure

The documentation is organized into the following sections:

### 1. KOGRAL Definition (`kogral/`)

- What is KOGRAL and why it exists
- Core concepts (nodes, edges, graphs)
- Design philosophy

### 2. Guides (`guides/`)

- Quick start (5 minutes)
- Installation guide
- Use cases with examples

### 3. Architecture (`architecture/`)

- System overview with diagrams
- Config-driven architecture
- Graph model details
- ADRs (Architectural Decision Records)

### 4. Setup (`setup/`)

- Initial setup
- Development environment
- Production deployment
- Testing environment
- CI/CD integration

### 5. Configuration (`config/`)

- Configuration overview
- Nickel schema reference
- Runtime configuration
- Environment modes (dev/prod/test)

### 6. Storage (`storage/`)

- Storage architecture (hybrid strategy)
- Filesystem backend
- SurrealDB backend
- In-memory backend
- Sync mechanism

### 7. AI & Embeddings (`ai/`)

- Semantic search
- Embedding providers
- Provider comparison
- Configuration examples

### 8. Templates (`templates/`)

- Template system (Tera)
- Document templates
- Export templates
- Custom templates

### 9. CLI Reference (`cli/`)

- All kb-cli commands
- Common workflows
- Advanced usage
- Troubleshooting

### 10. Apps & Integrations (`apps/`)

- MCP quick guide (Claude Code)
- Logseq integration
- Vapora integration

### 11. API Reference (`api/`)

- MCP tools specification
- Storage trait
- Embedding trait
- REST API (future)

### 12. Contributing (`contributing/`)

- Development setup
- Code guidelines
- Testing standards
- Documentation guidelines

## 🎨 Visual Diagrams

The documentation includes SVG diagrams for visual understanding:

- architecture-overview.svg - Complete system architecture
- core-concepts.svg - Node types and relationships
- config-composition.svg - Configuration flow (Nickel → JSON → Rust)
- storage-architecture.svg - Hybrid storage strategy

These diagrams are embedded in relevant documentation pages and can be viewed standalone in a browser.

## 🔍 Searching the Documentation

When using `just docs::serve`, you get a built-in search feature:

1. Click the search icon (🔍) in the top-left corner
2. Type your query
3. Press Enter to navigate results

The search indexes all documentation content including:

- Page titles
- Headers
- Body text
- Code examples (optionally)

## ✏️ Editing Documentation

### File Format

All documentation is written in GitHub Flavored Markdown with mdBook extensions.

See contributing/documentation.md for detailed editing guidelines.

### Adding a New Page

1. Create the markdown file in the appropriate directory
2. Add it to `SUMMARY.md` for navigation
3. Build to verify: `just docs::build`

### Adding a New Section

1. Create the directory
2. Add a `README.md` for the section landing page
3. Add section to `SUMMARY.md`

## 🧪 Testing Documentation

### Test Code Examples

    just docs::test

This runs all Rust code examples in the documentation to ensure they compile.

### Check Links

    just docs::check-links

This validates all internal and external links.

## 📝 Documentation Standards

When contributing to documentation:

1. Use clear, concise language - Write for developers and AI agents
2. Include code examples - Show, don't just tell
3. Add diagrams where helpful - Visual aids improve understanding
4. Link related concepts - Help readers discover related content
5. Test code examples - Ensure code compiles and works
6. Use consistent formatting - Follow existing page structure
7. Update SUMMARY.md - New pages must be in navigation
8. Run checks before committing:

    just docs::build
    just docs::test
    just docs::check-links

## 💡 Tips

### Live Reload While Writing

    just docs::watch

This watches for changes and rebuilds automatically. Open http://localhost:3000 in your browser to see updates in real-time.

### Markdown Preview in Editor

Most editors have Markdown preview:

- VS Code: `Ctrl+Shift+V` (Cmd+Shift+V on Mac)
- IntelliJ/CLion: Preview pane (right side)
- Vim/Neovim: Use plugins like `markdown-preview.nvim`

### Quick Reference

- SUMMARY.md - Table of contents (edit to add/remove pages)
- book.toml - mdBook configuration
- theme/ - Custom CSS/JS (if needed)
- diagrams/ - SVG diagrams

## 🐛 Troubleshooting

### mdbook command not found

    # Install mdBook
    cargo install mdbook

    # Verify installation
    mdbook --version

### Port 3000 already in use

    # Serve on different port
    cd docs
    mdbook serve --port 3001

### Links broken after moving files

    # Check all links
    just docs::check-links

    # Update internal links in affected files
    # Then rebuild
    just docs::build

## 📚 Resources

- mdBook User Guide
- GitHub Flavored Markdown Spec
- Markdown Guide

## 🤝 Contributing to Documentation

Documentation improvements are always welcome! To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with `just docs::build` and `just docs::test`
5. Submit a pull request

See contributing/documentation.md for detailed guidelines.

Happy documenting! 📖

If you have questions or need help, please open an issue or reach out to the maintainers.