kogral/docs/guides/quickstart.md

# Quick Start Guide

Get up and running with the KOGRAL in 5 minutes.

## Prerequisites

- Rust 1.70+ installed
- Nickel CLI installed (`cargo install nickel-lang-cli`)
- kogral-cli installed (see [Installation](../installation.md))

## Step 1: Initialize Your Knowledge Base

Navigate to your project directory and initialize:

```bash
cd /path/to/your/project
kogral init
```

This creates a `.kogral/` directory with the following structure:

```text
.kogral/
├── config.toml       # Configuration
├── notes/            # General notes
├── decisions/        # Architectural decisions
├── guidelines/       # Project guidelines
├── patterns/         # Reusable patterns
└── journal/          # Daily journal entries
```

## Step 2: Create Your First Note

Add a note to your knowledge base:

```bash
kogral add note "Getting Started with Rust" \
  --tags rust,programming,learning \
  --content "Key concepts for learning Rust effectively."
```

Or create interactively:

```bash
kogral add note
# Follow the prompts to enter title, tags, and content
```

## Step 3: Create a Decision Record

Document an architectural decision:

```bash
kogral add decision "Use SurrealDB for Storage" \
  --context "Need scalable storage for knowledge graph" \
  --decision "Adopt SurrealDB for its graph capabilities" \
  --consequence "Better query performance" \
  --consequence "Additional infrastructure dependency"
```

## Step 4: Link Nodes Together

Create relationships between nodes:

```bash
# Find node IDs
kogral list

# Create a relationship
kogral link <note-id> <decision-id> relates_to
```

Available relationship types:
- `relates_to` - General conceptual link
- `depends_on` - Dependency relationship
- `implements` - Implementation of a concept
- `extends` - Inheritance/extension
- `supersedes` - Replaces older version
- `explains` - Documentation/clarification

## Step 5: Search Your Knowledge Base

Search by text:

```bash
# Simple search
kogral search "rust"

# Filter by type
kogral search "architecture" --type decision

# Limit results
kogral search "error handling" --limit 5
```

Search semantically (requires embeddings):

```bash
# Semantic search finds conceptually related content
kogral search "memory safety" --semantic --threshold 0.7
```

## Step 6: View Node Details

```bash
# Show node by ID
kogral show <node-id>

# Show node with relationships
kogral show <node-id> --with-relationships
```

## Step 7: Edit Documents Directly

All knowledge base documents are markdown files you can edit:

```bash
# Open in your editor
$EDITOR .kogral/notes/getting-started-with-rust.md

# Or use your favorite markdown editor
code .kogral/notes/
```

Document format:

```markdown
---
id: unique-id
type: note
title: Getting Started with Rust
created: 2026-01-17T10:30:00Z
modified: 2026-01-17T10:30:00Z
tags: [rust, programming, learning]
status: active
---

# Getting Started with Rust

Content goes here with [[wikilinks]] to other nodes.

## Key Concepts

- Ownership
- Borrowing
- Lifetimes
```

## Step 8: Create a Daily Journal Entry

Start journaling your development progress:

```bash
kogral add journal "Today's Progress" \
  --content "Learned about trait objects and dynamic dispatch in Rust."
```

Or open today's journal directly:

```bash
$EDITOR .kogral/journal/$(date +%Y-%m-%d).md
```

## Step 9: Export to Logseq (Optional)

If you use Logseq, export your knowledge base:

```bash
nu scripts/kogral-export-logseq.nu /path/to/logseq-graph
```

This creates a Logseq-compatible graph you can open in Logseq for visual editing.

## Step 10: Start MCP Server for Claude Code

Integrate with Claude Code for AI-assisted knowledge management:

```bash
# Start MCP server
kogral serve

# Configure in ~/.config/claude/config.json
# Then use in Claude Code:
# > kogral/search "rust ownership"
```

## Common Workflows

### Capture Quick Notes

```bash
# Quick note
kogral add note "Remember to check error handling in parser module" --tags todo,parser
```

### Document Architectural Decisions

```bash
# Create ADR
kogral add decision "Adopt Async Rust for I/O Operations" \
  --status accepted \
  --tags architecture,async
```

### Build a Pattern Library

```bash
# Add a pattern
kogral add pattern "Error Handling with thiserror" \
  --tags rust,error-handling \
  --content "Standard pattern for error types in this project."
```

### Track Daily Progress

```bash
# Add journal entry
kogral add journal --content "Implemented search functionality. Need to add semantic search next."
```

## Next Steps

### Customize Configuration

Edit `.kogral/config.ncl` for advanced configuration:

```nickel
{
  graph = {
    name = "My Project",
    version = "1.0.0",
  },

  embeddings = {
    enabled = true,
    provider = 'fastembed,
  },

  templates = {
    templates_dir = "templates",
  },
}
```

See [Configuration Reference](configuration.md) for all options.

### Set Up Shared Guidelines

Create a shared knowledge base for organization-wide standards:

```bash
# Create shared KOGRAL
mkdir -p ~/Tools/.kogral-shared
cd ~/Tools/.kogral-shared
kogral init --name "Shared Guidelines"

# Add guidelines
kogral add guideline "Rust Error Handling" \
  --language rust \
  --category error-handling

# Configure inheritance in projects
kogral config set inheritance.base ~/Tools/.kogral-shared
```

### Automate with NuShell Scripts

```bash
# Backup regularly
nu scripts/kogral-backup.nu --compress

# Sync with SurrealDB
nu scripts/kogral-sync.nu --direction bidirectional

# Generate statistics
nu scripts/kogral-stats.nu --show-tags
```

### Integrate with Git

```bash
# Add to version control
git add .kogral/
git commit -m "docs: Add knowledge base"

# Add to .gitignore (optional: exclude certain types)
echo ".kogral/journal/" >> .gitignore
```

## Tips and Tricks

### Use Wikilinks

Link to other nodes naturally in markdown:

```markdown
See [[getting-started-with-rust]] for basics.
Related decision: [[use-surrealdb-for-storage]].
```

### Reference Code

Link to specific code locations:

```markdown
Error handling implementation: @src/parser.rs:42
```

### Tag Consistently

Use consistent tagging for better searchability:

```bash
# Good tagging
--tags rust,error-handling,pattern

# Avoid
--tags Rust,ErrorHandling,patterns
```

### Leverage Templates

Customize templates for your workflow:

```bash
# Copy template
cp templates/note.md.tera templates/meeting-notes.md.tera

# Edit for meeting notes format
$EDITOR templates/meeting-notes.md.tera
```

## Troubleshooting

### "KB directory not found"

```bash
# Make sure you initialized
kogral init

# Or specify KB directory
kogral --kogral-dir /path/to/.kb search "query"
```

### "Node not found"

```bash
# List all nodes to find ID
kogral list

# Search for node
kogral search "partial title"
```

### "Failed to parse frontmatter"

Check your markdown file has valid YAML frontmatter:

```yaml
---
id: my-note
type: note
title: My Note
---
```

## Further Reading

- [Configuration Reference](configuration.md) - Full configuration options
- [CLI Commands](cli-commands.md) - All available commands
- [Document Format](document-format.md) - Markdown and frontmatter details
- [MCP Tools](../api/mcp-tools.md) - Claude Code integration

## Getting Help

- Check `kogral --help` for command usage
- Read inline help: `kogral add --help`
- Report issues on GitHub
- Join community discussions

---

**Congratulations!** You've created your first knowledge base. Start capturing knowledge and building connections.