# KOGRAL Documentation

<div align="center"> <img src="../assets/kogral-logo.svg" alt="KoGraL Logo" width="600" /> </div>

Welcome to the KOGRAL documentation! This directory contains comprehensive documentation for KOGRAL (**KO**wledge **GRA**phs, **L**ocal-first), built with [mdBook](https://rust-lang.github.io/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:

```bash
# 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:

```bash
# 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](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

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

# Build static HTML
just docs::build

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

### Validation

```bash
# Test code examples in documentation
just docs::test

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

### Cleanup

```bash
# Remove build artifacts
just docs::clean
```

### View All Documentation Commands

```bash
just docs::help
```

## 📦 Installing mdBook

mdBook is required to build and serve the documentation.

### Install via Cargo

```bash
cargo install mdbook
```

### Install Optional Tools

For enhanced functionality:

```bash
# 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

```bash
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 kogral-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](diagrams/architecture-overview.svg)** - Complete system architecture
- **[core-concepts.svg](diagrams/core-concepts.svg)** - Node types and relationships
- **[config-composition.svg](diagrams/config-composition.svg)** - Configuration flow (Nickel → JSON → Rust)
- **[storage-architecture.svg](diagrams/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](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

```bash
just docs::test
```

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

### Check Links

```bash
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**:

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

## 💡 Tips

### Live Reload While Writing

```bash
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

```bash
# Install mdBook
cargo install mdbook

# Verify installation
mdbook --version
```

### Port 3000 already in use

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

### Links broken after moving files

```bash
# Check all links
just docs::check-links

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

## 📚 Resources

- [mdBook User Guide](https://rust-lang.github.io/mdBook/)
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
- [Markdown Guide](https://www.markdownguide.org/)

## 🤝 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](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.