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

package/README.md

@@ -1,53 +1,16 @@
 # @lucern/sdk
 
-The reasoning operating system for AI-native applications.
+The TypeScript SDK for Lucern, the reasoning operating system.
 
-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 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.
 
-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.
+## Install
 
 ```bash
 npm install @lucern/sdk
 ```
 
-## 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.
+## Quickstart
 
 ```typescript
 import { createLucernClient } from "@lucern/sdk";
@@ -57,667 +20,261 @@ const lucern = createLucernClient({
   baseUrl: "https://api.lucern.ai",
 });
 
-// Create a parent topic for your domain
-const codeQuality = await lucern.topics.create({
-  name: "Code Quality Intelligence",
+// 1. Create a topic (a scope for reasoning)
+const topic = await lucern.topics.create({
+  name: "Climate Tech Market Analysis",
   type: "domain",
 });
 
-// Create child topics for specific areas
-const securityTopic = await lucern.topics.create({
-  name: "Security Patterns",
-  type: "theme",
-  parentTopicId: codeQuality.data.topicId,
-});
-
-const performanceTopic = await lucern.topics.create({
-  name: "Performance Patterns",
-  type: "theme",
-  parentTopicId: codeQuality.data.topicId,
+// 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",
 });
-```
-
-### 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,
-  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: "OWASP verified, industry standard for 20+ years",
+// 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,
 });
 
-// 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,
+// 4. Score your confidence
+await lucern.beliefs.modulateConfidence(belief.data.nodeId, {
+  confidence: 0.78,
   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",
+  rationale: "DOE data supports the trajectory, but assumes continued policy support",
 });
 
-// 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",
+// 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,
 });
 ```
 
-### 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",
-});
-```
+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.
 
-### 5. Add Evidence as You Work
+## What Makes This Different
 
-Your agent processes the results and commits evidence to the graph.
+Most knowledge tools store facts. Lucern tracks how understanding evolves.
 
 ```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
+// New evidence contradicts your belief
 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.",
+  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,
 });
 
-// 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,
+// Your confidence changes
+await lucern.beliefs.modulateConfidence(belief.data.nodeId, {
+  confidence: 0.55,
   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",
+  rationale: "Major industry exit signals real-world cost barriers beyond DOE projections",
 });
 
-// Link them
-await lucern.graph.createEdge({
+// Flag the tension explicitly
+await lucern.contradictions.flag({
   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,
+  beliefA: belief.data.nodeId,
+  beliefB: optimisticBelief.nodeId,
+  description: "DOE projections vs Shell operational exit: lab costs vs deployed costs",
+  severity: "high",
+  defeatType: "undercuts",
 });
-
-// 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.
-
----
+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.
 
 ## 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. |
+| 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 |
 
 ## 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
+// 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
 ```
 
-## Graph Intelligence
+## Build Agents That Reason
 
-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}`);
-});
-```
-
-## LLM Integration Patterns
-
-### Inject Reasoning Context Into Any LLM Call
+Lucern is built for AI agents that need to think, not just retrieve.
 
 ```typescript
+// Compile the current understanding into a context pack
 const context = await lucern.context.compile(topicId, {
-  query: "security review priorities",
+  query: "What do we know about carbon capture economics?",
   ranking: "weighted_v1",
-  tokenBudget: 3000,
-  includeEntities: true,
+  tokenBudget: 2000,
 });
 
-// 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
+// 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:
 
-```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,
-  });
-}
-```
+    Beliefs (ranked by relevance):
+    ${context.data.activeBeliefs
+      .map((b) => `[${b.confidence}] ${b.canonicalText}`)
+      .join("\n    ")}
 
-### Search the Graph Semantically
+    Open Questions:
+    ${context.data.openQuestions.map((q) => q.text).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,
-});
+    Unresolved Contradictions:
+    ${context.data.contradictions.map((c) => c.description).join("\n    ")}
 
-results.data.forEach(b => {
-  console.log(`[${b.confidence}] ${b.canonicalText}`);
+    Reason from this foundation. When your analysis conflicts with
+    existing beliefs, say so explicitly.`,
+  prompt: userQuery,
 });
 
-// Search evidence
-const evidence = await lucern.search.evidence({
+// Write the agent findings back to the graph
+await lucern.evidence.create({
   topicId,
-  query: "token refresh timing data",
-  limit: 5,
+  text: response.analysis,
+  sourceUrl: "agent://research-analyst/session-42",
+  targetId: relevantBeliefId,
+  weight: 0.7,
 });
 ```
 
-## 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
+Every time an agent reads from the graph and writes back, the graph gets smarter. This is the compound intelligence loop.
 
-This project uses Lucern for knowledge management. Before making
-architectural decisions, check the reasoning graph:
+## Evolving Understanding
 
-- Read current beliefs: `lucern.beliefs.list({ topicId: "..." })`
-- Check for contradictions: `lucern.contradictions.list({ topicId: "..." })`
-- Compile context before analysis: `lucern.context.compile(topicId, { query: "..." })`
+Beliefs are immutable once scored, like git commits. When understanding evolves, you fork:
 
-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>",
+```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",
 });
 
-// Add evidence from your implementation
-await lucern.evidence.create({
-  topicId,
-  text: "<what you observed or built>",
-  sourceUrl: "commit://<sha>",
-  targetId: beliefId,
-  weight: 0.8,
+await lucern.beliefs.modulateConfidence(forked.data.nodeId, {
+  confidence: 0.82,
+  trigger: "evidence_added",
+  rationale: "Three independent operator reports confirm cost barriers persist",
 });
 
-// Answer questions your work resolved
-await lucern.questions.answer(questionId, {
-  text: "<the answer>",
-  confidence: "strong",
+await lucern.beliefs.modulateConfidence(originalBelief.nodeId, {
+  confidence: 0,
+  trigger: "evidence_added",
+  rationale: "Superseded by forked belief incorporating operator data",
 });
-\`\`\`
 ```
 
-### Custom Tool Registration for Agents
+The lineage is permanent. You can trace how understanding moved from one belief to another, through what evidence, at what confidence.
+
+## Custom Tools
 
-Give your agents domain-specific capabilities that interact with the graph:
+Extend the graph with domain-specific operations that any agent can invoke:
 
 ```typescript
+import { z } from "zod";
+
 lucern.tools.register({
-  namespace: "codebase",
-  name: "trace_dependency",
-  description: "Trace how a code change would affect beliefs in the reasoning graph",
+  namespace: "research",
+  name: "analyze_transcript",
+  description: "Extract beliefs and evidence from a meeting transcript",
   inputSchema: z.object({
-    filePath: z.string(),
-    changeDescription: z.string(),
+    transcriptUrl: z.string().url(),
     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"]),
-    })),
+    beliefs: z.array(z.object({ text: z.string(), confidence: z.number() })),
+    evidence: z.array(z.object({ text: z.string(), sourceUrl: z.string() })),
   }),
-  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) };
+  handler: async ({ transcriptUrl, topicId }) => {
+    const transcript = await fetchTranscript(transcriptUrl);
+    return extractInsights(transcript, topicId);
   },
 });
-```
-
-## Worktree Patterns
 
-### List and Resume Investigations
-
-```typescript
-// See all active investigations
-const worktrees = await lucern.worktrees.list({
+await lucern.extensions.research.analyze_transcript({
+  transcriptUrl: "https://...",
   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:
+## Authentication
 
 ```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",
-    },
-  ],
+// Service principal (server-to-server)
+const lucern = createLucernClient({
+  apiKey: "lk_your_service_principal_key",
+  baseUrl: "https://api.lucern.ai",
 });
-```
 
-## Confidence History
+// Tenant API key (application-level)
+const lucern = createLucernClient({
+  apiKey: "luc_your_tenant_api_key",
+  baseUrl: "https://api.lucern.ai",
+});
+```
 
-Every confidence change is recorded with full provenance:
+## Confidence Scale
 
-```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}`
-  );
-});
+| 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 |
 
-// 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
-```
+## TypeScript First
 
-## Authentication
+Every response is fully typed. Every parameter has IntelliSense.
 
 ```typescript
-const lucern = createLucernClient({
-  apiKey: "lk_your_key",
-  baseUrl: "https://api.lucern.ai",
+const belief = await lucern.beliefs.create({
+  topicId: "...",
+  canonicalText: "...",
 });
+
+belief.data.nodeId;      // string
+belief.data.confidence;  // number | null
+belief.data.status;      // "unscored" | "scored" | "archived"
 ```
 
 ## Links