@framers/agentos 0.1.135 → 0.1.136

package/README.md

@@ -10,6 +10,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@framers/agentos?style=flat-square&logo=npm&color=cb3837)](https://www.npmjs.com/package/@framers/agentos)
 [![CI](https://img.shields.io/github/actions/workflow/status/framersai/agentos/ci.yml?branch=master&style=flat-square&logo=github&label=CI)](https://github.com/framersai/agentos/actions/workflows/ci.yml)
+[![tests](https://img.shields.io/badge/tests-3%2C866%2B_passed-brightgreen?style=flat-square&logo=vitest)](https://github.com/framersai/agentos/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/framersai/agentos/graph/badge.svg)](https://codecov.io/gh/framersai/agentos)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.4+-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
@@ -40,6 +41,7 @@
   - [Planning Engine](#planning-engine)
   - [Conversation Management](#conversation-management)
   - [RAG (Retrieval Augmented Generation)](#rag-retrieval-augmented-generation)
+  - [Bundled Platform Knowledge](#bundled-platform-knowledge)
   - [Safety and Guardrails](#safety-and-guardrails)
   - [Human-in-the-Loop (HITL)](#human-in-the-loop-hitl)
   - [Channels System](#channels-system)
@@ -83,7 +85,7 @@
 
 ## Overview
 
-`@framers/agentos` is an open-source TypeScript AI agent runtime for building, deploying, and managing production AI agents. It provides multimodal RAG with cognitive memory (Ebbinghaus decay), multi-agent orchestration, 37 channel adapters, 5-tier guardrails with prompt injection defense, 21 LLM providers, and 40 curated skills. Self-hostable and production-ready, it handles the full lifecycle from prompt construction through tool execution, safety evaluation, and streaming response delivery.
+`@framers/agentos` is an open-source TypeScript AI agent runtime for building, deploying, and managing production AI agents. It provides multimodal RAG with cognitive memory (Ebbinghaus decay, 8 neuroscience-backed mechanisms including reconsolidation, retrieval-induced forgetting, involuntary recall, metacognitive FOK, temporal gist extraction, schema encoding, source confidence decay, and emotion regulation — all HEXACO personality-modulated), multi-agent orchestration, 37 channel adapters, 5-tier guardrails with prompt injection defense, 21 LLM providers, and 72 curated skills. Self-hostable and production-ready, it handles the full lifecycle from prompt construction through tool execution, safety evaluation, and streaming response delivery.
 
 **Key facts:**
 
@@ -106,14 +108,19 @@
 | `uuid` | Unique identifier generation |
 | `yaml` | YAML config parsing (agent configs, skill definitions) |
 
+**Required peer dependency:**
+
+| Dependency | Purpose |
+|------------|---------|
+| `@framers/sql-storage-adapter` | Cross-platform SQL persistence (SQLite, sql.js, IndexedDB, Postgres) — required for memory, knowledge graph, and trace storage |
+
 **Optional peer dependencies:**
 
 | Peer Dependency | Purpose |
 |-----------------|---------|
-| `@framers/sql-storage-adapter` | SQL-backed vector store and persistence |
-| `graphology` + `graphology-communities-louvain` | GraphRAG community detection |
-| `hnswlib-node` | HNSW-based approximate nearest neighbor search |
-| `neo4j-driver` | Neo4j-backed vector + GraphRAG persistence |
+| `graphology` + `graphology-communities-louvain` | GraphRAG community detection and memory graph clustering |
+| `hnswlib-node` | HNSW-based approximate nearest neighbor search (falls back to brute-force without) |
+| `neo4j-driver` | Neo4j-backed knowledge graph and GraphRAG (falls back to SQLite without) |
 
 ---
 
@@ -125,7 +132,7 @@
 | **@framers/agentos-extensions** | Official extension registry (45+ extensions) | [![npm](https://img.shields.io/npm/v/@framers/agentos-extensions?style=flat-square&logo=npm&label=)](https://www.npmjs.com/package/@framers/agentos-extensions) · [GitHub](https://github.com/framersai/agentos-extensions) |
 | **@framers/agentos-extensions-registry** | Curated manifest builder | [![npm](https://img.shields.io/npm/v/@framers/agentos-extensions-registry?style=flat-square&logo=npm&label=)](https://www.npmjs.com/package/@framers/agentos-extensions-registry) · [GitHub](https://github.com/framersai/agentos-extensions-registry) |
 | **@framers/agentos-skills-registry** | Skills catalog SDK (query helpers + snapshot factories) | [![npm](https://img.shields.io/npm/v/@framers/agentos-skills-registry?style=flat-square&logo=npm&label=)](https://www.npmjs.com/package/@framers/agentos-skills-registry) · [GitHub](https://github.com/framersai/agentos-skills-registry) |
-| **@framers/agentos-skills** | Skills content (69 SKILL.md files + registry.json) | [![npm](https://img.shields.io/npm/v/@framers/agentos-skills?style=flat-square&logo=npm&label=)](https://www.npmjs.com/package/@framers/agentos-skills) · [GitHub](https://github.com/framersai/agentos-skills) |
+| **@framers/agentos-skills** | Skills content (72 SKILL.md files + registry.json) | [![npm](https://img.shields.io/npm/v/@framers/agentos-skills?style=flat-square&logo=npm&label=)](https://www.npmjs.com/package/@framers/agentos-skills) · [GitHub](https://github.com/framersai/agentos-skills) |
 | **docs.agentos.sh** | Documentation site (Docusaurus) | [GitHub](https://github.com/framersai/agentos-live-docs) · [docs.agentos.sh](https://docs.agentos.sh) |
 
 ### Guardrail Extensions
@@ -176,8 +183,9 @@ const result = await team.generate('Summarise recent advances in fusion energy.'
 console.log(result.text);
 ```
 
-Set `OPENAI_API_KEY` (or another provider's key) and the agency auto-detects the
-provider.  All five strategies are available out of the box:
+Set any provider's API key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`,
+`GROQ_API_KEY`, `OLLAMA_BASE_URL`, etc.) and the agency auto-detects the provider.
+All five strategies are available out of the box:
 
 | Strategy | What it does |
 |---|---|
@@ -214,23 +222,157 @@ Use the streamlined helpers when you want AI SDK-style text generation, structur
 output extraction, embedding generation, image generation, or a single stateful
 session without a multi-agent team.
 
+#### Provider-First Pattern (Recommended)
+
+The recommended way to call any helper is **provider-first**: specify the provider
+name and let AgentOS pick the best default model automatically. No model string
+needed -- just set the matching environment variable and go.
+
 ```typescript
-import {
-  agent, embedText, generateImage, generateObject, generateText, streamText, streamObject,
-} from '@framers/agentos';
-import { z } from 'zod';
+import { generateText, streamText, agent } from '@framers/agentos';
 
-// Provider-first: AgentOS picks the best default model automatically.
-// Requires OPENAI_API_KEY (or the matching env var) to be set.
-const quick = await generateText({
+// Provider-first -- AgentOS picks the best default model
+const result = await generateText({
   provider: 'openai',
-  prompt: 'Explain how TCP handshakes work in 3 bullets.',
+  prompt: 'Explain TCP handshakes in 3 bullets.',
 });
 
-console.log(quick.text);
+// Works with any provider -- just change the name
+const result2 = await generateText({
+  provider: 'anthropic',
+  prompt: 'Explain TCP handshakes in 3 bullets.',
+});
 
-const live = streamText({
+// Local models via Ollama -- zero API keys
+const result3 = await generateText({
+  provider: 'ollama',
+  prompt: 'Explain TCP handshakes in 3 bullets.',
+});
+```
+
+The same pattern works across **every helper function**: `generateText`, `streamText`,
+`generateObject`, `streamObject`, `embedText`, `generateImage`, and `agent`.
+
+#### Default Models Per Provider
+
+When you use the provider-first pattern, AgentOS resolves the default model
+from a built-in registry. Set the matching env var and you are ready to go:
+
+| Provider | Default Model | Env Var |
+|---|---|---|
+| `openai` | `gpt-4o` | `OPENAI_API_KEY` |
+| `anthropic` | `claude-sonnet-4-20250514` | `ANTHROPIC_API_KEY` |
+| `gemini` | `gemini-2.5-flash` | `GEMINI_API_KEY` |
+| `ollama` | `llama3.2` | `OLLAMA_BASE_URL` |
+| `groq` | `llama-3.3-70b-versatile` | `GROQ_API_KEY` |
+| `openrouter` | `openai/gpt-4o` | `OPENROUTER_API_KEY` |
+| `together` | `Meta-Llama-3.1-70B-Instruct-Turbo` | `TOGETHER_API_KEY` |
+| `mistral` | `mistral-large-latest` | `MISTRAL_API_KEY` |
+| `xai` | `grok-2` | `XAI_API_KEY` |
+
+See `src/api/runtime/provider-defaults.ts` for the full registry including image
+and embedding defaults.
+
+#### Multi-Provider Showcase
+
+The **same prompt** works across every supported provider -- swap one string:
+
+```typescript
+import { generateText } from '@framers/agentos';
+
+// OpenAI
+await generateText({ provider: 'openai', prompt: 'What is QUIC?' });
+
+// Anthropic
+await generateText({ provider: 'anthropic', prompt: 'What is QUIC?' });
+
+// Google Gemini
+await generateText({ provider: 'gemini', prompt: 'What is QUIC?' });
+
+// Groq (fast inference)
+await generateText({ provider: 'groq', prompt: 'What is QUIC?' });
+
+// Local via Ollama (no API key needed)
+await generateText({ provider: 'ollama', prompt: 'What is QUIC?' });
+
+// OpenRouter (200+ models, auto-routing)
+await generateText({ provider: 'openrouter', prompt: 'What is QUIC?' });
+
+// Mistral
+await generateText({ provider: 'mistral', prompt: 'What is QUIC?' });
+
+// xAI (Grok)
+await generateText({ provider: 'xai', prompt: 'What is QUIC?' });
+```
+
+#### Provider + Model Override
+
+When you need a specific model instead of the default, pass both:
+
+```typescript
+// Cheaper model for high-volume workloads
+await generateText({
   provider: 'openai',
+  model: 'gpt-4o-mini',
+  prompt: 'Classify this support ticket.',
+});
+
+// Specific Anthropic model
+await generateText({
+  provider: 'anthropic',
+  model: 'claude-haiku-4-5-20251001',
+  prompt: 'Summarise this paragraph.',
+});
+
+// Specific Ollama model
+await generateText({
+  provider: 'ollama',
+  model: 'codellama',
+  prompt: 'Write a Python fizzbuzz.',
+});
+```
+
+#### Global Defaults via Environment Variables
+
+AgentOS auto-detects your active provider by scanning environment variables in
+priority order. Set one key and every call uses that provider automatically --
+no `provider` field needed:
+
+```bash
+# Set one of these -- AgentOS picks the first it finds:
+# Priority: OPENROUTER > OPENAI > ANTHROPIC > GEMINI > GROQ > TOGETHER > MISTRAL > XAI > OLLAMA
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+```typescript
+import { generateText } from '@framers/agentos';
+
+// No provider or model needed -- auto-detected from env vars
+const result = await generateText({ prompt: 'Hello world' });
+```
+
+#### Legacy Format
+
+The `provider:model` string format still works but provider-first is preferred:
+
+```typescript
+// Legacy format -- still fully supported but not recommended for new code
+await generateText({ model: 'openai:gpt-4o', prompt: '...' });
+await generateText({ model: 'anthropic:claude-sonnet-4-20250514', prompt: '...' });
+await generateText({ model: 'ollama:llama3.2', prompt: '...' });
+```
+
+#### Streaming, Structured Output, Images, and Embeddings
+
+```typescript
+import {
+  agent, embedText, generateImage, generateObject, streamText, streamObject,
+} from '@framers/agentos';
+import { z } from 'zod';
+
+// Streaming with Anthropic
+const live = streamText({
+  provider: 'anthropic',
   prompt: 'Stream a short explanation of SYN, SYN-ACK, ACK.',
 });
 
@@ -238,6 +380,7 @@ for await (const delta of live.textStream) {
   process.stdout.write(delta);
 }
 
+// Image generation with OpenAI
 const image = await generateImage({
   provider: 'openai',
   prompt: 'A cinematic neon city skyline reflected in rain at night.',
@@ -245,18 +388,18 @@ const image = await generateImage({
 
 console.log(image.images[0]?.mimeType);
 
-// Structured output — Zod-validated JSON extraction
+// Structured output with Gemini -- Zod-validated JSON extraction
 const { object } = await generateObject({
-  model: 'openai:gpt-4o',
+  provider: 'gemini',
   schema: z.object({ name: z.string(), age: z.number() }),
   prompt: 'Extract: "John is 30 years old"',
 });
 
 console.log(object.name, object.age); // "John" 30
 
-// Streaming structured output — partial objects as JSON builds up
+// Streaming structured output with Groq
 const structured = streamObject({
-  model: 'openai:gpt-4o',
+  provider: 'groq',
   schema: z.object({ title: z.string(), tags: z.array(z.string()) }),
   prompt: 'Generate metadata for an article about TCP.',
 });
@@ -266,17 +409,18 @@ for await (const partial of structured.partialObjectStream) {
 }
 console.log('final:', await structured.object);
 
-// Embeddings — single or batch
+// Embeddings -- single or batch (OpenAI)
 const { embeddings } = await embedText({
-  model: 'openai:text-embedding-3-small',
+  provider: 'openai',
   input: ['Hello world', 'Goodbye world'],
   dimensions: 256,
 });
 
 console.log(embeddings.length, embeddings[0].length); // 2, 256
 
+// Stateful agent session with Anthropic
 const assistant = agent({
-  provider: 'openai',
+  provider: 'anthropic',
   instructions: 'You are a concise networking tutor.',
   maxSteps: 3,
 });
@@ -285,9 +429,6 @@ const session = assistant.session('tcp-demo');
 const reply = await session.send('Now compare TCP and UDP.');
 console.log(reply.text);
 console.log(await session.usage());
-
-// Legacy format — still supported:
-// const result = await generateText({ model: 'openai:gpt-4o', prompt: '...' });
 ```
 
 If you want durable helper-level usage accounting outside the full runtime, enable
@@ -297,7 +438,7 @@ the opt-in usage ledger:
 import { generateText, getRecordedAgentOSUsage } from '@framers/agentos';
 
 await generateText({
-  provider: 'openai',
+  provider: 'anthropic',
   prompt: 'Explain HTTP keep-alive.',
   usageLedger: { enabled: true, sessionId: 'readme-demo' },
 });
@@ -386,7 +527,7 @@ graph TB
         Plan --> ReAct["ReAct<br/>Reasoner"]
 
         subgraph LLM["LLM Provider Manager"]
-            OAI["OpenAI"] ~~~ Anth["Anthropic"] ~~~ Az["Azure"] ~~~ Oll["Ollama"] ~~~ OR["OpenRouter"]
+            OAI["OpenAI"] ~~~ Anth["Anthropic"] ~~~ Gem["Gemini"] ~~~ Oll["Ollama"] ~~~ OR["OpenRouter"]
         end
 
         Tools --> LLM
@@ -524,12 +665,36 @@ graph TB
   - `Generalist` -- Balanced, conversational
   - `Atlas` -- Navigation and spatial reasoning
   - `Default Assistant` -- General-purpose helpful assistant
-- **Memory subsystem** (`memory/`) -- Four-layer memory architecture:
-  - **Working memory** -- Current session state, active tool context, conversation buffer
-  - **Episodic memory** -- Timestamped events and interactions
-  - **Semantic memory** -- Extracted facts, entity relationships, domain knowledge
-  - **Procedural memory** -- Learned skills, patterns, and execution strategies
-  - **Cognitive mechanisms** (`memory/mechanisms/`) -- 8 optional neuroscience-grounded mechanisms: reconsolidation drift (Nader et al., 2000), retrieval-induced forgetting (Anderson et al., 1994), involuntary recall (Berntsen, 2009), metacognitive feeling-of-knowing (Nelson & Narens, 1990), temporal gist extraction (Reyna & Brainerd, 1995), schema encoding (Bartlett, 1932), source confidence decay (Johnson et al., 1993), emotion regulation (Gross, 1998). All HEXACO personality-modulated, individually configurable. See `docs/memory/COGNITIVE_MECHANISMS.md`.
+- **Memory subsystem** (`memory/`) -- 5 memory types, 4-tier hierarchy, 8 cognitive mechanisms:
+
+  **Memory types** (Tulving's long-term memory taxonomy):
+  | Type | Cognitive Model | Usage |
+  |------|----------------|-------|
+  | `episodic` | Autobiographical events | Conversation events, interactions |
+  | `semantic` | General knowledge/facts | Learned facts, preferences, schemas |
+  | `procedural` | Skills and how-to | Workflows, tool usage patterns |
+  | `prospective` | Future intentions | Goals, reminders, planned actions |
+  | `working` | Baddeley's model | Current session state, active context (7 +/- 2 slots) |
+
+  **4-tier directory hierarchy:**
+  - `core/` -- Types, config, encoding (Yerkes-Dodson, flashbulb, HEXACO-weighted), decay (Ebbinghaus curves + spaced repetition), working memory, prompt assembly
+  - `retrieval/` -- MemoryStore (6-signal composite scoring), memory graph (spreading activation), prospective memory, retrieval feedback
+  - `pipeline/` -- Consolidation (merge, prune, promote, schema extraction), observation (buffer, compress, reflect), lifecycle management, infinite context window
+  - `io/` -- Document ingestion (PDF, DOCX, HTML, Markdown, URL), import/export (JSON, Obsidian, SQLite, ChatGPT, CSV), facade API, memory tools, extensions
+
+  **Cognitive mechanisms** (`memory/mechanisms/`) -- 8 optional, all HEXACO personality-modulated:
+  | Mechanism | Citation | Effect |
+  |-----------|----------|--------|
+  | Reconsolidation | [Nader et al., 2000](https://doi.org/10.1038/35021052) | Retrieved memories drift toward current mood |
+  | Retrieval-Induced Forgetting | [Anderson et al., 1994](https://doi.org/10.1037/0278-7393.20.5.1063) | Retrieving one memory suppresses similar competitors |
+  | Involuntary Recall | [Berntsen, 2009](https://doi.org/10.1017/CBO9780511575921) | Random surfacing of old high-vividness memories |
+  | Metacognitive FOK | [Nelson & Narens, 1990](https://doi.org/10.1016/S0079-7421(08)60053-5) | Feeling-of-knowing scoring for tip-of-tongue states |
+  | Temporal Gist | [Reyna & Brainerd, 1995](https://doi.org/10.1016/1041-6080(95)90003-9) | Old traces compressed to core assertions |
+  | Schema Encoding | [Bartlett, 1932](https://doi.org/10.1017/CBO9780511759185) | Novel input boosted, schema-matching encoded efficiently |
+  | Source Confidence Decay | [Johnson et al., 1993](https://doi.org/10.1037/0033-2909.114.1.3) | Agent inferences decay faster than observations |
+  | Emotion Regulation | [Gross, 1998](https://doi.org/10.1037/1089-2680.2.3.271) | Reappraisal + suppression during consolidation |
+
+  See `docs/memory/COGNITIVE_MECHANISMS.md` for API reference and 30+ APA citations.
 
 ---
 
@@ -543,21 +708,30 @@ The LLM layer abstracts multiple AI model providers behind a unified interface.
 graph TD
     PM["AIModelProviderManager<br/><i>Provider registry · Routing · Fallback · Model switching</i>"]
     PM --> OAI["OpenAI Provider<br/><code>gpt-4o · gpt-4o-mini · o1</code>"]
+    PM --> Anth["Anthropic Provider<br/><code>claude-sonnet-4 · claude-haiku</code>"]
+    PM --> Gem["Gemini Provider<br/><code>gemini-2.5-flash · gemini-2.0</code>"]
     PM --> Oll["Ollama Provider<br/><code>llama3.2 · mistral · codellama</code>"]
-    PM --> OR["OpenRouter Provider<br/><code>claude-3.5 · gemini-pro · command-r+</code>"]
+    PM --> GQ["Groq Provider<br/><code>llama-3.3-70b · gemma2-9b</code>"]
+    PM --> OR["OpenRouter Provider<br/><code>200+ models · auto-routing</code>"]
     PM --> Custom["Custom Provider<br/><i>IProvider interface</i>"]
     style PM fill:#1c1c28,stroke:#8b5cf6,color:#f2f2fa
 ```
 
 **Provider implementations:**
 
-| Provider | File | Models |
-|----------|------|--------|
-| OpenAI | `providers/implementations/OpenAIProvider.ts` | GPT-4o, GPT-4o-mini, o1, o3, etc. |
-| Ollama | `providers/implementations/OllamaProvider.ts` | Any locally-hosted model (Llama, Mistral, etc.) |
-| OpenRouter | `providers/implementations/OpenRouterProvider.ts` | 200+ models from any provider via unified API |
+| Provider | File | Models | Env Var |
+|----------|------|--------|---------|
+| OpenAI | `providers/implementations/OpenAIProvider.ts` | GPT-4o, GPT-4o-mini, o1, o3 | `OPENAI_API_KEY` |
+| Anthropic | `providers/implementations/AnthropicProvider.ts` | Claude Sonnet 4, Claude Haiku | `ANTHROPIC_API_KEY` |
+| Gemini | `providers/implementations/GeminiProvider.ts` | Gemini 2.5 Flash, Gemini 2.0 | `GEMINI_API_KEY` |
+| Groq | `providers/implementations/GroqProvider.ts` | Llama 3.3 70B, Gemma2 9B (fast inference) | `GROQ_API_KEY` |
+| Mistral | `providers/implementations/MistralProvider.ts` | Mistral Large, Mistral Small | `MISTRAL_API_KEY` |
+| Together | via OpenAI-compat | Meta-Llama 3.1 70B/8B | `TOGETHER_API_KEY` |
+| xAI | via OpenAI-compat | Grok-2, Grok-2 Mini | `XAI_API_KEY` |
+| Ollama | `providers/implementations/OllamaProvider.ts` | Any locally-hosted model | `OLLAMA_BASE_URL` |
+| OpenRouter | `providers/implementations/OpenRouterProvider.ts` | 200+ models from any provider | `OPENROUTER_API_KEY` |
 
-> **Note:** Anthropic (Claude) and Google Gemini are supported at the **Wunderland runtime** level via their respective APIs. In AgentOS, use OpenRouter to access these models, or use Wunderland's higher-level `createWunderlandSeed()` API which handles provider routing natively.
+> **Auto-detection:** When no `provider` is specified, AgentOS scans env vars in priority order (OpenRouter > OpenAI > Anthropic > Gemini > Groq > Together > Mistral > xAI > Ollama) and uses the first configured provider. Set one env var and every helper call works automatically.
 
 **Additional components:**
 
@@ -565,7 +739,17 @@ graph TD
 - **IProvider** (`providers/IProvider.ts`) -- Interface contract for adding custom LLM providers.
 - **Streaming adapters** -- All providers support token-level streaming via async generators with backpressure control.
 
-**Per-request model override:**
+**Per-request model override (high-level helpers):**
+
+```typescript
+// Provider-first: AgentOS picks the default model
+await generateText({ provider: 'gemini', prompt: 'Summarize this document' });
+
+// Override a specific model
+await generateText({ provider: 'anthropic', model: 'claude-haiku-4-5-20251001', prompt: '...' });
+```
+
+**Per-request model override (full runtime):**
 
 ```typescript
 for await (const chunk of agent.processRequest({
@@ -573,8 +757,8 @@ for await (const chunk of agent.processRequest({
   sessionId: 'session-1',
   textInput: 'Summarize this document',
   options: {
-    preferredProviderId: 'anthropic',
-    preferredModelId: 'claude-sonnet-4-5-20250929',
+    preferredProviderId: 'gemini',
+    preferredModelId: 'gemini-2.5-flash',
   },
 })) { /* ... */ }
 ```
@@ -858,6 +1042,41 @@ See [`docs/memory/MEMORY_SCALING.md`](./docs/memory/MEMORY_SCALING.md), [`docs/m
 
 ---
 
+### Bundled Platform Knowledge
+
+**Location:** `knowledge/platform-corpus.json`
+
+AgentOS ships with **243 pre-built knowledge entries** covering the entire platform surface area. When the QueryRouter initializes, these entries are automatically loaded alongside your project-specific documentation corpus, giving every agent instant knowledge about AgentOS capabilities with zero configuration.
+
+**Coverage breakdown:**
+
+| Category | Count | What it covers |
+|----------|-------|---------------|
+| Tools | 105 | Every tool and channel adapter (Discord, Telegram, LinkedIn, Bluesky, etc.) |
+| Skills | 79 | All curated skills from the skills registry |
+| FAQ | 30 | Common questions (voice setup, supported models, streaming, OCR, etc.) |
+| API | 14 | Core API functions (generateText, streamText, agent, agency, etc.) |
+| Troubleshooting | 15 | Common errors and their fixes (missing API keys, model not found, etc.) |
+
+**How it works:**
+
+- During `router.init()`, the QueryRouter loads `knowledge/platform-corpus.json` from the package directory
+- Platform entries are merged into the same corpus as user docs, making them searchable via both vector and keyword retrieval
+- The keyword fallback index covers platform entries, so they work even without an embedding API key
+
+**Disabling platform knowledge:**
+
+```typescript
+const router = new QueryRouter({
+  knowledgeCorpus: ['./docs'],
+  includePlatformKnowledge: false, // Skip bundled platform entries
+});
+```
+
+When disabled, the router only loads your `knowledgeCorpus` directories. This is useful when you want a purely project-specific knowledge base or are building a non-AgentOS product.
+
+---
+
 ### Safety and Guardrails
 
 **Location:** `src/safety/runtime/` and `src/safety/guardrails/`
@@ -1243,7 +1462,30 @@ await agent.initialize(await createAgentOSConfig());
 
 ### Multiple Providers
 
-Configure multiple LLM providers with fallback:
+**High-level helpers** (recommended): Just set env vars. No config object needed.
+
+```bash
+# Set as many provider keys as you like -- AgentOS uses them on demand
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENAI_API_KEY=sk-...
+export GEMINI_API_KEY=AIza...
+export OLLAMA_BASE_URL=http://localhost:11434
+```
+
+```typescript
+import { generateText } from '@framers/agentos';
+
+// Each call picks the right credentials from env vars automatically
+await generateText({ provider: 'anthropic', prompt: 'Hello from Claude' });
+await generateText({ provider: 'openai',    prompt: 'Hello from GPT' });
+await generateText({ provider: 'gemini',    prompt: 'Hello from Gemini' });
+await generateText({ provider: 'ollama',    prompt: 'Hello from Llama' });
+
+// Or omit provider entirely -- auto-detects the first configured one
+await generateText({ prompt: 'Hello from whichever provider is available' });
+```
+
+**Full runtime** — configure multiple providers with explicit fallback:
 
 ```typescript
 const agent = new AgentOS();
@@ -1253,10 +1495,12 @@ await agent.initialize({
   ...config,
   modelProviderManagerConfig: {
     providers: [
-      { providerId: 'openai', enabled: true, isDefault: true,
-        config: { apiKey: process.env.OPENAI_API_KEY } },
-      { providerId: 'anthropic', enabled: true,
+      { providerId: 'anthropic', enabled: true, isDefault: true,
         config: { apiKey: process.env.ANTHROPIC_API_KEY } },
+      { providerId: 'openai', enabled: true,
+        config: { apiKey: process.env.OPENAI_API_KEY } },
+      { providerId: 'gemini', enabled: true,
+        config: { apiKey: process.env.GEMINI_API_KEY } },
       { providerId: 'ollama', enabled: true,
         config: { baseUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434' } },
     ],
@@ -1265,8 +1509,8 @@ await agent.initialize({
     ...config.gmiManagerConfig,
     defaultGMIBaseConfigDefaults: {
       ...(config.gmiManagerConfig.defaultGMIBaseConfigDefaults ?? {}),
-      defaultLlmProviderId: 'openai',
-      defaultLlmModelId: 'gpt-4o',
+      defaultLlmProviderId: 'anthropic',
+      defaultLlmModelId: 'claude-sonnet-4-20250514',
     },
   },
 });
@@ -1277,8 +1521,8 @@ for await (const chunk of agent.processRequest({
   sessionId: 'session-1',
   textInput: 'Hello',
   options: {
-    preferredProviderId: 'anthropic',
-    preferredModelId: 'claude-sonnet-4-5-20250929',
+    preferredProviderId: 'gemini',
+    preferredModelId: 'gemini-2.5-flash',
   },
 })) { /* ... */ }
 ```
@@ -1286,12 +1530,16 @@ for await (const chunk of agent.processRequest({
 ### Environment Variables
 
 ```bash
-# Required: at least one LLM provider
-OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...
-GEMINI_API_KEY=AIza...
-OPENROUTER_API_KEY=sk-or-...
-OLLAMA_BASE_URL=http://localhost:11434    # local or remote URL
+# LLM providers (set at least one)
+OPENAI_API_KEY=sk-...                      # OpenAI (GPT-4o, GPT-4o-mini, o1, o3)
+ANTHROPIC_API_KEY=sk-ant-...               # Anthropic (Claude Sonnet 4, Claude Haiku)
+GEMINI_API_KEY=AIza...                     # Google Gemini (2.5 Flash, 2.0)
+OPENROUTER_API_KEY=sk-or-...              # OpenRouter (200+ models, auto-routing)
+GROQ_API_KEY=gsk_...                       # Groq (fast inference: Llama 3.3 70B)
+TOGETHER_API_KEY=...                       # Together AI (Llama, Mixtral)
+MISTRAL_API_KEY=...                        # Mistral (Mistral Large, Small)
+XAI_API_KEY=xai-...                        # xAI (Grok-2)
+OLLAMA_BASE_URL=http://localhost:11434     # Ollama (local models, no API key needed)
 
 # Database
 DATABASE_URL=file:./data/agentos.db

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.1.135",
+  "version": "0.1.136",
   "description": "Modular AgentOS orchestration library",
   "type": "module",
   "main": "dist/index.js",