docs: add comprehensive user guide

docs/guide/README.md

@@ -0,0 +1,44 @@
+# khive User Guide
+
+Documentation for using khive as a research knowledge graph runtime.
+
+| Guide                                          | What it covers                                  |
+| ---------------------------------------------- | ----------------------------------------------- |
+| [Getting Started](getting-started.md)          | Install, connect, first session                 |
+| [Knowledge Graph Modeling](knowledge-graph.md) | Entity kinds, edge relations, modeling patterns |
+| [Prompt Cookbook](prompt-cookbook.md)          | 20+ real-world verb patterns with examples      |
+| [Search and Retrieval](search.md)              | FTS, vector, hybrid fusion, reranking           |
+| [Memory and Recall](memory.md)                 | Episodic vs semantic, salience, decay           |
+| [GTD Task Management](tasks.md)                | Task lifecycle, priorities, dependencies        |
+
+## How to read these guides
+
+Each guide is self-contained but cross-references related topics. Start with
+[Getting Started](getting-started.md) if you have never used khive, then read
+[Knowledge Graph Modeling](knowledge-graph.md) for the conceptual foundation.
+
+The [Prompt Cookbook](prompt-cookbook.md) is a reference you return to — it shows
+the exact `request(ops="...")` syntax for every common operation.
+
+## What khive is
+
+khive is a structured persistence layer for AI research agents. It provides a
+typed knowledge graph (8 entity kinds, 15 edge relations, 5 note kinds), hybrid
+search (FTS5 + vector + RRF fusion), GQL/SPARQL queries, task management, agent
+memory with decay-weighted recall, inter-agent messaging, scheduling, and a
+knowledge corpus with reranking.
+
+All interaction goes through a single MCP tool: `request(ops="verb(args)")`.
+
+## What khive is not
+
+khive is not a general-purpose database, a vector DB, or a chat memory system.
+It has opinions: closed taxonomies, a fixed edge ontology, namespace isolation.
+If your data does not fit the schema, reconsider how you model it before
+requesting schema changes.
+
+## Further reading
+
+- [AGENTS.md](../../AGENTS.md) — agent usage reference (verb tables, property conventions, edge density rules)
+- [CLAUDE.md](../../CLAUDE.md) — developer guide for working on khive itself
+- [ADR index](../adr/README.md) — architecture decision records (the design contract)

docs/guide/getting-started.md

@@ -0,0 +1,187 @@
+# Getting Started
+
+This guide walks you from zero to a productive khive session: install the
+binary, connect it to your MCP client, create your first entities, search the
+graph, and link concepts together.
+
+## What khive gives you
+
+khive is a research knowledge graph runtime. When you read papers, form
+concepts, link ideas, record decisions, or track tasks, khive gives that work a
+typed, queryable graph that persists across sessions. Everything is accessible
+through 63 verbs across 7 packs, dispatched through a single MCP tool.
+
+## Install
+
+### From crates.io (Rust)
+
+```bash
+cargo install khive-mcp
+```
+
+### From npm
+
+```bash
+npm install -g khive
+# or
+npm install -g @khive-ai/cli
+```
+
+### From source
+
+```bash
+git clone https://github.com/ohdearquant/khive
+cd khive
+cargo build --workspace --release
+# Binary at crates/target/release/khive-mcp
+```
+
+## Connect to your MCP client
+
+### Claude Code
+
+Add to your MCP configuration (`.claude/settings.json` or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "khive": {
+      "command": "khive-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "khive": {
+      "command": "khive-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+khive auto-spawns a background daemon on first request to keep the ANN index and
+embedding model warm. You do not need to manage this — it starts automatically
+and cleans up on exit.
+
+## The single-tool interface
+
+khive exposes one MCP tool: `request`. Every operation goes through it:
+
+```
+request(ops="verb(arg=value, arg=value)")
+```
+
+This is the only syntax you need. The `ops` string contains a verb call (or a
+batch of them), and khive dispatches it to the appropriate pack handler.
+
+## Your first session
+
+### 1. Create an entity
+
+Entities are the nodes in your knowledge graph. khive has 8 entity kinds:
+`concept`, `document`, `dataset`, `project`, `person`, `org`, `artifact`,
+`service`.
+
+```
+request(ops="create(kind=\"entity\", entity_kind=\"concept\", name=\"FlashAttention\", description=\"IO-aware exact attention algorithm\", properties={domain: \"attention\", year: 2022})")
+```
+
+Response:
+
+```json
+{
+  "ok": true,
+  "result": {
+    "id": "a1b2c3d4",
+    "kind": "concept",
+    "name": "FlashAttention",
+    "description": "IO-aware exact attention algorithm"
+  }
+}
+```
+
+### 2. Create a related entity
+
+```
+request(ops="create(kind=\"entity\", entity_kind=\"document\", name=\"FlashAttention: Fast and Memory-Efficient Exact Attention\", properties={authors: \"Dao et al.\", year: 2022, source: \"arxiv:2205.14135\"})")
+```
+
+### 3. Link them
+
+Edges express typed relationships. `introduced_by` means "this concept was
+introduced by that document":
+
+```
+request(ops="link(source_id=\"<flash_id>\", target_id=\"<paper_id>\", relation=\"introduced_by\", weight=1.0)")
+```
+
+### 4. Search the graph
+
+Search uses hybrid FTS5 + vector similarity with RRF fusion:
+
+```
+request(ops="search(kind=\"entity\", query=\"memory efficient attention\")")
+```
+
+Returns a scored list of matching entities.
+
+### 5. Explore neighbors
+
+See what connects to an entity:
+
+```
+request(ops="neighbors(node_id=\"<flash_id>\", direction=\"both\")")
+```
+
+### 6. Create a note
+
+Notes are temporal observations about your work — what you noticed, concluded,
+or decided. They can annotate entities:
+
+```
+request(ops="create(kind=\"note\", note_kind=\"observation\", content=\"FlashAttention reduces memory from O(N^2) to O(N) by tiling and recomputation\", annotates=[\"<flash_id>\"])")
+```
+
+### 7. Batch operations
+
+Run multiple independent operations in one call:
+
+```
+request(ops="[create(kind=\"entity\", entity_kind=\"concept\", name=\"FlashAttention-2\"), create(kind=\"entity\", entity_kind=\"concept\", name=\"FlashAttention-3\")]")
+```
+
+Batched ops run in parallel with no ordering guarantee. If op B depends on op
+A's output, use two separate `request` calls.
+
+### 8. Query the graph
+
+For complex pattern matching, use GQL:
+
+```
+request(ops="query(query=\"MATCH (a:concept)-[:introduced_by]->(b:document) RETURN a.name, b.name LIMIT 10\")")
+```
+
+Or SPARQL:
+
+```
+request(ops="query(query=\"SELECT ?a ?b WHERE { ?a :introduced_by ?b . } LIMIT 10\")")
+```
+
+Both compile to the same SQL backend.
+
+## What to read next
+
+- [Knowledge Graph Modeling](knowledge-graph.md) — how to think about entity
+  kinds, edge relations, and modeling decisions
+- [Prompt Cookbook](prompt-cookbook.md) — 20+ ready-to-use verb patterns
+- [Search and Retrieval](search.md) — how hybrid search, reranking, and
+  decompose work