joggrdocs · zrosenbauer · Apr 22, 2026 · coderabbitai · Apr 22, 2026 · coderabbitai
diff --git a/.gitignore b/.gitignore
@@ -24,6 +24,9 @@ coverage/
 # GG
 .gg/
 
+# Scratchpad
+scratchpad/
+
 # OS files
 .DS_Store
 Thumbs.db

diff --git a/README.md b/README.md
@@ -16,6 +16,15 @@
 - :lock: **Closures are state** — Flow agent state is just variables in your handler.
 - :triangular_ruler: **Type-driven design** — Zod schemas, discriminated unions, exhaustive matching.
 
+## Why funkai
+
+The [Vercel AI SDK](https://sdk.vercel.ai) is an excellent foundation for working with LLMs. funkai doesn't replace it — it's a thin, opinionated layer on top that adds functional agent composition, a prompt SDK with templating and codegen, model cost tracking, and Result-based error handling. If you're already using `ai` and want structured workflows without leaving the ecosystem, funkai fills those gaps.
+
+> [!TIP]
+> Looking for a batteries-included agent framework? Check out **[VoltAgent](https://voltagent.dev)** — a full-featured runtime with built-in observability, tool ecosystem, and everything you need out of the box. We recommend it highly, and funkai may build on top of it in the future.
+
+For a deeper comparison with alternatives, see [Why funkai](docs/why-funkai.md).
+
 ## Install
 
 ```bash

diff --git a/contributing/concepts/architecture.md b/contributing/concepts/architecture.md
@@ -13,13 +13,17 @@ The codebase follows a functional, immutable, composition-first design. There ar
 ```
 packages/
 ├── agents/          # @funkai/agents -- Workflow and agent orchestration
+├── cli/             # @funkai/cli -- CLI for the funkai framework
+├── config/          # @funkai/config -- Configuration schema and defineConfig helper
 ├── models/          # @funkai/models -- Model catalog, provider resolution, cost calculation
 └── prompts/         # @funkai/prompts -- Prompt SDK with templating and validation
 ```
 
 | Package           | Purpose                                                                                      |
 | ----------------- | -------------------------------------------------------------------------------------------- |
 | `@funkai/agents`  | Agent and workflow orchestration: agents, workflows, steps, tools, hooks, provider           |
+| `@funkai/cli`     | CLI for the funkai framework: setup, codegen, prompt management, and validation              |
+| `@funkai/config`  | Configuration schema and `defineConfig()` helper for typed `funkai.config.ts` files          |
 | `@funkai/models`  | Model catalog, provider resolution, cost calculation, and nightly model data synchronization |
 | `@funkai/prompts` | Prompt authoring SDK: LiquidJS templating, Zod validation, CLI, codegen                      |
 
@@ -134,6 +138,44 @@ The prompts package provides a prompt authoring SDK with two surfaces:
 | Partial     | Reusable template fragment included via `{% partial %}` |
 | Codegen     | Generate TypeScript types from prompt files             |
 
+## Config Package
+
+The config package provides the Zod-validated configuration schema for funkai projects. Users author a `funkai.config.ts` file and use `defineConfig()` for type-safe editor autocompletion.
+
+### Core Exports
+
+| Export              | Purpose                                                                   |
+| ------------------- | ------------------------------------------------------------------------- |
+| `defineConfig()`    | Identity function that provides type inference for `funkai.config.ts`     |
+| `configSchema`      | Root Zod schema covering all funkai configuration sections                |
+| `promptsConfigSchema` | Schema for prompt discovery, output directory, partials, and groups     |
+| `agentsConfigSchema`  | Schema for agent configuration (placeholder for future expansion)       |
+
+### Dependency Direction
+
+`@funkai/cli` depends on `@funkai/config` to load and validate the configuration file at runtime. Other packages do not depend on config directly — they receive resolved configuration values from the CLI.
+
+## CLI Package
+
+The CLI package (`funkai` binary) is the primary developer-facing tool for working with funkai projects. It loads configuration via `@funkai/config`, then exposes commands for setup, codegen, validation, and prompt management.
+
+### Commands
+
+| Command              | Purpose                                            |
+| -------------------- | -------------------------------------------------- |
+| `funkai setup`       | Project-level setup and initialization             |
+| `funkai generate`    | Run codegen across the project                     |
+| `funkai validate`    | Validate project configuration and artifacts       |
+| `funkai prompts create`   | Scaffold a new prompt file                    |
+| `funkai prompts generate` | Generate TypeScript modules from prompt files |
+| `funkai prompts lint`     | Lint prompt files for errors                  |
+| `funkai prompts setup`    | Initialize prompts workspace                  |
+| `funkai agents validate`  | Validate agent configuration                  |
+
+### Dependency Direction
+
+`@funkai/cli` depends on `@funkai/config` (schema and validation) and `@funkai/prompts` (prompt rendering and codegen). It does not depend on `@funkai/agents` or `@funkai/models` at runtime.
+
 ## Design Decisions
 
 1. **Functional by default** -- Factory functions, closures, and plain objects instead of classes
@@ -171,7 +213,7 @@ All packages in this monorepo follow strict conventions to ensure consistency, t
 
 - `strict: true` -- All strict checks enabled
 - `moduleResolution: bundler` -- Optimized for bundlers (tsdown)
-- TypeScript 5.9 with latest type features
+- TypeScript 6.0 with latest type features
 
 ### Test Structure
 
@@ -205,6 +247,7 @@ packages/{name}/
 
 ## References
 
+- [Why funkai](../../docs/why-funkai.md)
 - [Tech Stack](./tech-stack.md)
 - [Coding Style](../standards/typescript/coding-style.md)
 - [Design Patterns](../standards/typescript/design-patterns.md)

diff --git a/contributing/concepts/tech-stack.md b/contributing/concepts/tech-stack.md
@@ -8,7 +8,7 @@ Complete reference of tools and libraries used in the funkai AI SDK framework.
 
 | Tool                                         | Purpose                | Version | Documentation                                                                                |
 | -------------------------------------------- | ---------------------- | ------- | -------------------------------------------------------------------------------------------- |
-| [TypeScript](https://www.typescriptlang.org) | Type system            | ^5.9    | [Handbook](https://www.typescriptlang.org/docs/)                                             |
+| [TypeScript](https://www.typescriptlang.org) | Type system            | ^6.0.3  | [Handbook](https://www.typescriptlang.org/docs/)                                             |
 | [tsdown](https://tsdown.dev)                 | Bundler                | ^0.x    | [llms.txt](https://tsdown.dev/llms.txt) \| [llms-full.txt](https://tsdown.dev/llms-full.txt) |
 | [pnpm](https://pnpm.io)                      | Package manager        | ^9.x    | [Docs](https://pnpm.io/motivation)                                                           |
 | [Turbo](https://turbo.build)                 | Monorepo orchestration | ^2.x    | [Docs](https://turbo.build/repo/docs)                                                        |
@@ -138,7 +138,7 @@ LiquidJS provides a safe, sandboxed template engine for prompt authoring:
 | ----------- | --------------- | ----------------------------------------------------- |
 | Node.js     | 24.x            | Latest LTS, native ESM, modern JavaScript features    |
 | pnpm        | 9.x             | Workspace protocol, catalog protocol, better lockfile |
-| TypeScript  | 5.9.x           | Latest type features, improved inference              |
+| TypeScript  | 6.0.x           | Latest type features, improved inference              |
 
 ## Excluded Technologies
 
@@ -149,7 +149,7 @@ These technologies are **not used** in this codebase:
 | Classes    | Violates functional programming persona. Use factory functions. |
 | Lodash     | Imperative, mutable. Use es-toolkit.                            |
 | Ramda      | Overly complex for this use case. Use es-toolkit.               |
-| ESLint     | Use oxfmt for formatting.                                       |
+| ESLint     | Not used as a standalone runner. oxlint natively supports ESLint plugin configs (`eslint-plugin-functional`, `eslint-plugin-jsdoc`, `eslint-plugin-security`), so the plugin ecosystem is leveraged without running ESLint itself. |
 | Prettier   | Use oxfmt (faster, Rust-based).                                 |
 | Jest       | Too slow, poor ESM support. Use Vitest.                         |
 | Babel      | Not needed with modern TypeScript + tsdown.                     |

diff --git a/contributing/guides/getting-started.md b/contributing/guides/getting-started.md
@@ -46,7 +46,7 @@ Read the project docs in this order:
 2. [`contributing/concepts/architecture.md`](../concepts/architecture.md) -- package ecosystem, design principles, data flow
 3. [`contributing/concepts/tech-stack.md`](../concepts/tech-stack.md) -- tools, libraries, and design rationale
 4. Relevant standards in `contributing/standards/` as needed
-5. Package docs: [`@funkai/agents`](/concepts/agents) and [`@funkai/prompts`](/concepts/prompts)
+5. Package docs: [`@funkai/agents`](../../docs/concepts/agents.md) and [`@funkai/prompts`](../../docs/concepts/prompts.md)
 
 ### 6. Set up Claude Code (optional)
 

diff --git a/contributing/standards/git-commits.md b/contributing/standards/git-commits.md
@@ -63,7 +63,7 @@ Scopes identify what part of the codebase changed. Use directory-style paths for
 
 ```bash
 git commit -m "feat(packages/agents): add parallel step execution"
-git commit -m "chore(deps): update typescript to 5.9.3"
+git commit -m "chore(deps): update typescript to 6.0.3"
 git commit -m "chore(ci): add release workflow"
 git commit -m "chore(tooling): update turbo.json pipeline"
 ```

diff --git a/examples/basic-agent/README.md b/examples/basic-agent/README.md
@@ -17,12 +17,14 @@ A minimal example showing how to create an agent with tools and use `evolve()` t
 
 ## Prerequisites
 
-Set your OpenAI API key (or configure OpenRouter):
+Set your OpenAI API key:
 
 ```bash
 export OPENAI_API_KEY="sk-..."
 ```
 
+Or create a `.env` file in the example directory with `OPENAI_API_KEY=sk-...`.
+
 ## Usage
 
 ```bash

diff --git a/examples/flow-agent/README.md b/examples/flow-agent/README.md
@@ -17,12 +17,14 @@ A multi-step flow agent that orchestrates sub-agents sequentially — summarize
 
 ## Prerequisites
 
-Set your OpenAI API key (or configure OpenRouter):
+Set your OpenAI API key:
 
 ```bash
 export OPENAI_API_KEY="sk-..."
 ```
 
+Or create a `.env` file in the example directory with `OPENAI_API_KEY=sk-...`.
+
 ## Usage
 
 ```bash

diff --git a/examples/prompts-basic/README.md b/examples/prompts-basic/README.md
@@ -18,12 +18,14 @@ A minimal example showing how to use `.prompt` files with build-time codegen to
 
 ## Prerequisites
 
-Set your OpenAI API key (or configure OpenRouter):
+Set your OpenAI API key:
 
 ```bash
 export OPENAI_API_KEY="sk-..."
 ```
 
+Or create a `.env` file in the example directory with `OPENAI_API_KEY=sk-...`.
+
 ## Usage
 
 ```bash

diff --git a/examples/prompts-subagents/README.md b/examples/prompts-subagents/README.md
@@ -19,12 +19,14 @@ A multi-agent content pipeline where each sub-agent's system prompt is defined a
 
 ## Prerequisites
 
-Set your OpenAI API key (or configure OpenRouter):
+Set your OpenAI API key:
 
 ```bash
 export OPENAI_API_KEY="sk-..."
 ```
 
+Or create a `.env` file in the example directory with `OPENAI_API_KEY=sk-...`.
+
 ## Usage
 
 ```bash

diff --git a/examples/realworld-cli/README.md b/examples/realworld-cli/README.md
@@ -22,13 +22,16 @@ A realistic CLI application that uses an AI agent pipeline to scan a codebase fo
 
 ## Prerequisites
 
-Set your OpenAI API key (or configure OpenRouter):
+Set your OpenAI API key:
 
 ```bash
-# From the monorepo root
-pnpm install
+export OPENAI_API_KEY="sk-..."
+```
+
+Or copy the `.env.example` file and fill in your key:
 
-# Copy and fill in your API key
+```bash
+# From the monorepo root
 cp examples/realworld-cli/.env.example examples/realworld-cli/.env
 ```
 
@@ -73,7 +76,7 @@ CLI (@clack/prompts) ───────────────────
                      ←── SSE: done ──────────┘
 ```
 
-- **API server** (`api/`) — Hosts the agent pipeline (scanner + analyzer) and makes LLM calls via OpenRouter. When an agent decides to call a tool (`ls`, `grep`, `read-file`), the API sends a `tool-execute` SSE event to the CLI and waits for the result.
+- **API server** (`api/`) — Hosts the agent pipeline (scanner + analyzer) and makes LLM calls via OpenAI. When an agent decides to call a tool (`ls`, `grep`, `read-file`), the API sends a `tool-execute` SSE event to the CLI and waits for the result.
 - **CLI client** (`cli/`) — Owns the filesystem. Receives `tool-execute` events, runs the tool locally against the user's codebase, and POSTs the result back to `/tool-result`. Streams all agent activity to the terminal using `@clack/prompts`. Writes a markdown report to `./reports/` when complete.
 - **Fixtures** (`fixtures/`) — Sample source code and intentionally bad tests so the demo works out of the box.
 - **Shared** (`shared/`) — SSE event types and tool result payload shared between API and CLI.

diff --git a/examples/streaming/README.md b/examples/streaming/README.md
@@ -18,12 +18,14 @@ Demonstrates streaming for both regular agents and flow agents using the typed `
 
 ## Prerequisites
 
-Set your OpenAI API key (or configure OpenRouter):
+Set your OpenAI API key:
 
 ```bash
 export OPENAI_API_KEY="sk-..."
 ```
 
+Or create a `.env` file in the example directory with `OPENAI_API_KEY=sk-...`.
+
 ## Usage
 
 ```bash

diff --git a/packages/agents/docs/advanced/streaming.md b/packages/agents/docs/advanced/streaming.md
@@ -42,7 +42,7 @@ sequenceDiagram
     end
 
     C->>C: await result.output
-    C->>C: await result.messages
+    C->>C: await result.response
 ```
 
 ## Key Concepts
@@ -53,21 +53,23 @@ Returned by `.stream()` inside a `Result` wrapper. The `fullStream` is available
 
 ```ts
 interface StreamResult<TOutput = string> {
-  output: Promise<TOutput>;
-  messages: Promise<Message[]>;
-  usage: Promise<TokenUsage>;
-  finishReason: Promise<string>;
-  fullStream: AsyncIterableStream<StreamPart>;
+  output: PromiseLike<TOutput>;          // resolves after stream completes
+  usage: Promise<LanguageModelUsage>;    // resolves after stream completes
+  finishReason: Promise<string>;         // resolves after stream completes
+  textStream: AsyncIterableStream<string>; // live text deltas
+  fullStream: AsyncIterableStream<StreamPart>; // all stream parts (text, tool calls, etc.)
+  response: Promise<Response>;           // resolves after stream completes (includes messages)
 }
 ```
 
 | Field          | Type                              | When Available         |
 | -------------- | --------------------------------- | ---------------------- |
+| `textStream`   | `AsyncIterableStream<string>`     | Immediately            |
 | `fullStream`   | `AsyncIterableStream<StreamPart>` | Immediately            |
-| `output`       | `Promise<TOutput>`                | After stream completes |
-| `messages`     | `Promise<Message[]>`              | After stream completes |
-| `usage`        | `Promise<TokenUsage>`             | After stream completes |
+| `output`       | `PromiseLike<TOutput>`            | After stream completes |
+| `usage`        | `Promise<LanguageModelUsage>`     | After stream completes |
 | `finishReason` | `Promise<string>`                 | After stream completes |
+| `response`     | `Promise<Response>`               | After stream completes |
 
 ### StreamPart Events
 

diff --git a/packages/agents/docs/core/agent.md b/packages/agents/docs/core/agent.md
@@ -54,16 +54,13 @@ The `output` field accepts an AI SDK `Output` strategy or a raw Zod schema:
 ```ts
 interface Agent<TInput, TOutput, TTools, TSubAgents> {
   generate(
-    input: TInput,
-    config?: AgentOverrides<TTools, TSubAgents>,
+    params: GenerateParams<TInput, TTools, TSubAgents, TOutput>,
   ): Promise<Result<GenerateResult<TOutput>>>;
   stream(
-    input: TInput,
-    config?: AgentOverrides<TTools, TSubAgents>,
+    params: GenerateParams<TInput, TTools, TSubAgents, TOutput>,
   ): Promise<Result<StreamResult<TOutput>>>;
   fn(): (
-    input: TInput,
-    config?: AgentOverrides<TTools, TSubAgents>,
+    params: GenerateParams<TInput, TTools, TSubAgents, TOutput>,
   ) => Promise<Result<GenerateResult<TOutput>>>;
 }
 ```
@@ -75,29 +72,29 @@ Runs the agent to completion. Returns `Result<GenerateResult<TOutput>>`.
 ```ts
 interface GenerateResult<TOutput = string> {
   output: TOutput; // the generation output
-  messages: Message[]; // full message history including tool calls
-  usage: TokenUsage; // aggregated token usage across all tool-loop steps
+  usage: LanguageModelUsage; // aggregated token usage across all tool-loop steps
   finishReason: string; // why the model stopped ('stop', 'length', 'tool-calls', etc.)
 }
 ```
 
-On success, `result.ok` is `true` and `output`/`messages` are flat on the result object. On failure, `result.ok` is `false` and `result.error` contains a `ResultError`.
+On success, `result.ok` is `true` and `output` is flat on the result object. Access messages via `result.response.messages`. On failure, `result.ok` is `false` and `result.error` contains a `ResultError`.
 
 ### stream()
 
 Runs the agent with streaming output. Returns `Result<StreamResult<TOutput>>`.
 
 ```ts
 interface StreamResult<TOutput = string> {
-  output: Promise<TOutput>; // resolves after stream completes
-  messages: Promise<Message[]>; // resolves after stream completes
-  usage: Promise<TokenUsage>; // resolves after stream completes
+  output: PromiseLike<TOutput>; // resolves after stream completes
+  usage: Promise<LanguageModelUsage>; // resolves after stream completes
   finishReason: Promise<string>; // resolves after stream completes
-  stream: ReadableStream<string>; // live text deltas
+  textStream: AsyncIterableStream<string>; // live text deltas
+  fullStream: AsyncIterableStream<StreamPart>; // all stream parts (text, tool calls, etc.)
+  response: Promise<Response>; // resolves after stream completes (includes messages)
 }
 ```
 
-The `stream` is available immediately. Consume it for incremental output. Await `output` and `messages` after the stream ends.
+The `fullStream` and `textStream` are available immediately. Consume them for incremental output. Await `output`, `usage`, and `response` after the stream ends.
 
 ### fn()
 

diff --git a/packages/agents/docs/core/context.md b/packages/agents/docs/core/context.md
@@ -80,7 +80,7 @@ interface Context extends ExecutionContext {
 | `trace`    | `TraceEntry[]` | Execution trace -- every tracked `$` operation recorded |
 | `messages` | `Message[]`    | Synthetic tool-call messages in execution order         |
 
-The `trace` array builds the execution graph. The `messages` array collects synthetic tool-call/tool-result message pairs that the framework uses to populate `FlowAgentGenerateResult.messages`.
+The `trace` array builds the execution graph. The `messages` array collects synthetic tool-call/tool-result message pairs that the framework uses to populate `FlowAgentGenerateResult.response.messages`.
 
 ### Signal Propagation