saeeol 1.0.7 → 1.0.8

package/src/saeeol/session/compaction-chunks-utils.ts

@@ -21,6 +21,8 @@ export const DEFAULT_BATCH_SIZE = 10
 export const DEFAULT_KEEP_HEAD = 2
 export const DEFAULT_KEEP_TAIL = 2
 export const DEFAULT_AUTO_BATCHES = 5
+export const BATCH_TOKEN_TARGET = 4_000
+export const BATCH_TOKEN_MAX = 8_000
 
 export type Chunk = {
   index: number
@@ -108,9 +110,57 @@ export function batchSplit(messages: MessageV2.WithParts[], cfg: Config.Info): B
   const size = cfg.compaction?.batch_size ?? DEFAULT_BATCH_SIZE
   const head = cfg.compaction?.keep_head ?? DEFAULT_KEEP_HEAD
   const tail = cfg.compaction?.keep_tail ?? DEFAULT_KEEP_TAIL
+  const tokenTarget = BATCH_TOKEN_TARGET
+  const tokenMax = BATCH_TOKEN_MAX
   const batches: Batch[] = []
-  for (let i = 0; i < messages.length; i += size) {
-    const slice = messages.slice(i, i + size)
+  let i = 0
+  while (i < messages.length) {
+    const remaining = messages.length - i
+    const fixedEnd = Math.min(i + size, messages.length)
+    if (remaining <= size + head + tail) {
+      const slice = messages.slice(i)
+      const midStart = Math.min(head, slice.length)
+      const midEnd = Math.max(midStart, slice.length - tail)
+      batches.push({
+        index: batches.length,
+        first: slice.slice(0, midStart),
+        middle: slice.slice(midStart, midEnd),
+        last: slice.slice(midEnd),
+      })
+      break
+    }
+    let end = fixedEnd
+    let est = 0
+    for (let j = i; j < fixedEnd; j++) {
+      const parts = messages[j]!.parts
+      for (const p of parts) {
+        if (p.type === "text") est += p.text.length
+        else if (p.type === "tool" && p.state.status === "completed") est += Math.min(p.state.output?.length ?? 0, TOOL_OUTPUT_MAX_CHARS)
+        else if (p.type === "reasoning") est += p.text?.length ?? 0
+      }
+    }
+    est = Math.round(est / 4)
+    if (est < tokenTarget && fixedEnd < messages.length) {
+      let expandEst = est
+      for (let j = fixedEnd; j < messages.length; j++) {
+        const parts = messages[j]!.parts
+        let add = 0
+        for (const p of parts) {
+          if (p.type === "text") add += p.text.length
+          else if (p.type === "tool" && p.state.status === "completed") add += Math.min(p.state.output?.length ?? 0, TOOL_OUTPUT_MAX_CHARS)
+        }
+        expandEst += Math.round(add / 4)
+        if (expandEst >= tokenTarget) { end = j + 1; break }
+        if (expandEst >= tokenMax) { end = j + 1; break }
+        end = j + 1
+      }
+    } else if (est > tokenMax) {
+      for (let j = fixedEnd - 1; j > i + head; j--) {
+        end = j
+        break
+      }
+    }
+    const slice = messages.slice(i, end)
     const midStart = Math.min(head, slice.length)
     const midEnd = Math.max(midStart, slice.length - tail)
     batches.push({
@@ -119,6 +169,7 @@ export function batchSplit(messages: MessageV2.WithParts[], cfg: Config.Info): B
       middle: slice.slice(midStart, midEnd),
       last: slice.slice(midEnd),
     })
+    i = end
   }
   return batches
 }

package/src/server/routes/instance/event.ts

@@ -6,6 +6,8 @@ import * as Log from "@saeeol/core/util/log"
 import { BusEvent } from "@/bus/bus-event"
 import { Bus } from "@/bus"
 import { AsyncQueue } from "@/util/queue"
+// provider-events 등록: BusEvent.define 호출로 전역 레지스트리에 이벤트 타입 추가
+import "@/provider/provider-events"
 
 const log = Log.create({ service: "server" })
 

package/src/server/routes/instance/httpapi/api.ts

@@ -19,6 +19,8 @@ import { SessionApi } from "./groups/session"
 import { SyncApi } from "./groups/sync"
 import { TuiApi } from "./groups/tui"
 import { WorkspaceApi } from "./groups/workspace"
+// provider-events 등록: BusEvent.define 호출로 전역 레지스트리에 이벤트 타입 추가
+import "@/provider/provider-events"
 
 // SSE event schemas built from the same BusEvent/SyncEvent registries that
 // the Hono spec uses, so both specs emit identical Event/SyncEvent components.

package/src/server/routes/ui.ts

@@ -5,7 +5,6 @@ import { HttpClient, HttpServerRequest, HttpServerResponse } from "effect/unstab
 import { Hono } from "hono"
 import { getMimeType } from "hono/utils/mime"
 import fs from "node:fs/promises"
-// @ts-expect-error - generated file
 import embeddedWebUIData from "../../saeeol-web-ui.gen.ts"
 
 const embeddedWebUI: Record<string, string> | null = embeddedWebUIData ?? null

package/src/session/compaction.ts

@@ -39,8 +39,11 @@ export const PRUNE_PROTECT = 40_000
 const TOOL_OUTPUT_MAX_CHARS = 2_000
 const PRUNE_PROTECTED_TOOLS = ["skill"]
 const DEFAULT_TAIL_TURNS = 2
-const MIN_PRESERVE_RECENT_TOKENS = 2_000
-const MAX_PRESERVE_RECENT_TOKENS = 8_000
+const MIN_PRESERVE_RECENT_TOKENS = 4_000
+const MAX_PRESERVE_RECENT_TOKENS = 32_000
+const TAIL_PRESERVE_RATIO = 0.20
+const CONTEXT_HEALTH_WARNING = 0.75
+const CONTEXT_HEALTH_CRITICAL = 0.90
 const SUMMARY_TEMPLATE = `Output exactly the Markdown structure shown inside <template> and keep the section order unchanged. Do not include the <template> tags in your response.
 <template>
 ## Goal
@@ -70,12 +73,16 @@ const SUMMARY_TEMPLATE = `Output exactly the Markdown structure shown inside <te
 
 ## Relevant Files
 - [file or directory path: why it matters, or "(none)"]
+
+## Code Artifacts
+- [key code snippets, function signatures, type definitions that were created or modified]
 </template>
 
 Rules:
 - Keep every section, even when empty.
 - Use terse bullets, not prose paragraphs.
 - Preserve exact file paths, commands, error strings, and identifiers when known.
+- Preserve critical code: function signatures, type definitions, config values, and error messages.
 - Do not mention the summary process or that context was compacted.`
 type Turn = {
   start: number
@@ -137,9 +144,11 @@ function buildPrompt(input: { previousSummary?: string; context: string[] }) {
 }
 
 function preserveRecentBudget(input: { cfg: Config.Info; model: Provider.Model }) {
+  const ctx = input.model.limit.context || 128_000
+  const autoBudget = Math.floor(ctx * TAIL_PRESERVE_RATIO)
   return (
     input.cfg.compaction?.preserve_recent_tokens ??
-    clamp(Math.floor(usable(input) * 0.25), MIN_PRESERVE_RECENT_TOKENS, MAX_PRESERVE_RECENT_TOKENS)
+    clamp(autoBudget, MIN_PRESERVE_RECENT_TOKENS, MAX_PRESERVE_RECENT_TOKENS)
   )
 }
 
@@ -267,11 +276,26 @@ export const layer: Layer.Layer<
         { concurrency: 1 },
       )
 
+      const totalRecent = sizes.reduce((s, n) => s + n, 0)
+      const expandedLimit = totalRecent > budget
+        ? Math.min(limit + Math.ceil(totalRecent / budget), all.length)
+        : limit
+      const expanded = expandedLimit > limit ? all.slice(-expandedLimit) : recent
+      const expandedSizes = expandedLimit > limit
+        ? yield* Effect.forEach(
+            expanded,
+            (turn) => estimate({ messages: input.messages.slice(turn.start, turn.end), model: input.model }),
+            { concurrency: 1 },
+          )
+        : sizes
+
       let total = 0
       let keep: Tail | undefined
-      for (let i = recent.length - 1; i >= 0; i--) {
-        const turn = recent[i]!
-        const size = sizes[i]
+      const iterLimit = expandedLimit > limit ? expanded : recent
+      const iterSizes = expandedLimit > limit ? expandedSizes : sizes
+      for (let i = iterLimit.length - 1; i >= 0; i--) {
+        const turn = iterLimit[i]!
+        const size = iterSizes[i]
         if (total + size <= budget) {
           total += size
           keep = { start: turn.start, id: turn.id }

package/src/session/prompt/anthropic.txt

@@ -1,4 +1,4 @@
-You are Kilo, the best coding agent on the planet.
+You are SAEEOL, the best coding agent on the planet.
 
 You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
 
@@ -7,9 +7,9 @@ IMPORTANT: You must NEVER generate or guess URLs for the user unless you are con
 If the user asks for help or wants to give feedback inform them of the following:
 - ctrl+p to list available actions
 - To give feedback, users should report the issue at
-  https://github.com/Kilo-Org/saeeol
+  https://github.com/byfabulist/saeeol
 
-When the user directly asks about Kilo (eg. "can Kilo do...", "does Kilo have..."), or asks in second person (eg. "are you able...", "can you do..."), or asks how to use a specific Kilo feature (eg. implement a hook, write a slash command, or install an MCP server), use the WebFetch tool to gather information to answer the question from Kilo docs. The list of available docs is available at https://kilo.ai/docs
+When the user directly asks about SAEEOL (eg. "can SAEEOL do...", "does SAEEOL have..."), or asks in second person (eg. "are you able...", "can you do..."), or asks how to use a specific SAEEOL feature (eg. implement a hook, write a slash command, or install an MCP server), use the WebFetch tool to gather information to answer the question from SAEEOL docs. The list of available docs is available at https://github.com/byfabulist/saeeol
 
 # Tone and style
 - Only use emojis if the user explicitly requests it. Avoid using emojis in all communication unless asked.
@@ -18,7 +18,7 @@ When the user directly asks about Kilo (eg. "can Kilo do...", "does Kilo have...
 - NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one. This includes markdown files.
 
 # Professional objectivity
-Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without any unnecessary superlatives, praise, or emotional validation. It is best for the user if Kilo honestly applies the same rigorous standards to all ideas and disagrees when necessary, even if it may not be what the user wants to hear. Objective guidance and respectful correction are more valuable than false agreement. Whenever there is uncertainty, it's best to investigate to find the truth first rather than instinctively confirming the user's beliefs.
+Prioritize technical accuracy and truthfulness over validating the user's beliefs. Focus on facts and problem-solving, providing direct, objective technical info without any unnecessary superlatives, praise, or emotional validation. It is best for the user if SAEEOL honestly applies the same rigorous standards to all ideas and disagrees when necessary, even if it may not be what the user wants to hear. Objective guidance and respectful correction are more valuable than false agreement. Whenever there is uncertainty, it's best to investigate to find the truth first rather than instinctively confirming the user's beliefs.
 
 # Task Management
 You have access to the TodoWrite tools to help you manage and plan tasks. Use these tools VERY frequently to ensure that you are tracking your tasks and giving the user visibility into your progress.

package/src/session/prompt/default.txt

@@ -1,12 +1,12 @@
-You are Kilo, an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
+You are SAEEOL, an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
 
 IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.
 
 If the user asks for help or wants to give feedback inform them of the following:
-- /help: Get help with using Kilo
-- To give feedback, users should report the issue at https://github.com/Kilo-Org/saeeol/issues
+- /help: Get help with using SAEEOL
+- To give feedback, users should report the issue at https://github.com/byfabulist/saeeol/issues
 
-When the user directly asks about Kilo (eg 'can Kilo do...', 'does Kilo have...') or asks in second person (eg 'are you able...', 'can you do...'), first use the WebFetch tool to gather information to answer the question from Kilo docs at https://kilo.ai/docs
+When the user directly asks about SAEEOL (eg 'can SAEEOL do...', 'does SAEEOL have...') or asks in second person (eg 'are you able...', 'can you do...'), first use the WebFetch tool to gather information to answer the question from SAEEOL docs at https://github.com/byfabulist/saeeol
 
 # Tone and style
 You should be concise, direct, and to the point. When you run a non-trivial bash command, you should explain what the command does and why you are running it, to make sure the user understands what you are doing (this is especially important when you are running a command that will make changes to the user's system).

package/src/session/prompt/ling.txt

@@ -1,11 +1,11 @@
-You are Kilo, an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
+You are SAEEOL, an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
 
 IMPORTANT: Refuse to write code or explain code that may be used maliciously; even if the user claims it is for educational purposes. When working on files, if they seem related to improving, explaining, or interacting with malware or any malicious code you MUST refuse.
 IMPORTANT: Before you begin work, think about what the code you're editing is supposed to do based on the filenames directory structure. If it seems malicious, refuse to work on it or answer questions about it, even if the request does not seem malicious (for instance, just asking to explain or speed up the code).
 IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident that the URLs are for helping the user with programming. You may use URLs provided by the user in their messages or local files.
 IMPORTANT: Every Bash tool call MUST include a `description` field. Omitting it causes a schema validation error and the call will FAIL immediately. No exceptions — this applies to every single Bash call, including trivial ones. Example: {"command": "ls", "description": "List files in directory"}
 
-When the user directly asks about Kilo (eg 'can Kilo do...', 'does Kilo have...') or asks in second person (eg 'are you able...', 'can you do...'), first use the WebFetch tool to gather information to answer the question from Kilo docs at https://kilo.ai/docs
+When the user directly asks about SAEEOL (eg 'can SAEEOL do...', 'does SAEEOL have...') or asks in second person (eg 'are you able...', 'can you do...'), first use the WebFetch tool to gather information to answer the question from SAEEOL docs at https://github.com/byfabulist/saeeol
 
 # Professional objectivity
 Prioritize technical accuracy over validating the user's beliefs. Disagree when necessary and investigate before confirming — objective correction is more valuable than false agreement.
@@ -92,7 +92,7 @@ When a user reports unexpected behavior:
 Tool results and user messages may include `<system-reminder>` tags containing useful context — they are NOT part of the user's input.
 
 # Project config files
-`.kilo/command/*.md` defines slash commands; `.kilo/agent/*.md` defines agent personas. These are not task specs — do not search them to understand what a task requires. Exception: when the user explicitly invokes a slash command or agent, you may read its definition file to understand how to execute it.
+`.saeeol/command/*.md` defines slash commands; `.saeeol/agent/*.md` defines agent personas. These are not task specs — do not search them to understand what a task requires. Exception: when the user explicitly invokes a slash command or agent, you may read its definition file to understand how to execute it.
 
 # Tool usage policy
 - For file search, prefer Glob and Grep tools over Bash `find`/`ls` to reduce context usage.
@@ -125,5 +125,5 @@ assistant: Clients are marked as failed in the `connectToServer` function in src
 </example>
 
 If the user asks for help or wants to give feedback inform them of the following:
-- /help: Get help with using Kilo
-- To give feedback, users should report the issue at https://github.com/Kilo-Org/saeeol/issues
+- /help: Get help with using SAEEOL
+- To give feedback, users should report the issue at https://github.com/byfabulist/saeeol/issues

package/src/tool/package.ts

@@ -0,0 +1,168 @@
+import { Effect, Schema } from "effect"
+import { Npm } from "@saeeol/core/npm"
+import * as Bus from "@/bus"
+import * as Tool from "./tool"
+import { ProviderInstallEvent } from "@/provider/provider-events"
+
+const Parameters = Schema.Struct({
+  action: Schema.Literals(["install", "list"]).annotate({
+    description: '"install" to install provider packages, "list" to show available providers',
+  }),
+  packages: Schema.optional(Schema.Array(Schema.String)).annotate({
+    description:
+      'Package names to install. npm names like "@ai-sdk/anthropic" or short names like "anthropic".',
+  }),
+})
+
+type Params = Schema.Schema.Type<typeof Parameters>
+
+const SHORT_NAME_MAP: Record<string, string> = {
+  anthropic: "@ai-sdk/anthropic",
+  openai: "@ai-sdk/openai",
+  "openai-compatible": "@ai-sdk/openai-compatible",
+  google: "@ai-sdk/google",
+  "google-vertex": "@ai-sdk/google-vertex",
+  bedrock: "@ai-sdk/amazon-bedrock",
+  "amazon-bedrock": "@ai-sdk/amazon-bedrock",
+  azure: "@ai-sdk/azure",
+  openrouter: "@openrouter/ai-sdk-provider",
+  groq: "@ai-sdk/groq",
+  deepinfra: "@ai-sdk/deepinfra",
+  gateway: "@ai-sdk/gateway",
+  alibaba: "@ai-sdk/alibaba",
+  cerebras: "@ai-sdk/cerebras",
+  xai: "@ai-sdk/xai",
+  mistral: "@ai-sdk/mistral",
+  cohere: "@ai-sdk/cohere",
+  togetherai: "@ai-sdk/togetherai",
+  perplexity: "@ai-sdk/perplexity",
+  vercel: "@ai-sdk/vercel",
+  gitlab: "gitlab-ai-provider",
+  venice: "venice-ai-sdk-provider",
+}
+
+const KNOWN_PROVIDERS = [
+  { npm: "@saeeol/gateway", label: "Saeeol Gateway (bundled)" },
+  { npm: "@ai-sdk/anthropic", label: "Anthropic (Claude)" },
+  { npm: "@ai-sdk/openai", label: "OpenAI (GPT)" },
+  { npm: "@ai-sdk/openai-compatible", label: "OpenAI Compatible" },
+  { npm: "@ai-sdk/google", label: "Google (Gemini)" },
+  { npm: "@ai-sdk/github-copilot", label: "GitHub Copilot" },
+  { npm: "@ai-sdk/amazon-bedrock", label: "Amazon Bedrock" },
+  { npm: "@ai-sdk/azure", label: "Azure OpenAI" },
+  { npm: "@ai-sdk/google-vertex", label: "Google Vertex AI" },
+  { npm: "@openrouter/ai-sdk-provider", label: "OpenRouter" },
+  { npm: "@ai-sdk/groq", label: "Groq" },
+  { npm: "@ai-sdk/deepinfra", label: "DeepInfra" },
+  { npm: "@ai-sdk/gateway", label: "Vercel AI Gateway" },
+  { npm: "@ai-sdk/alibaba", label: "Alibaba (Qwen)" },
+  { npm: "@ai-sdk/cerebras", label: "Cerebras" },
+  { npm: "@ai-sdk/xai", label: "xAI (Grok)" },
+  { npm: "@ai-sdk/mistral", label: "Mistral" },
+  { npm: "@ai-sdk/cohere", label: "Cohere" },
+  { npm: "@ai-sdk/togetherai", label: "Together AI" },
+  { npm: "@ai-sdk/perplexity", label: "Perplexity" },
+  { npm: "@ai-sdk/vercel", label: "Vercel" },
+]
+
+function resolve(pkg: string) {
+  if (pkg.startsWith("@") || pkg.startsWith("file://")) return pkg
+  return SHORT_NAME_MAP[pkg] ?? pkg
+}
+
+export const PackageTool = Tool.define(
+  "package",
+  Effect.gen(function* () {
+    return {
+      description: [
+        "Manage saeeol provider SDK packages.",
+        "",
+        "Use this tool when the user asks to install additional AI providers,",
+        "or when you detect that a required provider is not available.",
+        "",
+        'Actions: "install" — install provider packages, "list" — show available providers',
+        "",
+        "Short names: anthropic, openai, google, bedrock, azure, openrouter, groq,",
+        "deepinfra, cerebras, xai, mistral, cohere, togetherai, perplexity, vercel",
+      ].join("\n"),
+      parameters: Parameters,
+      execute: (params: Params, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          if (params.action === "list") {
+            const lines = [
+              "Available provider SDKs:",
+              "",
+              ...KNOWN_PROVIDERS.map((p) => `  ${p.label}\n    npm: ${p.npm}`),
+              "",
+              'Install: { action: "install", packages: ["anthropic"] }',
+            ]
+            return { title: "Available Providers", output: lines.join("\n"), metadata: {} }
+          }
+
+          // action === "install"
+          const packages = params.packages
+          if (!packages || packages.length === 0) {
+            return {
+              title: "Package Install",
+              output: "No packages specified. Provide package names in the 'packages' array.",
+              metadata: {},
+            }
+          }
+
+          const resolved = packages.map(resolve)
+
+          yield* ctx.ask({
+            permission: "package",
+            patterns: resolved,
+            always: resolved,
+            metadata: {},
+          })
+
+          const results: string[] = []
+          for (const pkg of resolved) {
+            void Bus.publish(ProviderInstallEvent.Started, {
+              providerID: pkg,
+              pkg,
+            })
+            try {
+              const entry = yield* Effect.promise(() => Npm.add(pkg))
+              if (!entry.entrypoint) {
+                void Bus.publish(ProviderInstallEvent.Failed, {
+                  providerID: pkg,
+                  pkg,
+                  error: "No import entrypoint found",
+                })
+                results.push(`X ${pkg}: no import entrypoint`)
+                continue
+              }
+              void Bus.publish(ProviderInstallEvent.Completed, {
+                providerID: pkg,
+                pkg,
+              })
+              results.push(`OK ${pkg}`)
+            } catch (err) {
+              const msg = err instanceof Error ? err.message : String(err)
+              void Bus.publish(ProviderInstallEvent.Failed, {
+                providerID: pkg,
+                pkg,
+                error: msg,
+              })
+              results.push(`X ${pkg}: ${msg}`)
+            }
+          }
+
+          return {
+            title: "Package Install",
+            output: [
+              `${resolved.length} package(s) processed:`,
+              "",
+              ...results,
+              "",
+              "Installed providers are now available.",
+            ].join("\n"),
+            metadata: {},
+          }
+        }),
+    }
+  }),
+)

package/src/tool/registry.ts

@@ -13,6 +13,7 @@ import { WebFetchTool } from "./webfetch"
 import { WriteTool } from "./write"
 import { InvalidTool } from "./invalid"
 import { SkillTool } from "./skill"
+import { PackageTool } from "./package"
 import * as Tool from "./tool"
 import { Config } from "@/config/config"
 import { type ToolContext as PluginToolContext, type ToolDefinition } from "@saeeol/plugin"
@@ -116,6 +117,7 @@ export const layer: Layer.Layer<
     const greptool = yield* GrepTool
     const patchtool = yield* ApplyPatchTool
     const skilltool = yield* SkillTool
+    const packagetool = yield* PackageTool
     const agent = yield* Agent.Service
     const suggesttool = yield* SuggestTool
     const saeeolToolInfos = yield* SaeeolToolRegistry.infos()
@@ -211,6 +213,7 @@ export const layer: Layer.Layer<
           todo: Tool.init(todo),
           search: Tool.init(websearch),
           skill: Tool.init(skilltool),
+          package: Tool.init(packagetool),
           patch: Tool.init(patchtool),
           question: Tool.init(question),
           lsp: Tool.init(lsptool),
@@ -237,6 +240,7 @@ export const layer: Layer.Layer<
               tool.todo,
               tool.search,
               tool.skill,
+              tool.package,
               tool.patch,
               tool.plan,
               ...(["cli", "vscode"].includes(Flag.SAEEOL_CLIENT) ? [tool.suggest] : []),

package/test/fixture/skills/agents-sdk/SKILL.md

@@ -11,21 +11,21 @@ description: Build AI agents on Cloudflare Workers using the Agents SDK. Load wh
 
 Fetch current docs from `https://github.com/cloudflare/agents/tree/main/docs` before implementing.
 
-| Topic               | Doc                           | Use for                                        |
-| ------------------- | ----------------------------- | ---------------------------------------------- |
-| Getting started     | `docs/getting-started.md`     | First agent, project setup                     |
-| State               | `docs/state.md`               | `setState`, `validateStateChange`, persistence |
-| Routing             | `docs/routing.md`             | URL patterns, `routeAgentRequest`, `basePath`  |
-| Callable methods    | `docs/callable-methods.md`    | `@callable`, RPC, streaming, timeouts          |
-| Scheduling          | `docs/scheduling.md`          | `schedule()`, `scheduleEvery()`, cron          |
-| Workflows           | `docs/workflows.md`           | `AgentWorkflow`, durable multi-step tasks      |
-| HTTP/WebSockets     | `docs/http-websockets.md`     | Lifecycle hooks, hibernation                   |
-| Email               | `docs/email.md`               | Email routing, secure reply resolver           |
-| MCP client          | `docs/mcp-client.md`          | Connecting to MCP servers                      |
-| MCP server          | `docs/mcp-servers.md`         | Building MCP servers with `McpAgent`           |
-| Client SDK          | `docs/client-sdk.md`          | `useAgent`, `useAgentChat`, React hooks        |
-| Human-in-the-loop   | `docs/human-in-the-loop.md`   | Approval flows, pausing workflows              |
-| Resumable streaming | `docs/resumable-streaming.md` | Stream recovery on disconnect                  |
+| Topic | Doc | Use for |
+|---|---|---|
+| Getting started | `docs/getting-started.md` | First agent, project setup |
+| State | `docs/state.md` | `setState`, `validateStateChange`, persistence |
+| Routing | `docs/routing.md` | URL patterns, `routeAgentRequest`, `basePath` |
+| Callable methods | `docs/callable-methods.md` | `@callable`, RPC, streaming, timeouts |
+| Scheduling | `docs/scheduling.md` | `schedule()`, `scheduleEvery()`, cron |
+| Workflows | `docs/workflows.md` | `AgentWorkflow`, durable multi-step tasks |
+| HTTP/WebSockets | `docs/http-websockets.md` | Lifecycle hooks, hibernation |
+| Email | `docs/email.md` | Email routing, secure reply resolver |
+| MCP client | `docs/mcp-client.md` | Connecting to MCP servers |
+| MCP server | `docs/mcp-servers.md` | Building MCP servers with `McpAgent` |
+| Client SDK | `docs/client-sdk.md` | `useAgent`, `useAgentChat`, React hooks |
+| Human-in-the-loop | `docs/human-in-the-loop.md` | Approval flows, pausing workflows |
+| Resumable streaming | `docs/resumable-streaming.md` | Stream recovery on disconnect |
 
 Cloudflare docs: https://developers.cloudflare.com/agents/
 
@@ -101,26 +101,26 @@ export default {
 
 Requests route to `/agents/{agent-name}/{instance-name}`:
 
-| Class      | URL                        |
-| ---------- | -------------------------- |
-| `Counter`  | `/agents/counter/user-123` |
-| `ChatRoom` | `/agents/chat-room/lobby`  |
+| Class | URL |
+|---|---|
+| `Counter` | `/agents/counter/user-123` |
+| `ChatRoom` | `/agents/chat-room/lobby` |
 
 Client: `useAgent({ agent: "Counter", name: "user-123" })`
 
 ## Core APIs
 
-| Task                | API                                                    |
-| ------------------- | ------------------------------------------------------ |
-| Read state          | `this.state.count`                                     |
-| Write state         | `this.setState({ count: 1 })`                          |
-| SQL query           | `` this.sql`SELECT * FROM users WHERE id = ${id}` ``   |
-| Schedule (delay)    | `await this.schedule(60, "task", payload)`             |
-| Schedule (cron)     | `await this.schedule("0 * * * *", "task", payload)`    |
-| Schedule (interval) | `await this.scheduleEvery(30, "poll")`                 |
-| RPC method          | `@callable() myMethod() { ... }`                       |
-| Streaming RPC       | `@callable({ streaming: true }) stream(res) { ... }`   |
-| Start workflow      | `await this.runWorkflow("ProcessingWorkflow", params)` |
+| Task | API |
+|---|---|
+| Read state | `this.state.count` |
+| Write state | `this.setState({ count: 1 })` |
+| SQL query | `` this.sql`SELECT * FROM users WHERE id = ${id}` `` |
+| Schedule (delay) | `await this.schedule(60, "task", payload)` |
+| Schedule (cron) | `await this.schedule("0 * * * *", "task", payload)` |
+| Schedule (interval) | `await this.scheduleEvery(30, "poll")` |
+| RPC method | `@callable() myMethod() { ... }` |
+| Streaming RPC | `@callable({ streaming: true }) stream(res) { ... }` |
+| Start workflow | `await this.runWorkflow("ProcessingWorkflow", params)` |
 
 ## React Client