limen-ai 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -5,13 +5,39 @@ All notable changes to Limen are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-03-24
+
+### Added
+- Zero-config `createLimen()` — auto-detects LLM providers from environment variables, auto-generates dev master key, uses OS temp dir for storage
+- Provider auto-detection for Anthropic, OpenAI, Gemini, Groq, Mistral, and Ollama from environment variables
+- Proof pack: CI-governed evidence index at `docs/proof/` with 530 verified file:line references
+  - `system-calls.md` — 16 system calls, all Verified with interface, implementation, and A21 test coverage
+  - `invariants.md` — 134 invariants across 3 tiers (114 Verified, 1 Measured, 4 Implemented, 11 Declared, 4 Out of Scope)
+  - `failure-modes.md` — honest accounting: 21 traceable defenses of 45 specified (12 Verified, 8 Implemented, 1 Declared)
+  - `security-model.md` — 8 security mechanisms with evidence bindings and 25 declared non-protections
+  - `readiness.md` — capstone trust surface with explicit non-proof boundaries
+- `scripts/verify-proof-pack.ts` — CI enforcement script verifying proof pack file:line references stay fresh
+- Eight progressive examples (01-hello through 08-governance-visible) replacing five original examples
+- Demo vs Production getting-started split in `docs/getting-started.md`
+
+### Changed
+- `createLimen()` config parameter is now optional (zero-config when omitted)
+- README restructured: zero-config hero section, "What's Running Underneath" reveal, Trust Surface with proof pack links
+- Comparison table dated (March 2026) with narrowed claims and ecosystem context
+- Invariant count corrected from 99 to 134 per proof pack evidence
+- Examples 04 and 08 updated to use zero-config pattern
+- CI workflow updated with proof pack freshness check
+
+### Fixed
+- Examples 04 (multi-provider) and 08 (governance-visible) no longer require explicit masterKey
+
 ## [1.0.0] - 2026-03-23
 
 ### Added
 - Cognitive Operating System: deterministic infrastructure hosting stochastic cognition
 - Four-layer architecture: Kernel (L1), Substrate (L1.5), Orchestration (L2), API (L4)
 - 16 system calls defining the governance boundary between agents and infrastructure
-- 99 formally verified invariants enforced by 3,100+ tests
+- 99 continuously enforced invariants backed by 3,200+ tests
 - SQLite foundation with WAL mode, ACID transactions, single dependency (`better-sqlite3`)
 - Append-only, hash-chained audit trail recording every state mutation
 - RBAC engine with role hierarchy and per-operation authorization

package/README.md

@@ -15,86 +15,66 @@
 
 # Limen
 
-Your AI agents don't have a reliability problem. They have an infrastructure problem.
+```typescript
+import { createLimen } from 'limen-ai';
+const limen = await createLimen();
+const response = limen.chat('What is quantum computing?');
+console.log(await response.text);
+await limen.shutdown();
+```
 
-Limen is a Cognitive Operating System. It does for AI agents what a kernel does for processes: isolation, resource control, lifecycle management, and deterministic behavior contracts. One production dependency. 16 system calls. 99 formally verified invariants. Every execution path typed and tested.
+```bash
+ANTHROPIC_API_KEY=sk-ant-... npx tsx examples/01-hello.ts
+```
 
-The name is Latin for *threshold* -- the architectural boundary where deterministic infrastructure meets stochastic cognition.
+Set an API key environment variable. That is the only setup. `createLimen()` auto-detects your provider, generates a dev encryption key, and provisions a local SQLite database. Three lines to chat.
 
 ---
 
-## Why Limen Exists
+## What's Running Underneath
 
-Every serious AI application eventually builds the same infrastructure: conversation state management, token budget enforcement, provider failover, audit trails, structured output with retry, agent lifecycle control. Teams build these as ad-hoc layers on top of LLM SDKs, then spend months debugging the interactions between them.
+That three-line example is not a thin wrapper around an API call. When you ran it, the engine:
 
-Limen replaces that entire stack with a single engine. Provider communication happens through raw HTTP -- no SDKs, no transitive dependency trees, no version conflicts. State lives in a local SQLite database you control. Every mutation is audited atomically. Every agent operates within enforced budgets and capability boundaries.
+- **Created an AES-256-GCM encrypted SQLite database** with WAL mode and ACID transactions
+- **Recorded an append-only, hash-chained audit entry** for every state mutation
+- **Enforced RBAC authorization** on the operation
+- **Tracked token usage and cost** against a budget ledger
+- **Ran the request through circuit breakers and stall detection** over raw HTTP (no provider SDK)
+- **Isolated your data by tenant** (single-tenant by default, multi-tenant by configuration)
 
-The result: AI infrastructure with the reliability guarantees of a database engine and the operational simplicity of a single `npm install`.
+None of this required configuration. The governance layer runs whether you configure it or not. The difference between the three-line demo and a production deployment is explicit configuration -- not a different code path.
 
 ---
 
-## How Limen Compares
-
-|  | Limen | Vercel AI SDK | LangChain.js |
-|---|---|---|---|
-| **Production deps** | 1 | ~50+ | ~50+ |
-| **Provider SDKs required** | No (raw HTTP) | Yes (`@ai-sdk/*`) | Yes (`@langchain/*`) |
-| **Built-in persistence** | SQLite (WAL, local) | No | Optional (external DB) |
-| **Audit trail** | Hash-chained, append-only | No | LangSmith (paid SaaS) |
-| **Budget enforcement** | Per-mission token budgets | No | No |
-| **Agent governance** | 16 system calls, RBAC | No | No |
-| **Multi-tenant isolation** | Row-level or database-level | No | No |
-| **Encryption at rest** | AES-256-GCM | No | No |
-| **Streaming** | Yes (stall detection, timeouts) | Yes | Yes |
-| **Structured output** | JSON Schema + auto-retry | Zod schemas | Output parsers |
-| **Deterministic replay** | Yes (from recorded LLM outputs) | No | No |
-
-Limen is not a wrapper around LLM APIs. It is an operating system for AI agents. If you need a lightweight way to call an LLM, the Vercel AI SDK is excellent. If you need your agents to operate within enforced boundaries with full auditability, that is what Limen was built for.
+## Why Limen Exists
 
----
+Every serious AI application eventually builds the same infrastructure: conversation state management, token budget enforcement, provider failover, audit trails, structured output with retry, agent lifecycle control. Teams build these as ad-hoc layers on top of LLM SDKs, then spend months debugging the interactions between them.
 
-## Install
+Limen replaces that entire stack with a single engine. Provider communication happens through raw HTTP -- no SDKs, no transitive dependency trees, no version conflicts. State lives in a local SQLite database you control. Every mutation is audited atomically. Every agent operates within enforced budgets and capability boundaries.
 
-```bash
-npm install limen-ai
-```
+The result: AI infrastructure with the reliability guarantees of a database engine and the operational simplicity of a single `npm install`.
 
-Requires Node.js >= 22. Single production dependency: `better-sqlite3`.
+The name is Latin for *threshold* -- the architectural boundary where deterministic infrastructure meets stochastic cognition.
 
 ---
 
-## Quick Start
+## Progressive Examples
 
-```typescript
-import { createLimen } from 'limen-ai';
-import crypto from 'node:crypto';
+### Streaming
 
-const limen = await createLimen({
-  dataDir: './my-app-data',
-  masterKey: crypto.randomBytes(32),
-  providers: [{
-    type: 'anthropic',
-    baseUrl: 'https://api.anthropic.com',
-    models: ['claude-sonnet-4-20250514'],
-    apiKeyEnvVar: 'ANTHROPIC_API_KEY',
-  }],
-});
-
-// Chat -- returns synchronously, fields resolve async
-const response = limen.chat('What are the key trends in renewable energy?');
-const text = await response.text;
-const metadata = await response.metadata;
-console.log(text);
-console.log(`${metadata.tokens.input} in / ${metadata.tokens.output} out`);
-
-// Stream
-const streamed = limen.chat('Explain quantum computing', { stream: true });
-for await (const chunk of streamed.stream) {
+```typescript
+const result = limen.chat('Explain how neural networks learn', { stream: true });
+for await (const chunk of result.stream) {
   if (chunk.type === 'content_delta') process.stdout.write(chunk.delta);
 }
+```
 
-// Structured output with schema validation and auto-retry
-const analysis = await limen.infer({
+Streaming and non-streaming produce identical final results (Invariant I-26).
+
+### Structured Output
+
+```typescript
+const result = await limen.infer({
   input: 'List the top 3 programming languages by popularity',
   outputSchema: {
     type: 'object',
@@ -103,10 +83,7 @@ const analysis = await limen.infer({
         type: 'array',
         items: {
           type: 'object',
-          properties: {
-            name: { type: 'string' },
-            reason: { type: 'string' },
-          },
+          properties: { name: { type: 'string' }, reason: { type: 'string' } },
           required: ['name', 'reason'],
         },
       },
@@ -115,32 +92,76 @@ const analysis = await limen.infer({
   },
   maxRetries: 2,
 });
-console.log(analysis.data); // Typed, validated, guaranteed to match schema
+console.log(result.data); // Typed, validated, guaranteed to match schema
+```
 
-// Cleanup
-await limen.shutdown();
+### Sessions
+
+```typescript
+const session = await limen.session({
+  agentName: 'tutor',
+  user: { id: 'student-1', role: 'learner' },
+});
+
+session.chat('What is photosynthesis?');
+session.chat('What role does chlorophyll play in it?'); // Sees prior context
+session.chat('Summarize what we discussed');
+
+const branch = await session.fork(2); // Fork at turn 2
+branch.chat('What about artificial photosynthesis?');
+
+await branch.close();
+await session.close();
 ```
 
-`createLimen()` returns a deeply frozen object. Every method is immutable. Two calls produce fully independent instances -- no shared state, no cross-contamination.
+Context window is managed automatically -- including summarization when the window fills.
 
-> **Important: Master Key Management**
->
-> The `masterKey` is used for AES-256-GCM encryption at rest. If you lose the key, encrypted data in the SQLite database becomes permanently unreadable. Do **not** use `crypto.randomBytes(32)` in production — that generates a new key on every startup.
->
-> ```bash
-> # Generate once, store securely
-> node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" > master.key
-> chmod 600 master.key
-> ```
->
-> ```typescript
-> // Load from file or environment
-> const masterKey = Buffer.from(process.env.LIMEN_MASTER_KEY!, 'hex');
-> // or
-> const masterKey = fs.readFileSync('./master.key', 'utf8').trim();
-> ```
->
-> Keep the key out of version control. Rotate by re-encrypting: create a new engine instance with the new key and migrate data through the public API.
+### Missions
+
+```typescript
+await limen.agents.register({
+  name: 'researcher',
+  capabilities: ['web', 'data'],
+});
+
+const mission = await limen.missions.create({
+  agent: 'researcher',
+  objective: 'Analyze the renewable energy market in Europe',
+  constraints: {
+    tokenBudget: 50_000,
+    deadline: new Date(Date.now() + 3_600_000).toISOString(),
+    capabilities: ['web', 'data'],
+    maxTasks: 10,
+  },
+  deliverables: [
+    { type: 'report', name: 'market-analysis' },
+  ],
+});
+
+mission.on('checkpoint', (payload) => console.log('Checkpoint:', payload));
+const result = await mission.wait();
+```
+
+Missions are budget-governed, deadline-enforced, and operate exclusively through the 16 system calls. The lifecycle transitions through: `CREATED` -> `PLANNING` -> `EXECUTING` -> `REVIEWING` -> `COMPLETED`.
+
+See [`examples/`](examples/) for full runnable code.
+
+---
+
+## Trust Surface
+
+Every claim in this section links to a proof document with file-and-line-number evidence. Every gap is declared.
+
+| Claim | Status | Proof |
+|---|---|---|
+| 16 system calls | All Verified | [system-calls.md](docs/proof/system-calls.md) |
+| 134 invariants across 3 tiers | 114 Verified, 1 Measured, 4 Implemented, 11 Declared, 4 Out of Scope | [invariants.md](docs/proof/invariants.md) |
+| 21 failure mode defenses (of 45 specified) | 12 Verified, 8 Implemented, 1 Declared -- [24 have zero code presence](docs/proof/failure-modes.md) | [failure-modes.md](docs/proof/failure-modes.md) |
+| 8 security mechanisms | All Verified at mechanism level -- [25 declared non-protections](docs/proof/security-model.md) | [security-model.md](docs/proof/security-model.md) |
+
+Full evidence summary, including an explicit "What Is NOT Proven" section: [readiness.md](docs/proof/readiness.md).
+
+Evidence classes: **Verified** = source enforcement + meaningful tests. **Implemented** = source enforcement, weak/no tests. **Measured** = quantitative measurement with threshold. **Declared** = spec/documentation only. **Out of Scope** = not applicable to current version.
 
 ---
 
@@ -174,6 +195,73 @@ Limen is built as four layers, each with a strict dependency direction: down onl
 
 ---
 
+## Providers
+
+Six providers, zero SDKs. All communication is raw HTTP via `fetch`.
+
+| Provider | Adapter Factory | Streaming | Auth |
+|---|---|---|---|
+| **Anthropic** | `createAnthropicAdapter(apiKey, baseUrl?)` | SSE | Bearer token |
+| **OpenAI** | `createOpenAIAdapter(apiKey, baseUrl?)` | SSE | Bearer token |
+| **Google Gemini** | `createGeminiAdapter(apiKey, baseUrl?)` | SSE | Query param |
+| **Groq** | `createGroqAdapter(apiKey, baseUrl?)` | SSE | Bearer token |
+| **Mistral** | `createMistralAdapter(apiKey, baseUrl?)` | SSE | Bearer token |
+| **Ollama** | `createOllamaAdapter(baseUrl?)` | NDJSON | None (local) |
+
+Each provider also has a `*FromEnv()` variant that reads the API key from the environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`). Ollama runs locally and requires no authentication.
+
+Configure multiple providers at the engine level:
+
+```typescript
+const limen = await createLimen({
+  dataDir: './data',
+  masterKey: Buffer.from(process.env.LIMEN_MASTER_KEY!, 'hex'),
+  providers: [
+    {
+      type: 'anthropic',
+      baseUrl: 'https://api.anthropic.com',
+      models: ['claude-sonnet-4-20250514'],
+      apiKeyEnvVar: 'ANTHROPIC_API_KEY',
+      maxConcurrent: 5,
+    },
+    {
+      type: 'openai',
+      baseUrl: 'https://api.openai.com',
+      models: ['gpt-4o'],
+      apiKeyEnvVar: 'OPENAI_API_KEY',
+    },
+    {
+      type: 'ollama',
+      baseUrl: 'http://localhost:11434',
+      models: ['llama3.2'],
+    },
+  ],
+});
+```
+
+---
+
+## How Limen Compares
+
+*As of March 2026. Limen is a new project with near-zero community adoption. Vercel AI SDK and LangChain are mature ecosystems with large communities, extensive integrations, and production deployment track records that Limen does not have.*
+
+|  | Limen | Vercel AI SDK | LangChain.js |
+|---|---|---|---|
+| **Production deps** | 1 | ~50+ | ~50+ |
+| **Provider communication** | Raw HTTP (no provider SDKs) | Provider SDK packages (`@ai-sdk/*`) | Provider SDK packages (`@langchain/*`) |
+| **Built-in persistence** | SQLite (WAL, local) | No | Optional (external DB) |
+| **Audit trail** | Hash-chained, append-only | No | LangSmith (paid SaaS) |
+| **Budget enforcement** | Per-mission token budgets | No | No |
+| **Agent governance** | 16 system calls, RBAC | No | No |
+| **Multi-tenant isolation** | Row-level or database-level | No | No |
+| **Encryption at rest** | AES-256-GCM (per-field vault) | No | No |
+| **Streaming** | SSE/NDJSON with stall detection and timeouts | SSE | SSE |
+| **Structured output** | JSON Schema + auto-retry | Zod schemas | Output parsers |
+
+Limen occupies a different architectural position than these tools. Vercel AI SDK is an excellent lightweight interface for LLM communication. LangChain provides a broad ecosystem of integrations, agents, and retrieval patterns. Limen is an operating system for agent governance -- it enforces boundaries, tracks budgets, audits mutations, and isolates tenants. If your primary need is calling an LLM or composing a retrieval pipeline, those tools are more appropriate. If your primary need is enforced governance over agent behavior with full auditability, that is what Limen was built for.
+
+---
+
 ## Three Export Paths
 
 Limen ships three independent entry points. Use the full engine, the reference agent, or the transport layer alone.
@@ -204,7 +292,7 @@ const result = await agent.runMission({
   objective: 'Analyze competitive landscape for drone delivery in Southeast Asia',
   constraints: {
     tokenBudget: 50_000,
-    deadline: '2024-12-31T23:59:59Z',
+    deadline: '2026-12-31T23:59:59Z',
     capabilities: ['web', 'data'],
   },
 });
@@ -251,125 +339,11 @@ engine.shutdown(); // Aborts in-flight, rejects new requests
 
 ---
 
-## Providers
-
-Six providers, zero SDKs. All communication is raw HTTP via `fetch`.
-
-| Provider | Adapter Factory | Streaming | Auth |
-|---|---|---|---|
-| **Anthropic** | `createAnthropicAdapter(apiKey, baseUrl?)` | SSE | Bearer token |
-| **OpenAI** | `createOpenAIAdapter(apiKey, baseUrl?)` | SSE | Bearer token |
-| **Google Gemini** | `createGeminiAdapter(apiKey, baseUrl?)` | SSE | Query param |
-| **Groq** | `createGroqAdapter(apiKey, baseUrl?)` | SSE | Bearer token |
-| **Mistral** | `createMistralAdapter(apiKey, baseUrl?)` | SSE | Bearer token |
-| **Ollama** | `createOllamaAdapter(baseUrl?)` | NDJSON | None (local) |
-
-Each provider also has a `*FromEnv()` variant that reads the API key from the environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`). Ollama runs locally and requires no authentication.
-
-Configure providers at the engine level:
-
-```typescript
-const limen = await createLimen({
-  dataDir: './data',
-  masterKey: crypto.randomBytes(32),
-  providers: [
-    {
-      type: 'anthropic',
-      baseUrl: 'https://api.anthropic.com',
-      models: ['claude-sonnet-4-20250514'],
-      apiKeyEnvVar: 'ANTHROPIC_API_KEY',
-      maxConcurrent: 5,
-    },
-    {
-      type: 'openai',
-      baseUrl: 'https://api.openai.com',
-      models: ['gpt-4o'],
-      apiKeyEnvVar: 'OPENAI_API_KEY',
-    },
-    {
-      type: 'ollama',
-      baseUrl: 'http://localhost:11434',
-      models: ['llama3.2'],
-    },
-  ],
-});
-```
-
----
-
-## Sessions and Conversations
-
-Sessions bind a conversation to an agent and tenant context. Within a session, conversation history is maintained, turns are recorded, and the context window is managed automatically -- including summarization when the window fills.
-
-```typescript
-const session = await limen.session({
-  agentName: 'researcher',
-  tenantId: 'tenant-1' as TenantId,
-  user: { id: 'user-42', role: 'analyst' },
-});
-
-// Chat within session context
-const r1 = session.chat('What were last quarter earnings?');
-const r2 = session.chat('Compare that to the previous year');
-
-// Structured inference within the same conversation
-const summary = await session.infer({
-  input: 'Summarize our conversation so far',
-  outputSchema: SummarySchema,
-});
-
-// Fork conversation at a specific turn
-const branch = await session.fork(3);
-
-// Review history
-const turns = await session.history();
-
-await session.close();
-```
-
----
-
-## Autonomous Missions
-
-Missions are how agents do complex, multi-step work within enforced boundaries. An agent proposes an objective with a token budget and deadline. The system validates the proposal, and the agent then works through a cycle of planning (task graphs), execution, artifact creation, checkpoints, and result submission -- all through the 16 system calls.
-
-```typescript
-const mission = await limen.missions.create({
-  agent: 'researcher',
-  objective: 'Produce a competitive analysis report',
-  constraints: {
-    tokenBudget: 100_000,
-    deadline: '2024-12-31T23:59:59Z',
-    capabilities: ['web', 'data', 'code'],
-    maxTasks: 20,
-  },
-  deliverables: [
-    { type: 'report', name: 'competitive-analysis' },
-    { type: 'data', name: 'market-data' },
-  ],
-});
-
-// Monitor
-mission.on('checkpoint', (payload) => {
-  console.log('Checkpoint:', payload);
-});
-
-// Wait for completion
-const result = await mission.wait();
-console.log(result.summary);
-console.log(`Confidence: ${result.confidence}`);
-console.log(`Tokens used: ${result.resourcesConsumed.tokens}`);
-```
-
-The mission lifecycle transitions through: `CREATED` -> `PLANNING` -> `EXECUTING` -> `REVIEWING` -> `COMPLETED`. At any point, a mission can be paused, resumed, or cancelled. Budget enforcement is continuous -- if a mission exceeds its allocation, it is blocked until more budget is requested and approved.
-
----
-
 ## The 16 System Calls
 
 Every agent interaction with the engine passes through exactly 16 system calls. This is the governance boundary. Agents propose; the system validates and executes.
 
-**Orchestration** — mission lifecycle and task governance:
+**Orchestration** -- mission lifecycle and task governance:
 
 | # | Call | What It Does |
 |---|---|---|
@@ -384,7 +358,7 @@ Every agent interaction with the engine passes through exactly 16 system calls.
 | SC-9 | `submit_result` | Deliver final results with confidence score |
 | SC-10 | `respond_checkpoint` | Answer a system checkpoint with assessment |
 
-**Claim Protocol** — structured knowledge with provenance:
+**Claim Protocol** -- structured knowledge with provenance:
 
 | # | Call | What It Does |
 |---|---|---|
@@ -392,7 +366,7 @@ Every agent interaction with the engine passes through exactly 16 system calls.
 | SC-12 | `relate_claims` | Create typed relationships between claims |
 | SC-13 | `query_claims` | Query claims by subject, predicate, mission, or artifact |
 
-**Working Memory** — task-scoped ephemeral state:
+**Working Memory** -- task-scoped ephemeral state:
 
 | # | Call | What It Does |
 |---|---|---|
@@ -404,9 +378,92 @@ An agent cannot bypass these calls. It cannot write to the database, emit lifecy
 
 ---
 
-## The Invariant System
+## Configuration Reference
+
+```typescript
+interface LimenConfig {
+  dataDir: string;                           // Where all engine state lives
+  masterKey: Buffer;                         // >= 32 bytes, for AES-256-GCM encryption
+  providers?: ProviderConfig[];              // LLM provider configurations
+  tenancy?: {
+    mode: 'single' | 'multi';               // Default: 'single'
+    isolation?: 'row-level' | 'database';    // Multi-tenant isolation strategy
+  };
+  substrate?: {
+    maxWorkers?: number;                     // Worker pool size (default: 4)
+    schedulerPolicy?: 'deadline' | 'fair-share' | 'budget-aware';
+  };
+  offline?: {                                // Offline/disconnected operation (S30)
+    embeddings?: boolean;                    // Enable local embedding cache
+    queueSize?: number;                      // Offline operation queue size
+    syncOnReconnect?: boolean;               // Auto-sync when connectivity returns
+  };
+  hitl?: HitlConfig;                         // Human-in-the-loop defaults
+  safety?: {                                 // Safety gate configuration (DL-5)
+    enabled?: boolean;                       // Enable pre/post-safety gates (default: true)
+    jitterEnabled?: boolean;                 // Add jitter to safety timing
+  };
+  defaultTimeoutMs?: number;                 // Chat/infer timeout (default: 60000)
+  rateLimiting?: {
+    apiCallsPerMinute?: number;              // Default: 100
+    emitEventPerMinute?: number;             // Event emission rate limit
+    maxConcurrentStreams?: number;            // Default: 50
+  };
+  failoverPolicy?: 'degrade' | 'allow-overdraft' | 'block';  // Provider failure behavior (FM-12)
+  logger?: (event: LimenLogEvent) => void;  // Structured logging callback
+}
+```
+
+All fields except `dataDir` and `masterKey` are optional. When `createLimen()` is called with no arguments, provider detection, key generation, and data directory are resolved automatically from environment variables. See [getting-started.md](docs/getting-started.md) for details.
+
+---
+
+## Quick Start Paths
+
+### Demo (zero-config)
+
+```bash
+npm install limen-ai
+export ANTHROPIC_API_KEY=sk-ant-...  # or OPENAI_API_KEY, GEMINI_API_KEY, etc.
+npx tsx examples/01-hello.ts
+```
+
+Auto-detects provider, generates a dev encryption key (`~/.limen/dev.key`), stores data in OS temp directory. No configuration file needed.
+
+### Production (explicit config)
+
+```typescript
+import { createLimen } from 'limen-ai';
 
-Limen enforces 99 invariants continuously. These are not guidelines or best practices. They are machine-verified properties of the running system, each backed by dedicated tests. A violation of any invariant is a system defect.
+const limen = await createLimen({
+  dataDir: '/var/lib/myapp/limen',
+  masterKey: Buffer.from(process.env.LIMEN_MASTER_KEY!, 'hex'),
+  providers: [{
+    type: 'anthropic',
+    baseUrl: 'https://api.anthropic.com',
+    models: ['claude-sonnet-4-20250514'],
+    apiKeyEnvVar: 'ANTHROPIC_API_KEY',
+  }],
+  tenancy: { mode: 'multi', isolation: 'row-level' },
+});
+```
+
+> **Master key management:** The `masterKey` is used for AES-256-GCM encryption at rest. If you lose the key, encrypted data becomes permanently unreadable. Generate once, store securely:
+>
+> ```bash
+> node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" > master.key
+> chmod 600 master.key
+> ```
+>
+> Keep the key out of version control. Rotate by re-encrypting: create a new engine instance with the new key and migrate data through the public API.
+
+See [getting-started.md](docs/getting-started.md) for the full walkthrough.
+
+---
+
+## Invariant System
+
+Limen defines 134 invariants across 3 tiers. 114 are Verified (source enforcement with dedicated tests), 1 Measured, and 19 carry lower evidence classes — see the [full evidence index](docs/proof/invariants.md). A violation of any enforced invariant is a system defect.
 
 | Invariant | Guarantee |
 |---|---|
@@ -427,7 +484,7 @@ Limen enforces 99 invariants continuously. These are not guidelines or best prac
 | **I-26** | Streaming and non-streaming produce identical results |
 | **I-28** | Pipeline phases execute in fixed, deterministic order |
 
-These invariants are what make AI infrastructure trustworthy. When your agent runs a mission overnight, I-03 guarantees you can audit every action it took. I-17 guarantees it never bypassed the governance layer. I-20 guarantees it didn't spawn an unbounded tree of sub-missions. I-19 guarantees no artifact was silently modified after creation.
+These invariants are what make AI infrastructure trustworthy. When your agent runs a mission overnight, I-03 guarantees you can audit every action it took. I-17 guarantees it never bypassed the governance layer. I-20 guarantees it did not spawn an unbounded tree of sub-missions. I-19 guarantees no artifact was silently modified after creation.
 
 ---
 
@@ -453,33 +510,6 @@ Health distinguishes between three states: **healthy** (all subsystems operation
 
 ---
 
-## Configuration Reference
-
-```typescript
-interface LimenConfig {
-  dataDir: string;                           // Where all engine state lives
-  masterKey: Buffer;                         // >= 32 bytes, for AES-256-GCM encryption
-  providers?: ProviderConfig[];              // LLM provider configurations
-  tenancy?: {
-    mode: 'single' | 'multi';               // Default: 'single'
-    isolation?: 'row-level' | 'database';    // Multi-tenant isolation strategy
-  };
-  substrate?: {
-    maxWorkers?: number;                     // Worker pool size (default: 4)
-    schedulerPolicy?: 'deadline' | 'fair-share' | 'budget-aware';
-  };
-  hitl?: HitlConfig;                         // Human-in-the-loop defaults
-  defaultTimeoutMs?: number;                 // Chat/infer timeout (default: 60000)
-  rateLimiting?: {
-    apiCallsPerMinute?: number;              // Default: 100
-    maxConcurrentStreams?: number;            // Default: 50
-  };
-  logger?: (event: LimenLogEvent) => void;  // Structured logging callback
-}
-```
-
----
-
 ## Error Handling
 
 Every error thrown by Limen is a `LimenError` with a typed code, a human-readable message, a `retryable` flag, and an optional `cooldownMs` for rate-limited responses.
@@ -512,7 +542,7 @@ npm install
 
 npm run typecheck    # TypeScript strict mode, zero errors
 npm run build        # Compile to dist/
-npm test             # Full test suite
+npm test             # Full test suite (2,447+ tests)
 npm run ci           # typecheck + build + test
 ```
 

package/dist/api/agents/trust_progression.d.ts

@@ -53,7 +53,7 @@ export declare function validatePromotion(fromLevel: TrustLevel, targetLevel: Tr
  * @param targetAgentId - The agent being promoted
  * @returns { allowed: true } if not self-promotion, { allowed: false } if blocked
  */
-export declare function checkSelfPromotion(ctxAgentId: AgentId | null | undefined, targetAgentId: string): {
+export declare function checkSelfPromotion(ctxAgentId: AgentId | null | undefined, targetAgentId: AgentId | string): {
     allowed: true;
 } | {
     allowed: false;

package/dist/api/agents/trust_progression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trust_progression.d.ts","sourceRoot":"","sources":["../../../src/api/agents/trust_progression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAIhE,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC;AAgB5E;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,UAAU,EACrB,WAAW,EAAE,UAAU,EACvB,SAAS,EAAE,QAAQ,GAAG,OAAO,GAC5B;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA4BpD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,EACtC,aAAa,EAAE,MAAM,GACpB;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAQxD;AAID;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,UAAU,EACxB,QAAQ,EAAE,iBAAiB,GAC1B,UAAU,GAAG,IAAI,CAmBnB"}
+{"version":3,"file":"trust_progression.d.ts","sourceRoot":"","sources":["../../../src/api/agents/trust_progression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAIhE,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC;AAgB5E;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,UAAU,EACrB,WAAW,EAAE,UAAU,EACvB,SAAS,EAAE,QAAQ,GAAG,OAAO,GAC5B;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA4BpD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,EACtC,aAAa,EAAE,OAAO,GAAG,MAAM,GAC9B;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAQxD;AAID;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,UAAU,EACxB,QAAQ,EAAE,iBAAiB,GAC1B,UAAU,GAAG,IAAI,CAmBnB"}