@lucern/sdk 0.2.0-alpha.3 → 0.2.0-alpha.4

package/README.md

@@ -2,19 +2,21 @@
 
 The reasoning operating system for AI-native applications.
 
-Your AI agent reads 50 documents. It generates insights. A week later, it reads 50 more — and has no memory of what it learned before. Every session starts from zero.
+Your AI agent reads 50 documents, generates insights, and forgets everything by tomorrow. Every session starts from zero. The same questions get re-investigated. The same dead ends get explored. Nothing compounds.
 
-Lucern fixes this. It gives your application a knowledge graph that accumulates understanding over time. Beliefs strengthen or weaken as evidence arrives. Contradictions are detected, not hidden. Your agents get smarter with every interaction because the graph remembers what was learned, when, and why.
-
-## Install
+Lucern gives your agents a reasoning graph that accumulates understanding across sessions, across agents, and across time. Beliefs have confidence scores that change as evidence arrives. Contradictions are detected and tracked. Investigations are structured with hypotheses, evidence, and outcomes. Every mutation is traceable, every decision auditable.
 
 ```bash
 npm install @lucern/sdk
 ```
 
-## Quickstart — Build an Agent That Remembers
+## The Full Developer Journey
+
+This walkthrough mirrors what a developer building an AI-powered code review system would experience in a real coding session. Every API call is something you would actually use.
+
+### 1. Set Up Your Reasoning Scope
 
-Your agent processes customer support tickets and builds an evolving understanding of product issues:
+Topics are how you organize knowledge. They nest hierarchically, like folders that think.
 
 ```typescript
 import { createLucernClient } from "@lucern/sdk";
@@ -24,184 +26,654 @@ const lucern = createLucernClient({
   baseUrl: "https://api.lucern.ai",
 });
 
-// Create a reasoning scope
-const topic = await lucern.topics.create({
-  name: "Product Issue Tracker",
+// Create a parent topic for your domain
+const codeQuality = await lucern.topics.create({
+  name: "Code Quality Intelligence",
   type: "domain",
 });
-const topicId = topic.data.topicId;
 
-// Your agent processes a batch of support tickets and forms a belief
-const belief = await lucern.beliefs.create({
-  topicId,
-  canonicalText: "Authentication timeout errors are caused by the session refresh race condition, not the auth provider",
+// Create child topics for specific areas
+const securityTopic = await lucern.topics.create({
+  name: "Security Patterns",
+  type: "theme",
+  parentTopicId: codeQuality.data.topicId,
 });
 
-// Attach the evidence that led to this belief
-await lucern.evidence.create({
+const performanceTopic = await lucern.topics.create({
+  name: "Performance Patterns",
+  type: "theme",
+  parentTopicId: codeQuality.data.topicId,
+});
+```
+
+### 2. Populate the Graph With What You Know
+
+Beliefs represent understanding at different epistemic levels: facts (verified), beliefs (confident), hypotheses (testing), and assumptions (untested).
+
+```typescript
+const topicId = securityTopic.data.topicId;
+
+// A fact — verified and anchored
+const sqlFact = await lucern.beliefs.create({
   topicId,
-  text: "12 of 15 timeout tickets occur within 200ms of token refresh. Stack traces show concurrent refresh calls.",
-  targetId: belief.data.nodeId,
-  weight: 0.85,
+  canonicalText: "Parameterized queries prevent SQL injection in all major database drivers",
+  beliefType: "fact",
+});
+await lucern.beliefs.modulateConfidence(sqlFact.data.nodeId, {
+  confidence: 0.95,
+  trigger: "evidence_added",
+  rationale: "OWASP verified, industry standard for 20+ years",
 });
 
-// Score confidence based on evidence strength
-await lucern.beliefs.modulateConfidence(belief.data.nodeId, {
-  confidence: 0.75,
+// A belief — confident from observation
+const patternBelief = await lucern.beliefs.create({
+  topicId,
+  canonicalText: "Most security vulnerabilities in our codebase come from unvalidated user input at API boundaries, not from cryptographic weaknesses",
+});
+await lucern.beliefs.modulateConfidence(patternBelief.data.nodeId, {
+  confidence: 0.82,
   trigger: "evidence_added",
-  rationale: "Strong correlation in timing data, but haven't reproduced in staging yet",
+  rationale: "Last 6 months of security audits: 14 input validation issues, 1 crypto issue",
 });
 
-// Flag what would change this understanding
-await lucern.questions.create({
+// A hypothesis — under active testing
+const hypothesis = await lucern.beliefs.create({
   topicId,
-  text: "Does disabling concurrent refresh eliminate the timeout pattern?",
-  priority: "high",
-  linkedBeliefId: belief.data.nodeId,
+  canonicalText: "Automated static analysis catches fewer than 30% of the input validation vulnerabilities that human reviewers find",
+  beliefType: "hypothesis",
+});
+await lucern.beliefs.modulateConfidence(hypothesis.data.nodeId, {
+  confidence: 0.6,
+  trigger: "manual",
+  rationale: "Anecdotal — need to run a proper comparison study",
+});
+
+// An assumption — untested but used as a basis for decisions
+const assumption = await lucern.beliefs.create({
+  topicId,
+  canonicalText: "Our CI pipeline runs all static analysis rules on every PR",
+  beliefType: "assumption",
+});
+```
+
+### 3. Connect Beliefs With Edges
+
+Edges express the reasoning relationships between beliefs.
+
+```typescript
+// The pattern belief depends on the SQL injection fact
+await lucern.graph.createEdge({
+  topicId,
+  sourceId: patternBelief.data.nodeId,
+  targetId: sqlFact.data.nodeId,
+  edgeType: "depends_on",
+  reasoning: "Input validation pattern includes SQL injection as a subclass",
+  reasoningMethod: "deductive",
+});
+
+// The hypothesis is derived from the pattern belief
+await lucern.graph.createEdge({
+  topicId,
+  sourceId: hypothesis.data.nodeId,
+  targetId: patternBelief.data.nodeId,
+  edgeType: "derived_from",
+  reasoning: "If most vulns are input validation, and static analysis misses them, the tooling gap is at the input boundary",
+  reasoningMethod: "inductive",
+});
+
+// The hypothesis depends on an untested assumption
+await lucern.graph.createEdge({
+  topicId,
+  sourceId: hypothesis.data.nodeId,
+  targetId: assumption.data.nodeId,
+  edgeType: "depends_on",
+  reasoning: "If the CI pipeline is not running all rules, the comparison would be invalid",
+  reasoningMethod: "deductive",
 });
 ```
 
-Next week, your agent processes more tickets:
+### 4. Open an Investigation With a Worktree
+
+Worktrees are focused investigations — like a feature branch for knowledge. You test beliefs, gather evidence, and merge the findings.
 
 ```typescript
-// New evidence arrives that contradicts the original belief
+const investigation = await lucern.worktrees.create({
+  topicId,
+  title: "Static analysis vs human review comparison",
+  hypothesis: "Running the same 50 PRs through both static analysis and manual review will show static analysis catches less than 30% of what humans find",
+  beliefIds: [hypothesis.data.nodeId],
+});
+
+// Create tasks to drive the investigation
+await lucern.tasks.create({
+  topicId,
+  title: "Run Semgrep + CodeQL on the last 50 merged PRs and log findings",
+  linkedWorktreeId: investigation.data.worktreeId,
+  linkedQuestionId: comparisonQuestion.data.questionId,
+  taskType: "data_collection",
+});
+
+await lucern.tasks.create({
+  topicId,
+  title: "Have two senior engineers independently review the same 50 PRs",
+  linkedWorktreeId: investigation.data.worktreeId,
+  taskType: "research",
+});
+```
+
+### 5. Add Evidence as You Work
+
+Your agent processes the results and commits evidence to the graph.
+
+```typescript
+// Static analysis results
+await lucern.evidence.create({
+  topicId,
+  text: "Semgrep + CodeQL found 23 issues across 50 PRs. 18 were true positives. Categories: 12 input validation, 4 auth bypass patterns, 2 information disclosure.",
+  sourceUrl: "ci://semgrep-run/batch-50pr-comparison",
+  targetId: hypothesis.data.nodeId,
+  weight: 0.6, // partially supports
+});
+
+// Human review results
 await lucern.evidence.create({
   topicId,
-  text: "Timeouts persist after disabling concurrent refresh. Network traces show upstream latency spikes from the auth provider during peak hours.",
-  targetId: belief.data.nodeId,
-  weight: -0.7, // contradicts
+  text: "Two senior engineers found 41 issues across the same 50 PRs (34 unique after dedup). Categories: 22 input validation, 7 business logic flaws, 3 auth, 2 race conditions.",
+  sourceUrl: "review://manual-audit/batch-50pr",
+  targetId: hypothesis.data.nodeId,
+  weight: 0.9, // strongly supports — 18/34 = 53%, even worse than hypothesized
+});
+
+// Answer the question with data
+const comparisonQuestion = await lucern.questions.create({
+  topicId,
+  text: "What percentage of vulnerabilities does static analysis catch compared to human reviewers?",
+  priority: "high",
+  linkedBeliefId: hypothesis.data.nodeId,
 });
 
-// Confidence drops — the graph tracks the evolution
-await lucern.beliefs.modulateConfidence(belief.data.nodeId, {
-  confidence: 0.3,
+await lucern.questions.answer(comparisonQuestion.data.questionId, {
+  text: "Static analysis caught 18 of 34 unique issues (53%). However, it missed all 7 business logic flaws and both race conditions — categories where it found 0%.",
+  confidence: "strong",
+  evidenceIds: [staticEvidence.data.nodeId, humanEvidence.data.nodeId],
+});
+```
+
+### 6. Fork a Belief When Understanding Evolves
+
+The original hypothesis said "less than 30%." The data shows 53% — but the story is more nuanced. Fork the belief to capture the evolved understanding.
+
+```typescript
+// Drop confidence on the original (it was too pessimistic about overall catch rate)
+await lucern.beliefs.modulateConfidence(hypothesis.data.nodeId, {
+  confidence: 0.2,
   trigger: "evidence_added",
-  rationale: "Fix attempt failed. Evidence now points to upstream provider, not our code.",
+  rationale: "Static analysis catches 53% overall, not <30%. But the category breakdown reveals something more important.",
 });
 
-// Fork the belief — understanding has evolved
-const revised = await lucern.beliefs.fork(belief.data.nodeId, {
-  newFormulation: "Authentication timeouts are caused by upstream provider latency during peak hours, compounded by our lack of request queuing",
-  forkReason: "contradiction_response",
+// Fork into a more precise belief
+const evolved = await lucern.beliefs.fork(hypothesis.data.nodeId, {
+  newFormulation: "Static analysis catches 53% of vulnerabilities overall, but has a complete blind spot for business logic flaws and race conditions — the hardest categories to detect",
+  forkReason: "refinement",
 });
 
-await lucern.beliefs.modulateConfidence(revised.data.nodeId, {
-  confidence: 0.82,
+await lucern.beliefs.modulateConfidence(evolved.data.nodeId, {
+  confidence: 0.88,
   trigger: "evidence_added",
-  rationale: "Network traces confirm provider latency. Queuing fix in PR #847 eliminated 90% of timeouts in staging.",
+  rationale: "Direct comparison data: 0/7 business logic flaws caught, 0/2 race conditions caught, while input validation catch rate was 12/22 (55%)",
+});
+
+// This creates a new actionable belief
+const actionable = await lucern.beliefs.create({
+  topicId,
+  canonicalText: "Human code review should focus on business logic and concurrency — the categories where static analysis provides zero coverage",
+  beliefType: "belief",
 });
-```
 
-The graph now tells the complete story: your agent initially believed the issue was a race condition (75% confidence), new evidence contradicted that (dropped to 30%), and the understanding evolved to identify the real cause (82% confidence on the revised belief). Every step is traceable.
+await lucern.beliefs.modulateConfidence(actionable.data.nodeId, {
+  confidence: 0.85,
+  trigger: "worktree_outcome",
+  rationale: "Direct implication of the comparison study findings",
+});
 
-## Why This Matters
+// Link them
+await lucern.graph.createEdge({
+  topicId,
+  sourceId: actionable.data.nodeId,
+  targetId: evolved.data.nodeId,
+  edgeType: "derived_from",
+  reasoning: "The review focus recommendation follows directly from the coverage gap data",
+  reasoningMethod: "deductive",
+});
+```
 
-Without Lucern, your agent would process the second batch of tickets with no memory of the first. It would re-discover the race condition theory, waste time investigating it again, and maybe reach the right answer — or maybe not.
+### 7. Compile Context for Your Next Agent Session
 
-With Lucern, the agent reads its prior beliefs before processing new tickets. It knows what it already tried. It knows what questions are still open. It starts from understanding, not from zero.
+Before your agent starts its next session, it reads the graph:
 
 ```typescript
-// Before processing new data, the agent reads its current understanding
 const context = await lucern.context.compile(topicId, {
-  query: "authentication timeout root cause",
+  query: "code review strategy and static analysis coverage",
   ranking: "weighted_v1",
   tokenBudget: 2000,
 });
 
-// The context pack contains:
-// - Active beliefs ranked by relevance and confidence
-// - Open questions that still need answers
-// - Unresolved contradictions the agent should address
-// - Recent evidence for grounding
-
-// Feed this to your LLM as working memory
-const prompt = `
-  Current understanding:
-  ${context.data.activeBeliefs.map(b =>
-    `[${b.confidence}] ${b.canonicalText}`
-  ).join("\n  ")}
-
-  Open questions:
-  ${context.data.openQuestions.map(q => q.text).join("\n  ")}
-
-  Given this foundation, analyze the following new tickets...
-`;
+// context.data contains:
+// - activeBeliefs: ranked by confidence and relevance
+// - openQuestions: what still needs investigation
+// - contradictions: tensions the agent should address
+// - recentEvidence: latest findings for grounding
+
+// Your agent starts from understanding, not from zero
+console.log(`
+  ${context.data.summary.totalBeliefs} beliefs in scope
+  ${context.data.summary.openQuestions} open questions
+  ${context.data.summary.contradictions} unresolved contradictions
+`);
 ```
 
-This is the compound intelligence loop. Read from the graph, reason, write back. Every cycle makes the next one smarter.
+This is the compound intelligence loop. Every session reads the graph, reasons against it, and writes findings back. The graph gets smarter every cycle.
+
+---
 
 ## Core Concepts
 
 | Concept | What It Does |
 |---------|-------------|
-| **Topic** | Scopes reasoning to a domain (like a database for understanding) |
-| **Belief** | A statement held to be true, with a confidence score that changes over time |
-| **Evidence** | A fact that supports or contradicts a belief, with weight and source |
-| **Question** | An open investigation that drives evidence collection |
-| **Contradiction** | An explicit tension between beliefs that must be addressed |
-| **Worktree** | A focused investigation (branch, test hypotheses, merge findings) |
-| **Confidence** | A 0-to-1 score on every belief, with append-only history showing how it changed |
+| **Topic** | Scopes reasoning into a domain. Topics nest hierarchically. |
+| **Belief** | A statement with a confidence score. Types: fact, belief, hypothesis, assumption. |
+| **Evidence** | A weighted fact linked to beliefs. Positive weight supports, negative contradicts. |
+| **Question** | An open investigation. Linked to the belief it tests. |
+| **Contradiction** | An explicit tension between two beliefs. May remain permanently unresolved. |
+| **Worktree** | A focused investigation. Create hypotheses, gather evidence, merge findings. |
+| **Edge** | A typed relationship: supports, informs, depends_on, derived_from, contains, tests. |
+| **Confidence** | 0 to 1 score with append-only history. Every change has a trigger and rationale. |
+| **Task** | Execution work linked to a question or worktree. |
+| **Context Pack** | The graph compiled into ranked, budgeted context for LLM injection. |
 
 ## SDK Surface
 
 ```typescript
 const lucern = createLucernClient({ apiKey, baseUrl });
 
-lucern.beliefs        // Create, fork, archive, score beliefs
-lucern.evidence       // Add evidence, link to beliefs with weight
-lucern.questions      // Track what needs investigation
-lucern.contradictions // Detect and manage tensions
-lucern.topics         // Organize reasoning into domains
-lucern.worktrees      // Run focused investigations
-lucern.context        // Compile the graph into agent-ready context
-lucern.graph          // Traverse, analyze structure, detect bias
-lucern.ontologies     // Define domain vocabulary
-lucern.tasks          // Track execution work
+lucern.beliefs        // Create, fork, score, archive
+lucern.evidence       // Add weighted evidence, link to beliefs
+lucern.questions      // Ask, answer, track status
+lucern.contradictions // Flag tensions between beliefs
+lucern.topics         // Nested topic hierarchy
+lucern.worktrees      // Focused investigations
+lucern.graph          // Edges, traversal, structural analysis
+lucern.context        // Compile graph into agent-ready context
+lucern.ontologies     // Domain vocabulary
+lucern.tasks          // Execution tracking
 lucern.audit          // Full mutation history
-lucern.identity       // Manage API keys and sessions
+lucern.identity       // API keys and sessions
+```
+
+## Graph Intelligence
+
+The graph doesn't just store knowledge — it analyzes itself.
+
+### Structural Analysis
+
+```typescript
+// Run the full analysis suite: PageRank, Louvain clustering,
+// Tarjan SCC, spectral analysis, confirmation bias detection
+const analysis = await lucern.graph.analyze({ topicId });
+
+// Which beliefs are most central to your reasoning?
+analysis.data.pageRank.topNodes.forEach(node => {
+  console.log(`${node.canonicalText} — centrality: ${node.score}`);
+});
+
+// Are there isolated belief clusters that should be connected?
+analysis.data.communities.forEach(cluster => {
+  console.log(`Cluster "${cluster.label}": ${cluster.nodeCount} beliefs`);
+});
+
+// Any circular dependencies in your reasoning?
+if (analysis.data.cycles.length > 0) {
+  console.warn(`Found ${analysis.data.cycles.length} circular reasoning chains`);
+}
+```
+
+### Confirmation Bias Detection
+
+```typescript
+// Are you only collecting evidence that supports your beliefs?
+const bias = await lucern.graph.detectBias({ topicId });
+
+bias.data.beliefs.forEach(b => {
+  if (b.riskLevel === "critical") {
+    console.warn(
+      `"${b.canonicalText}" has ${b.supportingEvidence} supporting ` +
+      `and ${b.contradictingEvidence} contradicting evidence — ` +
+      `one-sided evidence base`
+    );
+  }
+});
+```
+
+### Find Gaps in Your Reasoning
+
+```typescript
+// What beliefs have no evidence? What questions have no answers?
+const gaps = await lucern.graph.findGaps({ topicId });
+
+console.log(`Beliefs without evidence: ${gaps.data.unsupportedBeliefs.length}`);
+console.log(`Beliefs without questions: ${gaps.data.untestedBeliefs.length}`);
+console.log(`Orphan evidence: ${gaps.data.unlinkedEvidence.length}`);
+```
+
+### Falsification — What Would Disprove Your Beliefs?
+
+```typescript
+// Generate the questions most likely to disprove your strongest beliefs
+const questions = await lucern.graph.falsify({ topicId });
+
+questions.data.forEach(q => {
+  console.log(`To disprove "${q.beliefText}", ask: "${q.question}"`);
+});
+```
+
+### Traverse the Graph
+
+```typescript
+// Walk the reasoning chain from a belief down to its evidence
+const traversal = await lucern.graph.traverse({
+  startNodeId: belief.data.nodeId,
+  direction: "down", // L3 belief -> L2 evidence -> L1 sources
+  maxDepth: 3,
+});
+
+traversal.data.nodes.forEach(node => {
+  console.log(`[${node.epistemicLayer}] ${node.canonicalText}`);
+});
 ```
 
-## Edge Types
+## LLM Integration Patterns
+
+### Inject Reasoning Context Into Any LLM Call
+
+```typescript
+const context = await lucern.context.compile(topicId, {
+  query: "security review priorities",
+  ranking: "weighted_v1",
+  tokenBudget: 3000,
+  includeEntities: true,
+});
+
+// The context pack is structured for direct prompt injection
+const systemPrompt = `
+You are a security-focused code reviewer. Your reasoning state:
+
+FACTS (high confidence, treat as ground truth):
+${context.data.invariants
+  .map(b => `- [${b.confidence}] ${b.canonicalText}`)
+  .join("\n")}
+
+ACTIVE BELIEFS (current understanding, may evolve):
+${context.data.activeBeliefs
+  .map(b => `- [${b.confidence}] ${b.canonicalText}`)
+  .join("\n")}
+
+OPEN QUESTIONS (unresolved — investigate these):
+${context.data.openQuestions
+  .map(q => `- [${q.priority}] ${q.text}`)
+  .join("\n")}
+
+CONTRADICTIONS (tensions you must address):
+${context.data.contradictions
+  .map(c => `- [${c.severity}] ${c.description}`)
+  .join("\n")}
+
+RULES:
+- If your analysis contradicts an active belief, flag it explicitly
+- If you discover evidence for an open question, answer it
+- Never silently override a high-confidence belief without evidence
+- When uncertain, create a new question rather than stating a conclusion
+`;
+```
 
-Six canonical reasoning relationships:
+### Let the LLM Write Back to the Graph
 
-| Edge | Meaning |
-|------|---------|
-| `supports` | Evidence reinforces a belief |
-| `informs` | Evidence bears on a belief (directional, weighted) |
-| `depends_on` | Belief B requires belief A to hold |
-| `derived_from` | Belief was derived from another (lineage) |
-| `contains` | Structural containment |
-| `tests` | Question tests a belief (falsification link) |
+```typescript
+// After your LLM generates analysis, parse its output
+// and write structured findings back to the graph
+
+const findings = await llm.generate({
+  system: systemPrompt,
+  prompt: `Review this PR diff and identify security concerns:\n${prDiff}`,
+  tools: [{
+    name: "record_finding",
+    description: "Record a security finding as evidence in the reasoning graph",
+    parameters: {
+      finding: { type: "string" },
+      severity: { type: "string", enum: ["low", "medium", "high", "critical"] },
+      relatedBeliefId: { type: "string", description: "ID of the belief this relates to" },
+      supportsOrContradicts: { type: "number", description: "-1 to 1" },
+    },
+  }],
+});
 
-## Custom Tools
+// Each tool call becomes evidence in the graph
+for (const call of findings.toolCalls) {
+  await lucern.evidence.create({
+    topicId,
+    text: call.args.finding,
+    sourceUrl: `pr://review/${prNumber}`,
+    targetId: call.args.relatedBeliefId,
+    weight: call.args.supportsOrContradicts,
+  });
+}
+```
 
-Extend the graph with domain operations any agent can invoke:
+### Search the Graph Semantically
 
 ```typescript
-import { z } from "zod";
+// Find beliefs related to a natural language query
+const results = await lucern.search.beliefs({
+  topicId,
+  query: "race conditions in authentication",
+  minConfidence: 0.5,
+  limit: 10,
+});
+
+results.data.forEach(b => {
+  console.log(`[${b.confidence}] ${b.canonicalText}`);
+});
+
+// Search evidence
+const evidence = await lucern.search.evidence({
+  topicId,
+  query: "token refresh timing data",
+  limit: 5,
+});
+```
+
+## Agent Configuration
+
+### CLAUDE.md / AGENTS.md Integration
+
+Add Lucern context to your coding agent's system instructions:
+
+```markdown
+<!-- In your CLAUDE.md or AGENTS.md -->
+
+## Reasoning Graph
+
+This project uses Lucern for knowledge management. Before making
+architectural decisions, check the reasoning graph:
+
+- Read current beliefs: `lucern.beliefs.list({ topicId: "..." })`
+- Check for contradictions: `lucern.contradictions.list({ topicId: "..." })`
+- Compile context before analysis: `lucern.context.compile(topicId, { query: "..." })`
+
+After making decisions, write them back:
+- Create beliefs for architectural decisions
+- Add evidence linking to the code/PR that validates them
+- Flag contradictions when new evidence conflicts with existing beliefs
+- Answer open questions when your work resolves them
+
+Confidence scale:
+- 0.90+: Verified in production
+- 0.80-0.90: Strong evidence, working implementation
+- 0.70-0.80: Directionally right, needs validation
+- Below 0.70: Hypothesis, needs investigation
+```
+
+### Claude Code Skill
+
+Create a Lucern skill for your coding agents at `~/.claude/skills/lucern-sdk/SKILL.md`:
 
+```markdown
+# Lucern SDK Skill
+
+Use this skill when building features that read or write to the
+reasoning graph, or when the user asks about beliefs, evidence,
+contradictions, or knowledge state.
+
+## Before Starting Work
+
+Compile the current context to understand what the graph knows:
+
+\`\`\`typescript
+const context = await lucern.context.compile(topicId, {
+  query: "<what you're working on>",
+  tokenBudget: 2000,
+});
+\`\`\`
+
+Check for open questions related to your task. If one exists, your work
+should aim to answer it.
+
+## After Completing Work
+
+Record what you learned:
+
+\`\`\`typescript
+// Create a belief for decisions made
+await lucern.beliefs.create({
+  topicId,
+  canonicalText: "<what you now believe to be true>",
+});
+
+// Add evidence from your implementation
+await lucern.evidence.create({
+  topicId,
+  text: "<what you observed or built>",
+  sourceUrl: "commit://<sha>",
+  targetId: beliefId,
+  weight: 0.8,
+});
+
+// Answer questions your work resolved
+await lucern.questions.answer(questionId, {
+  text: "<the answer>",
+  confidence: "strong",
+});
+\`\`\`
+```
+
+### Custom Tool Registration for Agents
+
+Give your agents domain-specific capabilities that interact with the graph:
+
+```typescript
 lucern.tools.register({
-  namespace: "support",
-  name: "classify_ticket",
-  description: "Classify a support ticket and link it to relevant beliefs",
+  namespace: "codebase",
+  name: "trace_dependency",
+  description: "Trace how a code change would affect beliefs in the reasoning graph",
   inputSchema: z.object({
-    ticketId: z.string(),
-    content: z.string(),
+    filePath: z.string(),
+    changeDescription: z.string(),
     topicId: z.string(),
   }),
   outputSchema: z.object({
-    category: z.string(),
-    linkedBeliefs: z.array(z.string()),
-    suggestedQuestions: z.array(z.string()),
+    affectedBeliefs: z.array(z.object({
+      beliefId: z.string(),
+      text: z.string(),
+      currentConfidence: z.number(),
+      impact: z.enum(["strengthens", "weakens", "invalidates"]),
+    })),
   }),
-  handler: async ({ ticketId, content, topicId }) => {
-    // Your classification logic
-    return classifyAndLink(ticketId, content, topicId);
+  handler: async ({ filePath, changeDescription, topicId }) => {
+    // Search for beliefs related to this file/area
+    const related = await lucern.search.beliefs({
+      topicId,
+      query: `${filePath} ${changeDescription}`,
+    });
+    // Analyze impact...
+    return { affectedBeliefs: analyzeImpact(related, changeDescription) };
   },
 });
 ```
 
+## Worktree Patterns
+
+### List and Resume Investigations
+
+```typescript
+// See all active investigations
+const worktrees = await lucern.worktrees.list({
+  topicId,
+  status: "active",
+});
+
+worktrees.data.forEach(wt => {
+  console.log(`${wt.title} — phase: ${wt.phase}, beliefs: ${wt.beliefCount}`);
+});
+
+// Get the full state of an investigation
+const investigation = await lucern.worktrees.get(worktreeId);
+console.log(`Hypothesis: ${investigation.data.hypothesis}`);
+console.log(`Questions: ${investigation.data.questionCount} open`);
+console.log(`Evidence: ${investigation.data.evidenceCount} collected`);
+```
+
+### Merge an Investigation
+
+When the investigation is complete, merge findings into the main graph:
+
+```typescript
+await lucern.worktrees.merge(worktreeId, {
+  summary: "Static analysis catches 53% of vulns overall but has zero coverage for business logic flaws",
+  outcomes: [
+    {
+      beliefId: hypothesis.data.nodeId,
+      confidence: 0.2,
+      rationale: "Overall catch rate was 53%, not <30% — but the category breakdown is more important",
+    },
+    {
+      beliefId: evolved.data.nodeId,
+      confidence: 0.88,
+      rationale: "Direct comparison data confirms the coverage gap hypothesis at category level",
+    },
+  ],
+});
+```
+
+## Confidence History
+
+Every confidence change is recorded with full provenance:
+
+```typescript
+const history = await lucern.beliefs.confidenceHistory(beliefId);
+
+history.data.forEach(entry => {
+  console.log(
+    `${new Date(entry.timestamp).toISOString()} ` +
+    `${entry.previousConfidence} -> ${entry.confidence} ` +
+    `[${entry.trigger}] ${entry.rationale}`
+  );
+});
+
+// Example output:
+// 2026-04-10T14:00:00Z null -> 0.60 [manual] Anecdotal observation
+// 2026-04-11T09:30:00Z 0.60 -> 0.75 [evidence_added] Semgrep data supports
+// 2026-04-11T16:00:00Z 0.75 -> 0.20 [evidence_added] Comparison study contradicted
+```
+
 ## Authentication
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucern/sdk",
-  "version": "0.2.0-alpha.3",
+  "version": "0.2.0-alpha.4",
   "description": "Lucern reasoning platform SDK. Install this one package, provide your API key, and start building in 10 minutes.",
   "license": "UNLICENSED",
   "type": "module",