@lucern/sdk 0.2.0-alpha.1 → 0.2.0-alpha.10

package/README.md

@@ -1,97 +1,727 @@
 # @lucern/sdk
 
-TypeScript SDK for the Lucern reasoning platform.
+The reasoning operating system for AI-native applications.
 
-## Package status
+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.
 
-- Distribution target: private/internal registry
-- License: UNLICENSED
-- Auth model: service principal key via `LUCERN_API_KEY`
-
-## 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
-export NODE_AUTH_TOKEN="<your-package-token>"
-cat <<'EOF' > .npmrc
-@lucern:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
-EOF
-
 npm install @lucern/sdk
 ```
 
-## Quickstart
+## Canonical Interface
+
+`@lucern/sdk` is the canonical public interface for Lucern.
+
+- Build applications, automations, and backend integrations against the SDK first.
+- Treat `/api/platform/v1/*` as the transport mirror of the SDK surface.
+- Treat MCP as an agent-facing client of the same surface, not as a privileged bypass around SDK or HTTP semantics.
+
+IA-7 closes the remaining SDK surface gaps needed for SDK-first clients:
+
+- Kernel mutations that previously only existed behind route or MCP adapters now have SDK wrappers across beliefs, evidence, questions, edges, topics, worktrees, and nodes.
+- `lucern.identity.whoami()` exposes resolved principal context for service principals, tenant API keys, and interactive users.
+- Public SDK types now export `SdkPrincipalContext` plus the `Platform*Record` and `Workflow*Record` families for typed client code.
+
+```typescript
+import {
+  createLucernClient,
+  type PlatformBeliefRecord,
+  type SdkPrincipalContext,
+  type WorkflowWorktreeRecord,
+} from "@lucern/sdk";
+
+const lucern = createLucernClient({
+  apiKey: process.env.LUCERN_API_KEY,
+  baseUrl: "https://api.lucern.ai",
+});
+
+const identity = await lucern.identity.whoami();
+const principal: SdkPrincipalContext = identity.data;
+```
+
+## 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.
 
-```ts
+```typescript
 import { createLucernClient } from "@lucern/sdk";
 
 const lucern = createLucernClient({
   apiKey: process.env.LUCERN_API_KEY,
-  baseUrl: process.env.LUCERN_BASE_URL ?? process.env.LUCERN_API_BASE_URL,
+  baseUrl: "https://api.lucern.ai",
 });
 
-const projectList = await lucern.context.listProjects({ includeShared: true });
-const project = projectList.data.projects[0];
+// Create a parent topic for your domain
+const codeQuality = await lucern.topics.create({
+  name: "Code Quality Intelligence",
+  type: "domain",
+});
 
-if (!project?.projectId) {
-  throw new Error(
-    "No graph project is available. Bootstrap or create one before running the SDK quickstart."
-  );
-}
+// Create child topics for specific areas
+const securityTopic = await lucern.topics.create({
+  name: "Security Patterns",
+  type: "theme",
+  parentTopicId: codeQuality.data.topicId,
+});
 
-const belief = await lucern.beliefs.create({
-  canonicalText:
-    "AI-native reasoning infrastructure will expand rapidly over 3 years",
-  projectId: project.projectId,
+const performanceTopic = await lucern.topics.create({
+  name: "Performance Patterns",
+  type: "theme",
+  parentTopicId: codeQuality.data.topicId,
 });
+```
+
+### 2. Populate the Graph With What You Know
 
-await lucern.beliefs.modulateConfidence(belief.data.nodeId, {
-  confidence: 0.72,
+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,
+  baseRate: 0.5,
+  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: "Two independent sources confirm demand pull.",
+  rationale: "OWASP verified, industry standard for 20+ years",
+});
+
+// A belief — confident from observation
+const patternBelief = await lucern.beliefs.create({
+  topicId,
+  baseRate: 0.5,
+  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,
+  baseRate: 0.5,
+  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,
+  baseRate: 0.5,
+  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",
+});
+```
+
+### 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",
+});
+```
+
+### 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: "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,
+});
+
+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: "Static analysis catches 53% overall, not <30%. But the category breakdown reveals something more important.",
+});
+
+// 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,
+  baseRate: 0.5,
+  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
+`);
+```
+
+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 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, 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`);
+}
+```
+
+### 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}`);
 });
 ```
 
-## Surface
+## 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
+`;
+```
+
+### 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,
+  });
+}
+```
+
+### Search the Graph Semantically
+
+```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,
+});
+
+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,
+});
+```
 
-`createLucernClient()` returns grouped clients:
+## Agent Configuration
 
-- `beliefs`
-- `evidence`
-- `questions`
-- `graph`
-- `judgments`
-- `worktrees`
-- `context`
-- `tasks`
-- `research`
-- `tools` (runtime custom tool registration/invocation)
-- `custom` (default custom namespace invoker)
-- `extensions` (dynamic namespace invokers)
-- `raw` (low-level endpoint clients)
+### CLAUDE.md / AGENTS.md Integration
 
-## Custom tool extensions
+Add Lucern context to your coding agent's system instructions:
 
-```ts
-import { z } from "zod";
+```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,
+  baseRate: 0.5,
+  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: "stack",
-  name: "score_deal",
-  description: "Stack-specific scoring extension",
-  inputSchema: z.object({ dealId: z.string() }),
-  outputSchema: z.object({ score: z.number() }),
-  handler: async ({ dealId }) => ({ score: dealId.length / 10 }),
+  namespace: "codebase",
+  name: "trace_dependency",
+  description: "Trace how a code change would affect beliefs in the reasoning graph",
+  inputSchema: z.object({
+    filePath: z.string(),
+    changeDescription: z.string(),
+    topicId: z.string(),
+  }),
+  outputSchema: z.object({
+    affectedBeliefs: z.array(z.object({
+      beliefId: z.string(),
+      text: z.string(),
+      currentConfidence: z.number(),
+      impact: z.enum(["strengthens", "weakens", "invalidates"]),
+    })),
+  }),
+  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
 
-await lucern.extensions.stack.score_deal({ dealId: "deal_001" });
+```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",
+    },
+  ],
+});
 ```
 
-## Key provisioning endpoints
+## 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
+const lucern = createLucernClient({
+  apiKey: "lk_your_key",
+  baseUrl: "https://api.lucern.ai",
+});
+```
 
-SDK key lifecycle methods map to:
+## Links
 
-- `GET /api/platform/v1/identity/keys`
-- `POST /api/platform/v1/identity/keys`
-- `POST /api/platform/v1/identity/keys/{keyId}/rotate`
-- `POST /api/platform/v1/identity/keys/{keyId}/revoke`
+- [Documentation](https://docs.lucern.ai)
+- [API Reference](https://docs.lucern.ai/api)
+- [Examples](https://github.com/LucernAI/lucern/tree/main/examples)