jesus/kogral
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
kogral/docs/book/guides/quickstart.html

496 lines
22 KiB
HTML
Raw Normal View History

chore: add docs
2026-01-23 16:11:07 +00:00
<!DOCTYPE HTML>
<html lang="en" class="rust sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Quick Start - KOGRAL Documentation</title>
<!-- Custom HTML head -->
<meta name="description" content="Complete documentation for KOGRAL - Git-native knowledge graphs for developer teams">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="../favicon.svg">
<link rel="shortcut icon" href="../favicon.png">
<link rel="stylesheet" href="../css/variables.css">
<link rel="stylesheet" href="../css/general.css">
<link rel="stylesheet" href="../css/chrome.css">
<link rel="stylesheet" href="../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "rust";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('rust')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">KOGRAL Documentation</h1>
<div class="right-buttons">
<a href="../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/your-org/knowledge-base" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
<a href="https://github.com/your-org/knowledge-base/edit/main/docs/./guides/quickstart.md" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="quick-start-guide"><a class="header" href="#quick-start-guide">Quick Start Guide</a></h1>
<p>Get up and running with the KOGRAL in 5 minutes.</p>
<h2 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h2>
<ul>
<li>Rust 1.70+ installed</li>
<li>Nickel CLI installed (<code>cargo install nickel-lang-cli</code>)</li>
<li>kb-cli installed (see <a href="../installation.html">Installation</a>)</li>
</ul>
<h2 id="step-1-initialize-your-knowledge-base"><a class="header" href="#step-1-initialize-your-knowledge-base">Step 1: Initialize Your Knowledge Base</a></h2>
<p>Navigate to your project directory and initialize:</p>
<pre><code class="language-bash">cd /path/to/your/project
kb init
</code></pre>
<p>This creates a <code>.kogral/</code> directory with the following structure:</p>
<pre><code>.kogral/
├── config.toml # Configuration
├── notes/ # General notes
├── decisions/ # Architectural decisions
├── guidelines/ # Project guidelines
├── patterns/ # Reusable patterns
└── journal/ # Daily journal entries
</code></pre>
<h2 id="step-2-create-your-first-note"><a class="header" href="#step-2-create-your-first-note">Step 2: Create Your First Note</a></h2>
<p>Add a note to your knowledge base:</p>
<pre><code class="language-bash">kb add note "Getting Started with Rust" \
--tags rust,programming,learning \
--content "Key concepts for learning Rust effectively."
</code></pre>
<p>Or create interactively:</p>
<pre><code class="language-bash">kb add note
# Follow the prompts to enter title, tags, and content
</code></pre>
<h2 id="step-3-create-a-decision-record"><a class="header" href="#step-3-create-a-decision-record">Step 3: Create a Decision Record</a></h2>
<p>Document an architectural decision:</p>
<pre><code class="language-bash">kb 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"
</code></pre>
<h2 id="step-4-link-nodes-together"><a class="header" href="#step-4-link-nodes-together">Step 4: Link Nodes Together</a></h2>
<p>Create relationships between nodes:</p>
<pre><code class="language-bash"># Find node IDs
kb list
# Create a relationship
kb link &lt;note-id&gt; &lt;decision-id&gt; relates_to
</code></pre>
<p>Available relationship types:</p>
<ul>
<li><code>relates_to</code> - General conceptual link</li>
<li><code>depends_on</code> - Dependency relationship</li>
<li><code>implements</code> - Implementation of a concept</li>
<li><code>extends</code> - Inheritance/extension</li>
<li><code>supersedes</code> - Replaces older version</li>
<li><code>explains</code> - Documentation/clarification</li>
</ul>
<h2 id="step-5-search-your-knowledge-base"><a class="header" href="#step-5-search-your-knowledge-base">Step 5: Search Your Knowledge Base</a></h2>
<p>Search by text:</p>
<pre><code class="language-bash"># Simple search
kb search "rust"
# Filter by type
kb search "architecture" --type decision
# Limit results
kb search "error handling" --limit 5
</code></pre>
<p>Search semantically (requires embeddings):</p>
<pre><code class="language-bash"># Semantic search finds conceptually related content
kb search "memory safety" --semantic --threshold 0.7
</code></pre>
<h2 id="step-6-view-node-details"><a class="header" href="#step-6-view-node-details">Step 6: View Node Details</a></h2>
<pre><code class="language-bash"># Show node by ID
kb show &lt;node-id&gt;
# Show node with relationships
kb show &lt;node-id&gt; --with-relationships
</code></pre>
<h2 id="step-7-edit-documents-directly"><a class="header" href="#step-7-edit-documents-directly">Step 7: Edit Documents Directly</a></h2>
<p>All knowledge base documents are markdown files you can edit:</p>
<pre><code class="language-bash"># Open in your editor
$EDITOR .kogral/notes/getting-started-with-rust.md
# Or use your favorite markdown editor
code .kogral/notes/
</code></pre>
<p>Document format:</p>
<pre><code class="language-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
</code></pre>
<h2 id="step-8-create-a-daily-journal-entry"><a class="header" href="#step-8-create-a-daily-journal-entry">Step 8: Create a Daily Journal Entry</a></h2>
<p>Start journaling your development progress:</p>
<pre><code class="language-bash">kb add journal "Today's Progress" \
--content "Learned about trait objects and dynamic dispatch in Rust."
</code></pre>
<p>Or open today's journal directly:</p>
<pre><code class="language-bash">$EDITOR .kogral/journal/$(date +%Y-%m-%d).md
</code></pre>
<h2 id="step-9-export-to-logseq-optional"><a class="header" href="#step-9-export-to-logseq-optional">Step 9: Export to Logseq (Optional)</a></h2>
<p>If you use Logseq, export your knowledge base:</p>
<pre><code class="language-bash">nu scripts/kb-export-logseq.nu /path/to/logseq-graph
</code></pre>
<p>This creates a Logseq-compatible graph you can open in Logseq for visual editing.</p>
<h2 id="step-10-start-mcp-server-for-claude-code"><a class="header" href="#step-10-start-mcp-server-for-claude-code">Step 10: Start MCP Server for Claude Code</a></h2>
<p>Integrate with Claude Code for AI-assisted knowledge management:</p>
<pre><code class="language-bash"># Start MCP server
kb serve
# Configure in ~/.config/claude/config.json
# Then use in Claude Code:
# &gt; kb/search "rust ownership"
</code></pre>
<h2 id="common-workflows"><a class="header" href="#common-workflows">Common Workflows</a></h2>
<h3 id="capture-quick-notes"><a class="header" href="#capture-quick-notes">Capture Quick Notes</a></h3>
<pre><code class="language-bash"># Quick note
kb add note "Remember to check error handling in parser module" --tags todo,parser
</code></pre>
<h3 id="document-architectural-decisions"><a class="header" href="#document-architectural-decisions">Document Architectural Decisions</a></h3>
<pre><code class="language-bash"># Create ADR
kb add decision "Adopt Async Rust for I/O Operations" \
--status accepted \
--tags architecture,async
</code></pre>
<h3 id="build-a-pattern-library"><a class="header" href="#build-a-pattern-library">Build a Pattern Library</a></h3>
<pre><code class="language-bash"># Add a pattern
kb add pattern "Error Handling with thiserror" \
--tags rust,error-handling \
--content "Standard pattern for error types in this project."
</code></pre>
<h3 id="track-daily-progress"><a class="header" href="#track-daily-progress">Track Daily Progress</a></h3>
<pre><code class="language-bash"># Add journal entry
kb add journal --content "Implemented search functionality. Need to add semantic search next."
</code></pre>
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
<h3 id="customize-configuration"><a class="header" href="#customize-configuration">Customize Configuration</a></h3>
<p>Edit <code>.kogral/config.ncl</code> for advanced configuration:</p>
<pre><code class="language-nickel">{
graph = {
name = "My Project",
version = "1.0.0",
},
embeddings = {
enabled = true,
provider = 'fastembed,
},
templates = {
templates_dir = "templates",
},
}
</code></pre>
<p>See <a href="configuration.html">Configuration Reference</a> for all options.</p>
<h3 id="set-up-shared-guidelines"><a class="header" href="#set-up-shared-guidelines">Set Up Shared Guidelines</a></h3>
<p>Create a shared knowledge base for organization-wide standards:</p>
<pre><code class="language-bash"># Create shared KB
mkdir -p ~/Tools/.kogral-shared
cd ~/Tools/.kogral-shared
kb init --name "Shared Guidelines"
# Add guidelines
kb add guideline "Rust Error Handling" \
--language rust \
--category error-handling
# Configure inheritance in projects
kb config set inheritance.base ~/Tools/.kogral-shared
</code></pre>
<h3 id="automate-with-nushell-scripts"><a class="header" href="#automate-with-nushell-scripts">Automate with NuShell Scripts</a></h3>
<pre><code class="language-bash"># Backup regularly
nu scripts/kb-backup.nu --compress
# Sync with SurrealDB
nu scripts/kb-sync.nu --direction bidirectional
# Generate statistics
nu scripts/kb-stats.nu --show-tags
</code></pre>
<h3 id="integrate-with-git"><a class="header" href="#integrate-with-git">Integrate with Git</a></h3>
<pre><code class="language-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/" &gt;&gt; .gitignore
</code></pre>
<h2 id="tips-and-tricks"><a class="header" href="#tips-and-tricks">Tips and Tricks</a></h2>
<h3 id="use-wikilinks"><a class="header" href="#use-wikilinks">Use Wikilinks</a></h3>
<p>Link to other nodes naturally in markdown:</p>
<pre><code class="language-markdown">See [[getting-started-with-rust]] for basics.
Related decision: [[use-surrealdb-for-storage]].
</code></pre>
<h3 id="reference-code"><a class="header" href="#reference-code">Reference Code</a></h3>
<p>Link to specific code locations:</p>
<pre><code class="language-markdown">Error handling implementation: @src/parser.rs:42
</code></pre>
<h3 id="tag-consistently"><a class="header" href="#tag-consistently">Tag Consistently</a></h3>
<p>Use consistent tagging for better searchability:</p>
<pre><code class="language-bash"># Good tagging
--tags rust,error-handling,pattern
# Avoid
--tags Rust,ErrorHandling,patterns
</code></pre>
<h3 id="leverage-templates"><a class="header" href="#leverage-templates">Leverage Templates</a></h3>
<p>Customize templates for your workflow:</p>
<pre><code class="language-bash"># Copy template
cp templates/note.md.tera templates/meeting-notes.md.tera
# Edit for meeting notes format
$EDITOR templates/meeting-notes.md.tera
</code></pre>
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
<h3 id="kb-directory-not-found"><a class="header" href="#kb-directory-not-found">"KB directory not found"</a></h3>
<pre><code class="language-bash"># Make sure you initialized
kb init
# Or specify KB directory
kb --kb-dir /path/to/.kb search "query"
</code></pre>
<h3 id="node-not-found"><a class="header" href="#node-not-found">"Node not found"</a></h3>
<pre><code class="language-bash"># List all nodes to find ID
kb list
# Search for node
kb search "partial title"
</code></pre>
<h3 id="failed-to-parse-frontmatter"><a class="header" href="#failed-to-parse-frontmatter">"Failed to parse frontmatter"</a></h3>
<p>Check your markdown file has valid YAML frontmatter:</p>
<pre><code class="language-yaml">---
id: my-note
type: note
title: My Note
---
</code></pre>
<h2 id="further-reading"><a class="header" href="#further-reading">Further Reading</a></h2>
<ul>
<li><a href="configuration.html">Configuration Reference</a> - Full configuration options</li>
<li><a href="cli-commands.html">CLI Commands</a> - All available commands</li>
<li><a href="document-format.html">Document Format</a> - Markdown and frontmatter details</li>
<li><a href="../api/mcp-tools.html">MCP Tools</a> - Claude Code integration</li>
</ul>
<h2 id="getting-help"><a class="header" href="#getting-help">Getting Help</a></h2>
<ul>
<li>Check <code>kb --help</code> for command usage</li>
<li>Read inline help: <code>kb add --help</code></li>
<li>Report issues on GitHub</li>
<li>Join community discussions</li>
</ul>
<hr />
<p><strong>Congratulations!</strong> You've created your first knowledge base. Start capturing knowledge and building connections.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../guides/installation.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../guides/daily-workflows.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../guides/installation.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../guides/daily-workflows.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>
Reference in New Issue Copy Permalink