docs: add example vaults (ML research, software docs, reading list)

.gitignore

@@ -4,6 +4,12 @@ dist/
 raw/
 wiki/
 inbox/
+
+# Allow vault content in examples
+!examples/**/.kb/
+!examples/**/raw/
+!examples/**/wiki/
+!examples/**/inbox/
 *.tgz
 .env
 .env.*

ROADMAP.md

@@ -171,7 +171,7 @@ What's built, what's next, and what's deferred.
 - [x] `docs/skill-authoring.md` — how to create custom skills
 - [x] `docs/provider-config.md` — LLM provider setup guide
 - [x] `docs/architecture.md` — codebase architecture for contributors
-- [ ] Example vaults in `examples/` directory (ML research, software docs, reading list)
+- [x] Example vaults in `examples/` directory (ML research, software docs, reading list)
 - [ ] Blog post / launch announcement
 
 ### Testing & Quality

examples/README.md

@@ -0,0 +1,53 @@
+# Example Vaults
+
+Pre-built kib vaults demonstrating different use cases. Each vault includes raw sources, compiled wiki articles, a knowledge graph, and a complete manifest — ready to explore with `kib search`, `kib query`, and `kib chat`.
+
+## Vaults
+
+### [`ml-research/`](ml-research/)
+
+A machine learning research vault built from seminal papers and tutorials. Demonstrates how kib distills technical content into interconnected concept articles.
+
+- **3 sources**: Attention Is All You Need, RL overview, backpropagation paper
+- **7 articles**: attention mechanism, transformers, reinforcement learning, backpropagation, gradient descent, MDPs, researcher reference
+- **Tags**: deep-learning, nlp, optimization, reinforcement-learning
+
+### [`software-docs/`](software-docs/)
+
+A software engineering knowledge base covering APIs, version control, CI/CD, and cloud-native patterns. Shows how kib organizes practical development knowledge.
+
+- **4 sources**: REST API tutorial, Git repo, CI article, Twelve-Factor App
+- **8 articles**: REST API, HTTP methods, Git, version control, CI, CD, API design patterns, twelve-factor app
+- **Tags**: api, git, ci-cd, devops, architecture
+
+### [`reading-list/`](reading-list/)
+
+A personal reading notes vault from non-fiction books and articles. Demonstrates kib as a tool for synthesizing ideas across books into a personal knowledge graph.
+
+- **4 sources**: Thinking Fast and Slow, Design of Everyday Things, Mental Models blog, Atomic Habits
+- **10 articles**: cognitive biases, System 1/2, mental models, affordances, habit formation, decision making, design principles, atomic habits framework, Kahneman, Don Norman
+- **Tags**: psychology, thinking, design, habits, decision-making
+
+## Try It
+
+```bash
+# Browse a vault
+cd examples/ml-research
+kib status
+kib search "attention"
+kib query "How do transformers work?"
+
+# Or point kib at it from anywhere
+kib --vault examples/reading-list search "cognitive biases"
+```
+
+## Using as a Starting Point
+
+These vaults are fully functional but static (the raw sources are excerpts, not full documents). To build your own vault from scratch:
+
+```bash
+kib init my-vault
+cd my-vault
+kib ingest https://example.com/article
+kib compile
+```

examples/ml-research/.kb/config.toml

@@ -0,0 +1,21 @@
+[provider]
+default = "anthropic"
+model = "claude-sonnet-4-20250514"
+fast_model = "claude-haiku-4-5-20251001"
+
+[compile]
+auto_index = true
+auto_graph = true
+max_sources_per_pass = 10
+categories = ["concepts", "topics", "references", "outputs"]
+enrich_cross_refs = true
+
+[search]
+engine = "hybrid"
+max_results = 20
+
+[skills]
+[skills.hooks]
+post-compile = []
+post-ingest = []
+post-lint = []

examples/ml-research/.kb/manifest.json

@@ -0,0 +1,146 @@
+{
+  "version": "1",
+  "vault": {
+    "name": "ml-research",
+    "created": "2026-03-01T09:00:00.000Z",
+    "lastCompiled": "2026-03-15T14:30:00.000Z",
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-20250514"
+  },
+  "sources": {
+    "src_att001": {
+      "hash": "a1b2c3d4e5f60001",
+      "ingestedAt": "2026-03-01T09:05:00.000Z",
+      "lastCompiled": "2026-03-15T14:30:00.000Z",
+      "sourceType": "web",
+      "originalUrl": "https://arxiv.org/abs/1706.03762",
+      "producedArticles": ["attention-mechanism", "transformer-architecture", "vaswani-et-al"],
+      "metadata": {
+        "title": "Attention Is All You Need",
+        "author": "Vaswani et al.",
+        "date": "2017-06-12",
+        "wordCount": 9200
+      }
+    },
+    "src_rl002": {
+      "hash": "a1b2c3d4e5f60002",
+      "ingestedAt": "2026-03-05T11:00:00.000Z",
+      "lastCompiled": "2026-03-15T14:30:00.000Z",
+      "sourceType": "web",
+      "originalUrl": "https://lilianweng.github.io/posts/2018-02-19-rl-overview/",
+      "producedArticles": ["reinforcement-learning", "markov-decision-process"],
+      "metadata": {
+        "title": "A (Long) Peek into Reinforcement Learning",
+        "author": "Lilian Weng",
+        "date": "2018-02-19",
+        "wordCount": 12000
+      }
+    },
+    "src_bp003": {
+      "hash": "a1b2c3d4e5f60003",
+      "ingestedAt": "2026-03-10T08:30:00.000Z",
+      "lastCompiled": "2026-03-15T14:30:00.000Z",
+      "sourceType": "pdf",
+      "originalUrl": "https://www.nature.com/articles/323533a0",
+      "producedArticles": ["backpropagation", "gradient-descent"],
+      "metadata": {
+        "title": "Learning representations by back-propagating errors",
+        "author": "Rumelhart, Hinton, Williams",
+        "date": "1986-10-09",
+        "wordCount": 4500
+      }
+    }
+  },
+  "articles": {
+    "attention-mechanism": {
+      "hash": "wiki_hash_0001",
+      "createdAt": "2026-03-15T14:30:00.000Z",
+      "lastUpdated": "2026-03-15T14:30:00.000Z",
+      "derivedFrom": ["src_att001"],
+      "backlinks": ["transformer-architecture"],
+      "forwardLinks": ["transformer-architecture", "backpropagation"],
+      "tags": ["deep-learning", "nlp", "attention"],
+      "summary": "Mechanism that lets models dynamically focus on relevant parts of the input",
+      "wordCount": 380,
+      "category": "concept"
+    },
+    "backpropagation": {
+      "hash": "wiki_hash_0002",
+      "createdAt": "2026-03-15T14:30:00.000Z",
+      "lastUpdated": "2026-03-15T14:30:00.000Z",
+      "derivedFrom": ["src_bp003"],
+      "backlinks": ["attention-mechanism", "gradient-descent"],
+      "forwardLinks": ["gradient-descent"],
+      "tags": ["optimization", "neural-networks", "training"],
+      "summary": "Algorithm for computing gradients in neural networks via the chain rule",
+      "wordCount": 350,
+      "category": "concept"
+    },
+    "gradient-descent": {
+      "hash": "wiki_hash_0003",
+      "createdAt": "2026-03-15T14:30:00.000Z",
+      "lastUpdated": "2026-03-15T14:30:00.000Z",
+      "derivedFrom": ["src_bp003"],
+      "backlinks": ["backpropagation"],
+      "forwardLinks": ["backpropagation"],
+      "tags": ["optimization", "training"],
+      "summary": "Iterative optimization algorithm that follows the negative gradient to minimize loss",
+      "wordCount": 290,
+      "category": "concept"
+    },
+    "transformer-architecture": {
+      "hash": "wiki_hash_0004",
+      "createdAt": "2026-03-15T14:30:00.000Z",
+      "lastUpdated": "2026-03-15T14:30:00.000Z",
+      "derivedFrom": ["src_att001"],
+      "backlinks": ["attention-mechanism"],
+      "forwardLinks": ["attention-mechanism", "reinforcement-learning"],
+      "tags": ["deep-learning", "nlp", "architecture"],
+      "summary": "Neural network architecture based entirely on self-attention, replacing recurrence and convolutions",
+      "wordCount": 520,
+      "category": "topic"
+    },
+    "reinforcement-learning": {
+      "hash": "wiki_hash_0005",
+      "createdAt": "2026-03-15T14:30:00.000Z",
+      "lastUpdated": "2026-03-15T14:30:00.000Z",
+      "derivedFrom": ["src_rl002"],
+      "backlinks": ["transformer-architecture"],
+      "forwardLinks": ["markov-decision-process"],
+      "tags": ["reinforcement-learning", "agents", "rewards"],
+      "summary": "Learning paradigm where agents learn optimal behavior through trial-and-error interaction with an environment",
+      "wordCount": 480,
+      "category": "topic"
+    },
+    "markov-decision-process": {
+      "hash": "wiki_hash_0006",
+      "createdAt": "2026-03-15T14:30:00.000Z",
+      "lastUpdated": "2026-03-15T14:30:00.000Z",
+      "derivedFrom": ["src_rl002"],
+      "backlinks": ["reinforcement-learning"],
+      "forwardLinks": ["reinforcement-learning"],
+      "tags": ["reinforcement-learning", "math", "probability"],
+      "summary": "Mathematical framework for modeling sequential decision-making under uncertainty",
+      "wordCount": 310,
+      "category": "concept"
+    },
+    "vaswani-et-al": {
+      "hash": "wiki_hash_0007",
+      "createdAt": "2026-03-15T14:30:00.000Z",
+      "lastUpdated": "2026-03-15T14:30:00.000Z",
+      "derivedFrom": ["src_att001"],
+      "backlinks": [],
+      "forwardLinks": ["attention-mechanism", "transformer-architecture"],
+      "tags": ["researchers", "google-brain"],
+      "summary": "Authors of the 2017 'Attention Is All You Need' paper that introduced the transformer",
+      "wordCount": 200,
+      "category": "reference"
+    }
+  },
+  "stats": {
+    "totalSources": 3,
+    "totalArticles": 7,
+    "totalWords": 2530,
+    "lastLintAt": "2026-03-15T15:00:00.000Z"
+  }
+}

examples/ml-research/README.md

@@ -0,0 +1,29 @@
+# ML Research Vault
+
+A machine learning research knowledge base built from foundational papers and tutorials.
+
+## Sources
+
+| Source | Type | Articles Produced |
+|--------|------|-------------------|
+| Attention Is All You Need (Vaswani et al., 2017) | web | attention-mechanism, transformer-architecture, vaswani-et-al |
+| A (Long) Peek into Reinforcement Learning (Lilian Weng) | web | reinforcement-learning, markov-decision-process |
+| Learning representations by back-propagating errors (Rumelhart et al., 1986) | pdf | backpropagation, gradient-descent |
+
+## Knowledge Graph
+
+```
+attention-mechanism ─── transformer-architecture
+        │                       │
+  backpropagation          reinforcement-learning
+        │                       │
+  gradient-descent      markov-decision-process
+```
+
+## Try It
+
+```bash
+kib search "attention"
+kib query "Explain how transformers replaced RNNs"
+kib skill run explain --args '{"topic": "backpropagation", "level": "beginner"}'
+```

examples/ml-research/raw/articles/attention-is-all-you-need.md

@@ -0,0 +1,47 @@
+---
+title: "Attention Is All You Need"
+source_type: web
+url: "https://arxiv.org/abs/1706.03762"
+author: "Vaswani et al."
+date: "2017-06-12"
+ingested: "2026-03-01"
+word_count: 9200
+---
+
+# Attention Is All You Need
+
+The dominant sequence transduction models are based on complex recurrent or convolutional neural networks that include an encoder and a decoder. The best performing models also connect the encoder and decoder through an attention mechanism. We propose a new simple network architecture, the Transformer, based solely on attention mechanisms, dispensing with recurrence and convolutions entirely.
+
+## Architecture
+
+The Transformer follows an encoder-decoder structure using stacked self-attention and point-wise, fully connected layers for both the encoder and decoder.
+
+### Encoder
+
+The encoder is composed of a stack of N=6 identical layers. Each layer has two sub-layers: a multi-head self-attention mechanism and a simple position-wise fully connected feed-forward network. We employ a residual connection around each of the two sub-layers, followed by layer normalization.
+
+### Decoder
+
+The decoder is also composed of a stack of N=6 identical layers. In addition to the two sub-layers in each encoder layer, the decoder inserts a third sub-layer which performs multi-head attention over the output of the encoder stack.
+
+## Attention
+
+An attention function maps a query and a set of key-value pairs to an output, where the query, keys, values, and output are all vectors. The output is computed as a weighted sum of the values, where the weight assigned to each value is computed by a compatibility function of the query with the corresponding key.
+
+### Scaled Dot-Product Attention
+
+We compute the attention function on a set of queries simultaneously, packed together into a matrix Q. The keys and values are also packed together into matrices K and V:
+
+Attention(Q, K, V) = softmax(QK^T / sqrt(d_k)) V
+
+### Multi-Head Attention
+
+Instead of performing a single attention function, we found it beneficial to linearly project the queries, keys and values h times with different, learned linear projections. On each of these projected versions we perform the attention function in parallel, yielding d_v-dimensional output values.
+
+## Results
+
+The Transformer achieves 28.4 BLEU on the WMT 2014 English-to-German translation task, improving over the existing best results by over 2 BLEU. On the English-to-French translation task, our model achieves 41.0 BLEU, outperforming all previously published single models.
+
+## Training
+
+We trained on the WMT 2014 English-German dataset consisting of about 4.5 million sentence pairs. Training took 3.5 days on 8 P100 GPUs.

examples/ml-research/raw/articles/rl-overview.md

@@ -0,0 +1,55 @@
+---
+title: "A (Long) Peek into Reinforcement Learning"
+source_type: web
+url: "https://lilianweng.github.io/posts/2018-02-19-rl-overview/"
+author: "Lilian Weng"
+date: "2018-02-19"
+ingested: "2026-03-05"
+word_count: 12000
+---
+
+# A (Long) Peek into Reinforcement Learning
+
+Reinforcement learning (RL) is one approach to machine learning where an agent learns to make decisions by interacting with an environment. Unlike supervised learning, the agent isn't told what the correct action is — instead it discovers which actions yield the most reward through trial and error.
+
+## Key Concepts
+
+### Agent and Environment
+
+The agent is the learner and decision-maker. The environment is everything the agent interacts with. At each time step, the agent observes the current state, takes an action, and receives a reward signal along with the next state.
+
+### Markov Decision Process
+
+A Markov Decision Process (MDP) provides the mathematical framework for RL. An MDP is defined by:
+- S: a set of states
+- A: a set of actions
+- P(s'|s,a): transition probability function
+- R(s,a): reward function
+- γ: discount factor (0 ≤ γ ≤ 1)
+
+The Markov property states that the future depends only on the current state, not the history of states.
+
+### Policy
+
+A policy π(a|s) defines the agent's behavior — the probability of taking action a in state s. The goal is to find a policy that maximizes the expected cumulative reward.
+
+### Value Functions
+
+The state-value function V_π(s) represents the expected return starting from state s and following policy π. The action-value function Q_π(s,a) represents the expected return starting from state s, taking action a, then following policy π.
+
+## Methods
+
+### Model-Free Methods
+
+**Q-Learning**: An off-policy method that learns the optimal Q-function directly. The update rule:
+Q(s,a) ← Q(s,a) + α[r + γ max_a' Q(s',a') - Q(s,a)]
+
+**SARSA**: An on-policy variant that updates based on the action actually taken.
+
+**Policy Gradient**: Instead of learning a value function, directly optimize the policy. REINFORCE is the simplest policy gradient method, using Monte Carlo sampling to estimate the gradient.
+
+### Deep Reinforcement Learning
+
+DQN (Deep Q-Network) uses a neural network to approximate the Q-function, enabling RL in high-dimensional state spaces like raw pixels. Key innovations include experience replay and target networks for stability.
+
+Policy gradient methods scale naturally with deep networks. Actor-critic methods combine value function estimation with policy optimization — the critic evaluates, the actor improves.