kogral/CHANGELOG.md

# Changelog

All notable changes to the Knowledge Base project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Changed

#### BREAKING: MCP Protocol Rebranding
- **All MCP URIs, tool names, and prompts updated to KOGRAL namespace**
  - **URI Scheme**: `kb://` → `kogral://`
    - `kb://project/notes` → `kogral://project/notes`
    - `kb://project/decisions` → `kogral://project/decisions`
    - `kb://project/guidelines` → `kogral://project/guidelines`
    - `kb://project/patterns` → `kogral://project/patterns`
    - `kb://shared/guidelines` → `kogral://shared/guidelines`
    - `kb://shared/patterns` → `kogral://shared/patterns`
  - **Tool Names**: `kb/*` → `kogral/*`
    - `kb/search` → `kogral/search`
    - `kb/add_note` → `kogral/add_note`
    - `kb/add_decision` → `kogral/add_decision`
    - `kb/link` → `kogral/link`
    - `kb/get_guidelines` → `kogral/get_guidelines`
    - `kb/list_graphs` → `kogral/list_graphs`
    - `kb/export` → `kogral/export`
    - `kb/find_blocks` → `kogral/find_blocks`
    - `kb/find_todos` → `kogral/find_todos`
    - `kb/find_cards` → `kogral/find_cards`
  - **Prompt Names**: `kb/*` → `kogral/*`
    - `kb/summarize_project` → `kogral/summarize_project`
    - `kb/find_related` → `kogral/find_related`
  - **Server Name**: `kb-mcp` → `kogral-mcp`
  - **Migration Required**: Users must update `~/.config/claude/config.json`:

    ```diff
    {
      "mcpServers": {
    -   "kb-mcp": {
    -     "command": "/path/to/kb-mcp",
    +   "kogral-mcp": {
    +     "command": "/path/to/kogral-mcp",
    -       "env": { "KB_DIR": "/path/to/.kb" }
    +       "env": { "KOGRAL_DIR": "/path/to/.kogral" }
        }
      }
    }
    ```

  - **Rationale**: Complete branding consistency across all interfaces. Pre-release status (v0.x) allows breaking changes without user pain.
  - **Files updated**:
    - `crates/kb-mcp/src/resources.rs`: All URI definitions and parsing
    - `crates/kb-mcp/src/tools.rs`: All tool name definitions and dispatch
    - `crates/kb-mcp/src/prompts.rs`: All prompt name definitions and dispatch
    - `crates/kb-mcp/src/main.rs`: Server name registration
    - `crates/kb-mcp/tests/integration_test.rs`: Test assertions updated
    - `docs/apps/mcp-quickguide.md`: All examples and references
    - `docs/kogral/core-concepts.md`: MCP protocol documentation
    - `docs/api/mcp-tools.md`: API reference documentation
    - `README.md`: MCP integration examples

#### Branding
- **Rebranded to KOGRAL** (**KO**wledge **GRA**phs, **L**ocal-first)
  - Updated project name from "Knowledge Base" to "KOGRAL" across all documentation
  - New tagline: "Git-native knowledge graphs for developer teams"
  - Updated description emphasizing structured knowledge management for developers
  - Documentation folder renamed: `docs/kb/` → `docs/kogral/`
  - Documentation files renamed:
    - `docs/kogral/what-is-kb.md` → `what-is-kogral.md`
    - `docs/kogral/why-kb.md` → `why-kogral.md`
  - Technical names maintained for compatibility: `kb-core`, `kb-cli`, `kb-mcp` (crate names), `kb` (CLI binary)
  - Hybrid naming strategy: KOGRAL as primary brand, `kb.vapora.dev` as future alias
  - Files updated:
    - `README.md`: Title, description, and branding
    - `Cargo.toml` (workspace): Homepage, description, repository metadata
    - `crates/kb-core/Cargo.toml`: Package description
    - `crates/kb-cli/Cargo.toml`: Package description
    - `crates/kb-mcp/Cargo.toml`: Package description
    - `crates/kb-core/src/lib.rs`: Module documentation comments
    - `crates/kb-core/src/models.rs`: Type documentation comments
    - `crates/kb-cli/src/main.rs`: CLI description and messages
    - `docs/kogral/what-is-kogral.md`: Full KOGRAL branding with acronym explanation
    - `docs/kogral/core-concepts.md`: All "KB" references replaced with "KOGRAL"
    - `docs/README.md`: Title and section headers
    - `docs/book.toml`: mdBook title and description
    - `docs/SUMMARY.md`: Navigation titles
    - `.claude/CLAUDE.md`: Project description and documentation links

#### BREAKING: Filesystem Paths and Environment Variables
- **Directory structure renamed from `.kb/` to `.kogral/`**
  - Project directory: `.kb/` → `.kogral/`
  - Shared directory: `.kb-shared/` → `.kogral-shared/`
  - Configuration paths updated throughout codebase
  - All storage paths use `.kogral/` prefix
- **Environment variable renamed from `KB_DIR` to `KOGRAL_DIR`**
  - MCP server configuration requires `KOGRAL_DIR` environment variable
  - CLI tools respect `KOGRAL_DIR` for custom directory location
- **Migration Required**:
  1. Rename existing directory: `mv .kb .kogral`
  2. Update environment variables: `KB_DIR` → `KOGRAL_DIR`
  3. Update config files referencing `.kb/` paths
- **Rationale**: Complete branding consistency across all filesystem operations. Pre-release status allows breaking changes.
- **Files updated**:
  - All Rust source files in `crates/`: Path constants and variable names
  - `crates/kb-core/src/config/loader.rs`: Configuration path discovery
  - `crates/kb-core/src/storage/filesystem.rs`: Storage paths
  - `crates/kb-cli/src/main.rs`: CLI messages and examples
  - `crates/kb-mcp/src/main.rs`: Environment variable handling
  - All documentation in `docs/`: Examples and instructions
  - `README.md`: Setup and usage examples
  - `.claude/CLAUDE.md`: Project configuration paths

### Added

#### Core Infrastructure
- Initial project structure with Cargo workspace (kb-core, kb-cli, kb-mcp)
- Core graph models (Node, Edge, Graph) with 6 node types and 6 relationship types
- Config-driven architecture using Nickel schemas (NCL → JSON → Rust)
- Markdown parser with Logseq compatibility (YAML frontmatter + wikilinks)
- Storage backends: Filesystem (default), In-Memory, SurrealDB (feature-gated)
- Embedding integration via rig-core (OpenAI, Claude, Ollama) + fastembed local fallback
- Tera template engine for document generation and export

#### Logseq Blocks Support (ADR-004)
- **Block Data Structures** (`crates/kb-core/src/models.rs`):
  - `TaskStatus` enum: TODO, DOING, DONE, LATER, NOW, WAITING, CANCELLED
  - `BlockProperties` struct: tags, task status, custom properties, block/page references
  - `Block` struct: hierarchical content blocks with properties and children
  - `Node.blocks` field: Optional cached block structure (lazy parsing)
- **BlockParser** (`crates/kb-core/src/block_parser.rs`):
  - Bidirectional parser: Markdown outliner ↔ Block structures
  - Supports: task markers, #tags, custom properties (key:: value), ((block-refs)), [[page-refs]]
  - Hierarchical parsing based on indentation
  - Round-trip fidelity for Logseq import/export
  - 15 comprehensive tests covering parsing, serialization, and round-trips
- **Block Query API**:
  - `Node::get_blocks()`: Lazy parsing from content with caching
  - `Node::find_blocks_by_tag()`: Find blocks with specific tag
  - `Node::find_all_todos()`: Find all task blocks
  - `Node::find_blocks_by_status()`: Find blocks by task status
  - `Node::find_blocks_by_property()`: Find blocks with custom property
  - `Graph::find_blocks_by_tag()`: Search blocks across all nodes
  - `Graph::find_all_todos()`: Find TODOs across entire graph
  - 6 integration tests for Node and Graph block queries
- **SurrealDB Schema** (`schemas/surrealdb/blocks.surql`):
  - `block` table with indexes on node_id, block_id, tags, status, parent_id
  - Full-text search index on content
  - Support for hierarchical queries and tag-based filtering
  - Migration queries and example usage patterns
- **Logseq Import/Export** (`crates/kb-core/src/import/logseq.rs`, `crates/kb-core/src/export/logseq.rs`):
  - Round-trip import: Logseq markdown → KB Node with blocks
  - Property parsing: key:: value format, tags ([[tag]] and #tag), references, timestamps
  - Export to Logseq page/journal formats with block serialization
  - 12 comprehensive tests covering import/export round-trips
- **MCP Block Tools** (`crates/kb-mcp/src/tools.rs`):
  - `kb/find_blocks`: Search blocks by tag, task status, or custom property
  - `kb/find_todos`: Find all TODO blocks across KB
  - `kb/find_cards`: Find all flashcard blocks (#card tag)
  - Fixed borrowing issues with two-phase data collection pattern
- **Configuration Schema** (`schemas/kb-config.ncl`, `config/*.ncl`):
  - Added `BlocksConfig` schema with 4 settings:
    - `enabled`: Enable/disable Logseq blocks parsing (default: false, opt-in)
    - `parse_on_import`: Auto-parse blocks from Logseq imports (default: true)
    - `serialize_on_export`: Serialize blocks to outliner format on export (default: true)
    - `enable_mcp_tools`: Enable block-related MCP tools (default: true)
  - Updated all config files (defaults.ncl, production.ncl, minimal.ncl)
  - Validated: All configs export to JSON successfully
- **Documentation**:
  - Complete technical design: `docs/architecture/logseq-blocks-design.md`
  - Architectural Decision Record: `docs/architecture/adrs/004-logseq-blocks-support.md`
  - 6-phase implementation plan documented
  - Use cases and examples for flashcards, task tracking, and block references

#### Applications
- CLI tool (kb-cli) with 13 commands (init, add, search, link, sync, serve, etc.)
- MCP server (kb-mcp) with 10 tools (7 core + 3 block tools), 6 resources, 2 prompts for Claude Code integration
- NuShell maintenance scripts (6 scripts: sync, backup, reindex, import/export Logseq, stats)

#### Configuration System (Nickel)
- Complete Nickel configuration schema following typedialog/provisioning pattern
- Schema contracts (`schemas/kb/contracts.ncl`) - Type definitions with validation
- Default values (`schemas/kb/defaults.ncl`) - Base configuration values
- Composition helpers (`schemas/kb/helpers.ncl`) - merge_with_override, compose_config
- Mode overlays (`schemas/kb/modes/{dev,prod,test}.ncl`) - Environment-specific tuning
- Runtime configurations (`.kb-config/core/kb.ncl`, `.kb-config/platform/*.ncl`)
- Double validation pattern: Nickel contracts + serde deserialization
- Config export to JSON for Rust consumption (`.kb-config/targets/*.json`)

#### Templates
- Tera templates for 6 document types (note, decision, guideline, pattern, journal, execution)
- 4 export format templates (Logseq page/journal, summary, JSON)
- Customizable template system with frontmatter generation

#### Documentation (mdBook)
- Complete mdBook documentation structure with SUMMARY.md navigation
- 4 SVG diagrams for visual guides:
  - `architecture-overview.svg` - Complete system architecture
  - `core-concepts.svg` - Node types and relationships
  - `config-composition.svg` - Configuration flow (Schema → Defaults → Mode → User → JSON)
  - `storage-architecture.svg` - Hybrid storage strategy
- 11 major documentation sections (kb/, guides/, architecture/, setup/, config/, storage/, ai/, templates/, cli/, apps/, api/, contributing/)
- ADR documentation (ADR-001: Nickel vs TOML, ADR-002: FastEmbed + AI providers, ADR-003: Hybrid storage)
- Use cases documentation (8 real-world scenarios)
- MCP quick guide (5-minute setup for Claude Code)
- Config-driven architecture deep dive
- Storage architecture deep dive with code examples
- docs/README.md - Comprehensive guide for using and building documentation

#### Build System
- Modular justfile system (7 modules: build, test, dev, ci, nickel, docs, scripts)
- Nickel validation and export recipes (`just nickel::validate-all`, `just nickel::export-all`)
- mdBook documentation recipes (`just docs::serve`, `just docs::build`, `just docs::test`)
- CI/CD pipeline recipes (format, lint, test, build validation)
- NuShell script validation and execution recipes

#### Project Documentation
- Enhanced README.md with complete documentation links and visual diagram references
- Directory structure documentation with detailed explanations
- Quick start guide with MCP integration
- Integration guides (Vapora, Logseq, Claude Code)
- CHANGELOG.md following Keep a Changelog format

### Changed
- Updated README.md with comprehensive documentation links (mdBook, guides, architecture, config)
- Enhanced directory structure documentation with .kb-config/ and schemas/kb/ details
- Improved documentation section with visual diagrams and just recipe references
- **Blocks Feature Documentation**:
  - README.md: Added Logseq blocks section with examples, features, and configuration
  - README.md: Updated architecture diagram to include BlockParser
  - README.md: Added 3 new MCP tools to integration section
  - docs/kb/core-concepts.md: Added comprehensive "Logseq Content Blocks" section with examples, use cases, and queries
  - docs/api/mcp-tools.md: Added "Block Tools" section documenting kb/find_blocks, kb/find_todos, kb/find_cards
  - docs/api/mcp-tools.md: Updated overview from 7 to 10 tools

### Infrastructure
- Cargo workspace with 3 crates
- Feature flags: `filesystem` (default), `surrealdb`, `fastembed`, `full`
- 90 tests across workspace (81 kb-core + 5 kb-mcp + 4 kb-cli)
  - 15 tests for block parser
  - 12 tests for Logseq import/export
  - 6 tests for block queries
- mdBook integration for documentation (serves on [http://localhost:3000](http://localhost:3000))
- Nickel → JSON → Rust configuration pipeline
- Justfile modules: build, test, dev, ci, nickel, docs, scripts
- CI/CD pipeline recipes (format, lint, test, build validation)
- mdBook documentation structure with SUMMARY.md
- NuShell script validation recipes

## [1.0.0] - TBD

Initial release (planned).

### Planned Features
- Full FilesystemStorage implementation with file watching
- Complete Query Engine with semantic search
- Guideline inheritance resolution (shared → local override priority)
- SurrealDB schema and complete backend implementation
- Sync mechanism: bidirectional Filesystem ↔ SurrealDB
- FastEmbed local embeddings integration
- API provider integrations (OpenAI, Claude, Ollama) for embeddings
- Cross-graph queries (project + shared knowledge bases)
- Template customization system
- Export to multiple formats (Logseq, JSON, Markdown)
- Import from Logseq graphs
- MCP protocol compliance testing
- Production-ready CLI tool
- Performance benchmarks
- Security audit

---

## Version History

### Version Numbering

This project follows semantic versioning (MAJOR.MINOR.PATCH):

- **MAJOR**: Incompatible API changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)

### Release Schedule

- **Alpha** (0.x.x): API unstable, features incomplete
- **Beta** (1.0.0-beta.x): API stable, features complete, testing phase
- **Stable** (1.0.0+): Production ready

### Feature Roadmap

#### Phase 1: Foundation ✅ (Completed)
- [x] Core models and graph structure
- [x] Nickel configuration system
- [x] Markdown parser with Logseq compatibility
- [x] Storage trait abstraction
- [x] CLI structure with clap
- [x] MCP server protocol implementation
- [x] NuShell maintenance scripts
- [x] Documentation structure

#### Phase 2: Integration (In Progress)
- [ ] Full FilesystemStorage with file watching
- [ ] SurrealDB backend implementation
- [ ] Query engine with text + semantic search
- [ ] Embedding provider integrations
- [ ] Guideline inheritance resolution
- [ ] Sync mechanism implementation

#### Phase 3: Polish (Planned)
- [ ] Performance optimization
- [ ] Comprehensive error handling
- [ ] Production testing
- [ ] Security audit
- [ ] API stabilization
- [ ] Release preparation

---

## Migration Guides

### Upgrading from 0.x to 1.0

(To be documented when 1.0 is released)

---

## Contributing

See [CONTRIBUTING.md](docs/contributing/development.md) for development setup and guidelines.

---

## License

(To be determined)