@falai/agent 3.4.5 → 4.0.0-alpha.2

package/dist/utils/template.js

@@ -1,372 +1,45 @@
-import { MessageRole, EventKind } from "../types/history.js";
 /**
- * Renders a template, which can be a string or a function, using the provided context.
- * This function is asynchronous to support template functions that perform async operations.
+ * `{{path}}` substitution for prompts, `say` texts and action parameters.
  *
- * @param template - The template to render (string or function).
- * @param params - The context object to pass to the template function.
- * @returns A promise that resolves to the rendered string.
- *
- * @example
- * ```typescript
- * // With a string template
- * const result1 = await render("Hello {{name}}", { context: { name: "Alice" } });
- * // Result: "Hello Alice"
- *
- * // With a function template
- * const fnTemplate = ({ context }) => `Hello ${context.name}`;
- * const result2 = await render(fnTemplate, { context: { name: "Bob" } });
- * // Result: "Hello Bob"
- * ```
+ * The scope has three roots: `data` (collected fields), `context` (the host's
+ * per-turn context) and `input` (the run's trigger payload). A path that
+ * resolves to nothing keeps its placeholder, so a typo stays visible instead
+ * of vanishing into an empty string.
  */
-export async function render(template, params) {
-    if (typeof template === "function") {
-        // Execute the function and await the result if it's a promise
-        const result = await Promise.resolve(template(params));
-        return result;
-    }
-    if (typeof template === "string") {
-        // Fallback to the old renderTemplate logic for string-based templates
-        return renderTemplate(template, params.context);
-    }
-    // Return empty string if template is undefined or not a supported type
-    return "";
+const PLACEHOLDER = /\{\{\s*([^}\s]+)\s*\}\}/g;
+export function render(template, scope) {
+    return template.replace(PLACEHOLDER, (match, path) => {
+        const value = lookup(scope, path.split("."));
+        return value === undefined || value === null ? match : stringify(value);
+    });
 }
-/**
- * Renders an array of templates.
- *
- * @param templates - An array of templates to render.
- * @param params - The context object.
- * @returns A promise that resolves to an array of rendered strings.
- */
-export async function renderMany(templates, params) {
-    if (!templates) {
-        return [];
+/** `render` over every string inside a value, recursively. Non-strings pass through. */
+export function renderDeep(value, scope) {
+    if (typeof value === "string")
+        return render(value, scope);
+    if (Array.isArray(value))
+        return value.map((item) => renderDeep(item, scope));
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, renderDeep(v, scope)]));
     }
-    return Promise.all(templates.map((t) => render(t, params)));
+    return value;
 }
-/**
- * Renders template variables in a string using the provided context.
- * Supports {{variable}} and {{object.property}} syntax for property access.
- *
- * @param template - The template string containing {{variable}} placeholders
- * @param context - The context object to pull values from
- * @returns The rendered string with variables replaced
- *
- * @example
- * ```typescript
- * const template = "Hello {{user.name}}, welcome to {{company.name}}!";
- * const context = {
- *   user: { name: "Alice", age: 30 },
- *   company: { name: "Acme Corp", location: "NYC" }
- * };
- * const result = renderTemplate(template, context);
- * // Result: "Hello Alice, welcome to Acme Corp!"
- *
- * // Array handling
- * const template2 = "Items: {{items}}";
- * const context2 = { items: ["apple", "banana", "cherry"] };
- * const result2 = renderTemplate(template2, context2);
- * // Result: "Items: apple, banana, cherry"
- * ```
- */
-export function renderTemplate(template, context) {
-    if (!template || !context) {
-        return template;
-    }
-    return template.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
-        const value = getValueByPath(context, path.trim());
-        if (value === undefined || value === null) {
-            return match; // Keep the original placeholder if value not found
-        }
-        return valueToString(value);
-    });
-}
-/**
- * Gets a value from an object using dot notation path.
- * Supports nested property access like "user.name" or "user.address.city".
- *
- * @param obj - The object to search in
- * @param path - The dot-separated path to the property
- * @returns The value at the path, or undefined if not found
- */
-function getValueByPath(obj, path) {
-    const keys = path.split(".");
-    let current = obj;
+function lookup(root, keys) {
+    let current = root;
     for (const key of keys) {
-        if (current === null ||
-            current === undefined ||
-            typeof current !== "object") {
+        if (current === null || typeof current !== "object")
             return undefined;
-        }
         current = current[key];
     }
     return current;
 }
-/**
- * Converts a value to its string representation for template rendering.
- * Handles different types appropriately.
- *
- * @param value - The value to convert to string
- * @returns String representation of the value
- */
-function valueToString(value) {
-    if (value === null || value === undefined) {
-        return "";
-    }
-    if (typeof value === "string") {
+function stringify(value) {
+    if (typeof value === "string")
         return value;
-    }
-    if (typeof value === "number" || typeof value === "boolean") {
+    if (typeof value === "number" || typeof value === "boolean")
         return String(value);
-    }
-    if (Array.isArray(value)) {
-        // For arrays, join with commas by default
-        // Users can override this by using JSON.stringify in their templates if needed
-        return value.map((item) => valueToString(item)).join(", ");
-    }
-    if (typeof value === "object") {
-        // For objects, convert to JSON string
-        // This provides a readable representation while being safe
-        try {
-            return JSON.stringify(value);
-        }
-        catch {
-            return "[object Object]";
-        }
-    }
-    // Fallback for any other type
+    if (Array.isArray(value))
+        return value.map(stringify).join(", ");
     return JSON.stringify(value);
 }
-/**
- * Renders template variables in an object recursively.
- * Handles nested objects and arrays.
- *
- * @param obj - The object to render templates in
- * @param context - The context object to pull values from
- * @returns The object with all string templates rendered
- */
-export function renderTemplateObject(obj, context) {
-    if (obj === null || obj === undefined) {
-        return obj;
-    }
-    if (typeof obj === "string") {
-        return renderTemplate(obj, context);
-    }
-    if (Array.isArray(obj)) {
-        return obj.map((item) => renderTemplateObject(item, context));
-    }
-    if (typeof obj === "object") {
-        const result = {};
-        for (const [key, value] of Object.entries(obj)) {
-            result[key] = renderTemplateObject(value, context);
-        }
-        return result;
-    }
-    return obj;
-}
-/**
- * Creates helper functions for working with history and context in templates.
- * These helpers make it easier to access message content and perform common operations.
- *
- * @param history - The event history array
- * @returns Object containing helper functions
- */
-export function createTemplateHelpers(history) {
-    const helpers = {
-        /**
-         * Get the last message from history, optionally filtered by role.
-         * @param role - Optional role to filter by (user, assistant, etc.)
-         * @returns The message content or undefined if not found
-         */
-        getLastMessage(role) {
-            if (!history || history.length === 0)
-                return undefined;
-            // Search backwards through history for the most recent message
-            for (let i = history.length - 1; i >= 0; i--) {
-                const event = history[i];
-                if (event.kind === EventKind.MESSAGE) {
-                    // If no role specified, return the first message found
-                    if (!role || event.source === role) {
-                        const messageData = event.data;
-                        return messageData.message;
-                    }
-                }
-            }
-            return undefined;
-        },
-        /**
-         * Get the last user message from history.
-         * @returns The user message content or undefined if not found
-         */
-        getLastUserMessage() {
-            return helpers.getLastMessage(MessageRole.USER);
-        },
-        /**
-         * Get the last assistant message from history.
-         * @returns The assistant message content or undefined if not found
-         */
-        getLastAssistantMessage() {
-            return helpers.getLastMessage(MessageRole.ASSISTANT);
-        },
-        /**
-         * Get all messages from history, optionally filtered by role.
-         * @param role - Optional role to filter by
-         * @returns Array of message contents
-         */
-        getMessages(role) {
-            if (!history || history.length === 0)
-                return [];
-            const messages = [];
-            for (const event of history) {
-                if (event.kind === EventKind.MESSAGE) {
-                    if (!role || event.source === role) {
-                        const messageData = event.data;
-                        messages.push(messageData.message);
-                    }
-                }
-            }
-            return messages;
-        },
-        /**
-         * Check if the last message contains any of the given keywords.
-         * @param keywords - Keywords to search for
-         * @param caseSensitive - Whether to perform case-sensitive search (default: false)
-         * @returns True if any keyword is found
-         */
-        lastMessageContains(keywords, caseSensitive = false) {
-            const lastMessage = helpers.getLastMessage();
-            if (!lastMessage)
-                return false;
-            const searchText = caseSensitive ? lastMessage : lastMessage.toLowerCase();
-            const keywordArray = Array.isArray(keywords) ? keywords : [keywords];
-            return keywordArray.some(keyword => {
-                const searchKeyword = caseSensitive ? keyword : keyword.toLowerCase();
-                return searchText.includes(searchKeyword);
-            });
-        },
-    };
-    return helpers;
-}
-/**
- * Creates a complete TemplateContext with helpers included.
- * This is a convenience function for creating template contexts with all the helper methods.
- *
- * @param params - The base template context parameters
- * @returns Complete TemplateContext with helpers
- */
-export function createTemplateContext(params) {
-    return {
-        ...params,
-        data: params.data || {},
-        helpers: createTemplateHelpers(params.history),
-    };
-}
-/**
- * Formats a JSON structure into readable markdown format.
- * Handles nested objects, arrays, and primitive values.
- *
- * @param data - The JSON data to format
- * @param title - Optional title for the knowledge base section
- * @param maxDepth - Maximum nesting depth (default: 3)
- * @returns Formatted markdown string
- *
- * @example
- * ```typescript
- * const knowledge = {
- *   company: {
- *     name: "Acme Corp",
- *     products: ["Widget A", "Widget B"],
- *     locations: {
- *       headquarters: "NYC",
- *       branches: ["LA", "Chicago"]
- *     }
- *   }
- * };
- *
- * const markdown = formatKnowledgeBase(knowledge, "Company Information");
- * // Output:
- * // ## Company Information
- * //
- * // ### company
- * // - **name**: Acme Corp
- * // - **products**:
- * //   - Widget A
- * //   - Widget B
- * // - **locations**:
- * //   - **headquarters**: NYC
- * //   - **branches**:
- * //     - LA
- * //     - Chicago
- * ```
- */
-export function formatKnowledgeBase(data, title, maxDepth = 3) {
-    const lines = [];
-    if (title) {
-        lines.push(`## ${title}`);
-        lines.push("");
-    }
-    if (!data || typeof data !== "object") {
-        lines.push("*No knowledge base data available*");
-        return lines.join("\n");
-    }
-    formatObject(data, lines, 0, maxDepth);
-    return lines.join("\n");
-}
-/**
- * Recursively formats an object into markdown format
- */
-function formatObject(obj, lines, depth, maxDepth, prefix = "") {
-    const entries = Object.entries(obj);
-    if (entries.length === 0) {
-        lines.push(`${prefix}*Empty*`);
-        return;
-    }
-    for (const [key, value] of entries) {
-        const currentPrefix = prefix ? `${prefix}  ` : "";
-        if (value === null || value === undefined) {
-            lines.push(`${currentPrefix}- **${key}**: *Not specified*`);
-        }
-        else if (typeof value === "string" ||
-            typeof value === "number" ||
-            typeof value === "boolean") {
-            lines.push(`${currentPrefix}- **${key}**: ${value}`);
-        }
-        else if (Array.isArray(value)) {
-            if (value.length === 0) {
-                lines.push(`${currentPrefix}- **${key}**: *Empty list*`);
-            }
-            else {
-                lines.push(`${currentPrefix}- **${key}**:`);
-                for (const item of value) {
-                    if (typeof item === "string" ||
-                        typeof item === "number" ||
-                        typeof item === "boolean") {
-                        lines.push(`${currentPrefix}  - ${item}`);
-                    }
-                    else if (depth < maxDepth &&
-                        typeof item === "object" &&
-                        item !== null) {
-                        lines.push(`${currentPrefix}  - ${JSON.stringify(item)}`);
-                    }
-                    else {
-                        lines.push(`${currentPrefix}  - ${JSON.stringify(item)}`);
-                    }
-                }
-            }
-        }
-        else if (typeof value === "object") {
-            if (depth < maxDepth) {
-                lines.push(`${currentPrefix}- **${key}**:`);
-                formatObject(value, lines, depth + 1, maxDepth, currentPrefix);
-            }
-            else {
-                lines.push(`${currentPrefix}- **${key}**: ${JSON.stringify(value)}`);
-            }
-        }
-        else {
-            lines.push(`${currentPrefix}- **${key}**: ${JSON.stringify(value)}`);
-        }
-    }
-}
 //# sourceMappingURL=template.js.map

package/dist/utils/template.js.map

@@ -1 +1 @@
-{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/utils/template.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,GAAG,0BAA0B,CAAC;AAE/C,MAAM,UAAU,MAAM,CAAC,QAAgB,EAAE,KAAoB;IAC3D,OAAO,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7C,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,UAAU,CAAI,KAAQ,EAAE,KAAoB;IAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,KAAK,EAAE,KAAK,CAAM,CAAC;IAChE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAa,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAM,CAAC;IAC5F,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAC5D,CAAC;IACT,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,MAAM,CAAC,IAAa,EAAE,IAAc;IAC3C,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACtE,OAAO,GAAI,OAAmC,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC"}

package/dist/utils/usage.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Token counts, added up across a turn.
+ *
+ * Providers report per call; a text turn spends two, plus one per tool round,
+ * plus one if the history was compacted. The host bills the conversation, so
+ * the framework hands it one figure beside `llmCalls`.
+ */
+import type { TokenUsage } from "../types/ai.js";
+interface Counted {
+    promptTokens?: number;
+    completionTokens?: number;
+    cachedInputTokens?: number;
+}
+/** What a call's metadata says it cost, or nothing when the provider said nothing. */
+export declare function readUsage(metadata: Counted | undefined): TokenUsage | undefined;
+/** Adds two tallies. Nobody counting is not the same as counting zero. */
+export declare function addUsage(a: TokenUsage | undefined, b: TokenUsage | undefined): TokenUsage | undefined;
+export {};
+//# sourceMappingURL=usage.d.ts.map

package/dist/utils/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/utils/usage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,UAAU,OAAO;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAS/E;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAOrG"}

package/dist/utils/usage.js

@@ -0,0 +1,31 @@
+/**
+ * Token counts, added up across a turn.
+ *
+ * Providers report per call; a text turn spends two, plus one per tool round,
+ * plus one if the history was compacted. The host bills the conversation, so
+ * the framework hands it one figure beside `llmCalls`.
+ */
+/** What a call's metadata says it cost, or nothing when the provider said nothing. */
+export function readUsage(metadata) {
+    if (!metadata)
+        return undefined;
+    const { promptTokens, completionTokens, cachedInputTokens } = metadata;
+    if (promptTokens === undefined && completionTokens === undefined)
+        return undefined;
+    return {
+        promptTokens: promptTokens ?? 0,
+        completionTokens: completionTokens ?? 0,
+        cachedInputTokens: cachedInputTokens ?? 0,
+    };
+}
+/** Adds two tallies. Nobody counting is not the same as counting zero. */
+export function addUsage(a, b) {
+    if (!a || !b)
+        return a ?? b;
+    return {
+        promptTokens: a.promptTokens + b.promptTokens,
+        completionTokens: a.completionTokens + b.completionTokens,
+        cachedInputTokens: a.cachedInputTokens + b.cachedInputTokens,
+    };
+}
+//# sourceMappingURL=usage.js.map

package/dist/utils/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/utils/usage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,sFAAsF;AACtF,MAAM,UAAU,SAAS,CAAC,QAA6B;IACrD,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,GAAG,QAAQ,CAAC;IACvE,IAAI,YAAY,KAAK,SAAS,IAAI,gBAAgB,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACnF,OAAO;QACL,YAAY,EAAE,YAAY,IAAI,CAAC;QAC/B,gBAAgB,EAAE,gBAAgB,IAAI,CAAC;QACvC,iBAAiB,EAAE,iBAAiB,IAAI,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,QAAQ,CAAC,CAAyB,EAAE,CAAyB;IAC3E,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO;QACL,YAAY,EAAE,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY;QAC7C,gBAAgB,EAAE,CAAC,CAAC,gBAAgB,GAAG,CAAC,CAAC,gBAAgB;QACzD,iBAAiB,EAAE,CAAC,CAAC,iBAAiB,GAAG,CAAC,CAAC,iBAAiB;KAC7D,CAAC;AACJ,CAAC"}

package/docs/README.md

@@ -1,40 +1,58 @@
 ---
-title: "Documentation"
-description: "Typed conversations where code stays in charge. Docs for @falai/agent."
+title: "@falai/agent docs"
+description: "The docs for @falai/agent 4.0: a five-page tutorial, one guide per task, the concepts behind a turn, and one reference page per public type."
 type: overview
 order: 0
 ---
 
-# Documentation
+# @falai/agent docs
 
-**Typed conversations where code stays in charge.**
+@falai/agent is a TypeScript library for building chat assistants. The AI understands what the customer wrote; your code decides what happens next. One `agent.turn()` takes a message, a timer, an event from your system or a manual start, and returns the messages to send and the timers to set. Your program, the host, sends and schedules them.
 
-Define flows, steps, and tools in TypeScript; the framework calls the LLM only for the parts that need language — routing, extraction, and generation.
+## Tutorial
 
-## New here?
+Five pages that build one agent from install to production. Start at [Install](./start/01-install.md).
 
-Walk through a five-step tutorial that builds a working agent end to end, from install to streaming responses in production.
+1. [Install](./start/01-install.md)
+2. [Your first agent](./start/02-first-agent.md)
+3. [Collect data](./start/03-collect-data.md)
+4. [Add tools](./start/04-add-tools.md)
+5. [Go to production](./start/05-go-to-production.md)
 
-[Start the tutorial](./start/01-install.md)
+## Guides
 
-## Solving one task?
+One page per task. Each shows the code you write and what the framework does with it. Open [Triggers](./guides/triggers.md) first, since every flow starts with one; the rest stand alone.
 
-Eight task-shaped recipes covering conditions, branching, flow control, instructions, persistence, streaming, errors, and compaction.
+- [Triggers](./guides/triggers.md) — message, mention, silence, event, manual start
+- [Conditions](./guides/conditions.md) — `when` (the model) versus `if` (your code)
+- [Branching](./guides/branching.md) — forks while a step is asking
+- [Flow control](./guides/flow-control.md) — `then`, `else`, `onEnd`, `while`, chaining flows
+- [Actions and events](./guides/actions-and-events.md) — what your code does and what it reports
+- [Instructions](./guides/instructions.md) — rules the model follows at agent, flow or step level
+- [Error handling](./guides/error-handling.md) — what throws, what stays put and retries on a timer, what you replay
+- [Persistence](./guides/persistence.md) — `Store`, the version check on save, the seven built-in stores
+- [Streaming](./guides/streaming.md) — `turnStream` and its chunks
+- [Compaction](./guides/compaction.md) — trimming long histories once per turn
+- [Flows from JSON](./guides/flows-from-json.md) — `FlowSpec`, `fromSpec`, `validateFlow`
+- [Testing](./guides/testing.md) — a fake clock, an in-memory store, a scripted provider
 
-[Browse the guides](./guides/conditions.md)
+## Concepts
 
-## Want the why?
+Four pages explain the design. Start with [Architecture](./concepts/architecture.md).
 
-Three concept pages that build the mental model: the seven primitives, the per-turn pipeline, and how directives steer a conversation.
+- [Architecture](./concepts/architecture.md) — agent, flow, trigger, step, field, run, turn
+- [Pipeline](./concepts/pipeline.md) — the eight phases of one turn and what each costs
+- [Runs and waits](./concepts/runs-and-waits.md) — who is speaking (the floor), timers (wakes), keys and claims
+- [Collection](./concepts/collection.md) — how fields get filled
 
-[Read about the architecture](./concepts/architecture.md)
+## Reference
 
-## Looking up an API?
+One page per public type, with every field, its type and its default, taken from the code. Start at [Agent](./reference/agent.md), which covers `falai()`, the agent options, `turn()` and its result.
 
-One page per public type. Signatures, field tables, errors, and short runnable examples for `createAgent`, `Flow`, `Step`, `Tool`, `Instruction`, `Directive`, signals, providers, adapters, and more.
-
-[Open the reference](./reference/create-agent.md)
+- [Agent](./reference/agent.md) · [Flow](./reference/flow.md) · [Step](./reference/step.md) · [Trigger](./reference/trigger.md) · [Fields](./reference/fields.md) · [Branches](./reference/branches.md)
+- [Actions, events, conditions](./reference/actions-events-conditions.md) · [Instruction](./reference/instruction.md) · [Tool](./reference/tool.md)
+- [Session](./reference/session.md) · [Stores](./reference/stores.md) · [Flow spec](./reference/flow-spec.md) · [Outcomes](./reference/outcomes.md) · [Errors](./reference/errors.md) · [Providers](./reference/providers.md)
 
 ---
 
-Upgrading? See the [v2.3 → v2.4 migration guide](./migration/v2-3-to-v2-4.md) or, from `1.x`, the [v1 → v2 migration guide](./migration/v1-to-v2.md).
+Upgrading from 3.x? v4 is a clean break: nothing old compiles. The [v3 → v4 migration guide](./migration/v3-to-v4.md) has the before and after for every change.