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

package/README.md

@@ -1,16 +1,22 @@
 # @lucern/sdk
 
-The TypeScript SDK for Lucern, the reasoning operating system.
+The reasoning operating system for AI-native applications.
 
-Lucern gives your application a knowledge graph that thinks. Beliefs evolve. Evidence compounds. Contradictions surface. Your software does not just store data. It reasons about it.
+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.
 
-## 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
+## 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
+
+Topics are how you organize knowledge. They nest hierarchically, like folders that think.
 
 ```typescript
 import { createLucernClient } from "@lucern/sdk";
@@ -20,261 +26,661 @@ const lucern = createLucernClient({
   baseUrl: "https://api.lucern.ai",
 });
 
-// 1. Create a topic (a scope for reasoning)
-const topic = await lucern.topics.create({
-  name: "Climate Tech Market Analysis",
+// Create a parent topic for your domain
+const codeQuality = await lucern.topics.create({
+  name: "Code Quality Intelligence",
   type: "domain",
 });
 
-// 2. State a belief (what you think is true)
-const belief = await lucern.beliefs.create({
-  topicId: topic.data.topicId,
-  canonicalText: "Carbon capture will reach cost parity with offsets by 2028",
+// Create child topics for specific areas
+const securityTopic = await lucern.topics.create({
+  name: "Security Patterns",
+  type: "theme",
+  parentTopicId: codeQuality.data.topicId,
 });
 
-// 3. Ground it in evidence
-await lucern.evidence.create({
-  topicId: topic.data.topicId,
-  text: "DOE report shows capture costs fell 40% in 2025, projecting $80/ton by 2027",
-  sourceUrl: "https://energy.gov/reports/carbon-capture-2025",
-  targetId: belief.data.nodeId,
-  weight: 0.85,
+const performanceTopic = await lucern.topics.create({
+  name: "Performance Patterns",
+  type: "theme",
+  parentTopicId: codeQuality.data.topicId,
 });
+```
+
+### 2. Populate the Graph With What You Know
 
-// 4. Score your confidence
-await lucern.beliefs.modulateConfidence(belief.data.nodeId, {
-  confidence: 0.78,
+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,
+  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: "DOE data supports the trajectory, but assumes continued policy support",
+  rationale: "OWASP verified, industry standard for 20+ years",
 });
 
-// 5. Ask what would change your mind
-await lucern.questions.create({
-  topicId: topic.data.topicId,
-  text: "What happens to capture economics if the IRA tax credits expire in 2026?",
-  priority: "high",
-  linkedBeliefId: belief.data.nodeId,
+// 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: "Last 6 months of security audits: 14 input validation issues, 1 crypto issue",
+});
+
+// A hypothesis — under active testing
+const hypothesis = await lucern.beliefs.create({
+  topicId,
+  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",
 });
 ```
 
-Five calls. A living knowledge graph with a belief grounded in evidence, scored with confidence, and tested by a question. The graph remembers everything: what you believed, when you believed it, and why.
+### 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",
+});
+```
+
+### 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
+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",
+});
+```
 
-## What Makes This Different
+### 5. Add Evidence as You Work
 
-Most knowledge tools store facts. Lucern tracks how understanding evolves.
+Your agent processes the results and commits evidence to the graph.
 
 ```typescript
-// New evidence contradicts your belief
+// 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: "Shell exits direct air capture citing unfavorable unit economics at scale",
-  sourceUrl: "https://reuters.com/shell-dac-exit-2026",
-  targetId: belief.data.nodeId,
-  weight: -0.6,
+  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,
 });
 
-// Your confidence changes
-await lucern.beliefs.modulateConfidence(belief.data.nodeId, {
-  confidence: 0.55,
+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: "Major industry exit signals real-world cost barriers beyond DOE projections",
+  rationale: "Static analysis catches 53% overall, not <30%. But the category breakdown reveals something more important.",
 });
 
-// Flag the tension explicitly
-await lucern.contradictions.flag({
+// 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(evolved.data.nodeId, {
+  confidence: 0.88,
+  trigger: "evidence_added",
+  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,
-  beliefA: belief.data.nodeId,
-  beliefB: optimisticBelief.nodeId,
-  description: "DOE projections vs Shell operational exit: lab costs vs deployed costs",
-  severity: "high",
-  defeatType: "undercuts",
+  canonicalText: "Human code review should focus on business logic and concurrency — the categories where static analysis provides zero coverage",
+  beliefType: "belief",
 });
+
+await lucern.beliefs.modulateConfidence(actionable.data.nodeId, {
+  confidence: 0.85,
+  trigger: "worktree_outcome",
+  rationale: "Direct implication of the comparison study findings",
+});
+
+// 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",
+});
+```
+
+### 7. Compile Context for Your Next Agent Session
+
+Before your agent starts its next session, it reads the graph:
+
+```typescript
+const context = await lucern.context.compile(topicId, {
+  query: "code review strategy and static analysis coverage",
+  ranking: "weighted_v1",
+  tokenBudget: 2000,
+});
+
+// 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
+`);
 ```
 
-You started at 78% confidence. New evidence dropped you to 55%. There is an unresolved contradiction between the optimistic projection and the market reality. Every step is traceable. Every change has a rationale. Nothing is silently overwritten.
+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 Is | Git Analogy |
-|---------|-----------|-------------|
-| **Topic** | A scope for reasoning about something | A repository |
-| **Belief** | A statement held to be true, with confidence | A commit (immutable once scored) |
-| **Evidence** | A fact that supports or contradicts a belief | A test result |
-| **Question** | Something that needs investigation | An open issue |
-| **Contradiction** | Two beliefs in tension | A merge conflict that may stay unresolved |
-| **Worktree** | A focused investigation into specific beliefs | A feature branch |
-| **Confidence** | How sure you are (0 to 1), append-only history | Build status, changes with every test |
+| Concept | What It Does |
+|---------|-------------|
+| **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 });
 
-// Knowledge primitives
-lucern.beliefs        // Create, fork, archive, score beliefs
-lucern.evidence       // Add evidence, link to beliefs and questions
-lucern.questions      // Ask questions, answer them, track status
-lucern.contradictions // Flag and manage tensions between beliefs
-
-// Structure
-lucern.topics         // Scope your reasoning into domains
-lucern.worktrees      // Focused investigations (feature branches for knowledge)
-lucern.ontologies     // Define your domain vocabulary
-
-// Intelligence
-lucern.graph          // Traverse, analyze, detect bias, find gaps
-lucern.context        // Compile context packs for AI agents
-lucern.search         // Semantic search across the graph
-
-// Operations
-lucern.tasks          // Track execution work tied to questions
-lucern.audit          // Full audit trail, every mutation, every actor
-lucern.identity       // Manage principals, sessions, API keys
+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       // 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`);
+}
 ```
 
-## Build Agents That Reason
+### 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`
+    );
+  }
+});
+```
 
-Lucern is built for AI agents that need to think, not just retrieve.
+### 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}`);
+});
+```
+
+## LLM Integration Patterns
+
+### Inject Reasoning Context Into Any LLM Call
 
 ```typescript
-// Compile the current understanding into a context pack
 const context = await lucern.context.compile(topicId, {
-  query: "What do we know about carbon capture economics?",
+  query: "security review priorities",
   ranking: "weighted_v1",
-  tokenBudget: 2000,
+  tokenBudget: 3000,
+  includeEntities: true,
 });
 
-// Feed it to your LLM as grounded context
-const response = await llm.generate({
-  system: `You are a research analyst. Here is your current knowledge state:
+// 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
+`;
+```
 
-    Beliefs (ranked by relevance):
-    ${context.data.activeBeliefs
-      .map((b) => `[${b.confidence}] ${b.canonicalText}`)
-      .join("\n    ")}
+### Let the LLM Write Back to the Graph
+
+```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" },
+    },
+  }],
+});
+
+// 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,
+  });
+}
+```
 
-    Open Questions:
-    ${context.data.openQuestions.map((q) => q.text).join("\n    ")}
+### Search the Graph Semantically
 
-    Unresolved Contradictions:
-    ${context.data.contradictions.map((c) => c.description).join("\n    ")}
+```typescript
+// 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,
+});
 
-    Reason from this foundation. When your analysis conflicts with
-    existing beliefs, say so explicitly.`,
-  prompt: userQuery,
+results.data.forEach(b => {
+  console.log(`[${b.confidence}] ${b.canonicalText}`);
 });
 
-// Write the agent findings back to the graph
-await lucern.evidence.create({
+// Search evidence
+const evidence = await lucern.search.evidence({
   topicId,
-  text: response.analysis,
-  sourceUrl: "agent://research-analyst/session-42",
-  targetId: relevantBeliefId,
-  weight: 0.7,
+  query: "token refresh timing data",
+  limit: 5,
 });
 ```
 
-Every time an agent reads from the graph and writes back, the graph gets smarter. This is the compound intelligence loop.
+## Agent Configuration
 
-## Evolving Understanding
+### CLAUDE.md / AGENTS.md Integration
 
-Beliefs are immutable once scored, like git commits. When understanding evolves, you fork:
+Add Lucern context to your coding agent's system instructions:
 
-```typescript
-const forked = await lucern.beliefs.fork(originalBelief.nodeId, {
-  newFormulation:
-    "Carbon capture will remain 2-3x more expensive than offsets through 2030, " +
-    "with deployment limited to regulated industries where offsets are not accepted",
-  forkReason: "contradiction_response",
+```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,
 });
+\`\`\`
 
-await lucern.beliefs.modulateConfidence(forked.data.nodeId, {
-  confidence: 0.82,
-  trigger: "evidence_added",
-  rationale: "Three independent operator reports confirm cost barriers persist",
+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>",
 });
 
-await lucern.beliefs.modulateConfidence(originalBelief.nodeId, {
-  confidence: 0,
-  trigger: "evidence_added",
-  rationale: "Superseded by forked belief incorporating operator data",
+// Add evidence from your implementation
+await lucern.evidence.create({
+  topicId,
+  text: "<what you observed or built>",
+  sourceUrl: "commit://<sha>",
+  targetId: beliefId,
+  weight: 0.8,
 });
-```
 
-The lineage is permanent. You can trace how understanding moved from one belief to another, through what evidence, at what confidence.
+// Answer questions your work resolved
+await lucern.questions.answer(questionId, {
+  text: "<the answer>",
+  confidence: "strong",
+});
+\`\`\`
+```
 
-## Custom Tools
+### Custom Tool Registration for Agents
 
-Extend the graph with domain-specific operations that any agent can invoke:
+Give your agents domain-specific capabilities that interact with the graph:
 
 ```typescript
-import { z } from "zod";
-
 lucern.tools.register({
-  namespace: "research",
-  name: "analyze_transcript",
-  description: "Extract beliefs and evidence from a meeting transcript",
+  namespace: "codebase",
+  name: "trace_dependency",
+  description: "Trace how a code change would affect beliefs in the reasoning graph",
   inputSchema: z.object({
-    transcriptUrl: z.string().url(),
+    filePath: z.string(),
+    changeDescription: z.string(),
     topicId: z.string(),
   }),
   outputSchema: z.object({
-    beliefs: z.array(z.object({ text: z.string(), confidence: z.number() })),
-    evidence: z.array(z.object({ text: z.string(), sourceUrl: z.string() })),
+    affectedBeliefs: z.array(z.object({
+      beliefId: z.string(),
+      text: z.string(),
+      currentConfidence: z.number(),
+      impact: z.enum(["strengthens", "weakens", "invalidates"]),
+    })),
   }),
-  handler: async ({ transcriptUrl, topicId }) => {
-    const transcript = await fetchTranscript(transcriptUrl);
-    return extractInsights(transcript, 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) };
   },
 });
-
-await lucern.extensions.research.analyze_transcript({
-  transcriptUrl: "https://...",
-  topicId,
-});
 ```
 
-## Authentication
+## Worktree Patterns
+
+### List and Resume Investigations
 
 ```typescript
-// Service principal (server-to-server)
-const lucern = createLucernClient({
-  apiKey: "lk_your_service_principal_key",
-  baseUrl: "https://api.lucern.ai",
+// See all active investigations
+const worktrees = await lucern.worktrees.list({
+  topicId,
+  status: "active",
 });
 
-// Tenant API key (application-level)
-const lucern = createLucernClient({
-  apiKey: "luc_your_tenant_api_key",
-  baseUrl: "https://api.lucern.ai",
+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`);
 ```
 
-## Confidence Scale
+### Merge an Investigation
+
+When the investigation is complete, merge findings into the main graph:
 
-| Range | Meaning |
-|-------|---------|
-| 0.90-0.95 | Structural law, verified by multiple independent sources |
-| 0.85-0.90 | Strong conviction, working implementation validates it |
-| 0.80-0.85 | Confident, evidence supports it, not yet stress-tested |
-| 0.70-0.80 | Directionally right, good signal, details still emerging |
-| 0.50-0.70 | Hypothesis, plausible but needs investigation |
-| Below 0.50 | Weak signal, more question than answer |
-| 0 | Superseded, replaced by evolved understanding |
+```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",
+    },
+  ],
+});
+```
 
-## TypeScript First
+## Confidence History
 
-Every response is fully typed. Every parameter has IntelliSense.
+Every confidence change is recorded with full provenance:
 
 ```typescript
-const belief = await lucern.beliefs.create({
-  topicId: "...",
-  canonicalText: "...",
+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}`
+  );
 });
 
-belief.data.nodeId;      // string
-belief.data.confidence;  // number | null
-belief.data.status;      // "unscored" | "scored" | "archived"
+// 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
+const lucern = createLucernClient({
+  apiKey: "lk_your_key",
+  baseUrl: "https://api.lucern.ai",
+});
 ```
 
 ## Links