@poncho-ai/harness 0.20.13 → 0.21.0

package/dist/index.js

@@ -406,6 +406,1143 @@ var loadPonchoConfig = async (workingDir) => {
 import { mkdir, readdir, readFile as readFile3, rm, unlink, writeFile as writeFile2 } from "fs/promises";
 import { dirname, resolve as resolve4, sep } from "path";
 import { defineTool } from "@poncho-ai/sdk";
+
+// src/generated/poncho-docs.ts
+var PONCHO_DOCS = {
+  "api": `# HTTP API & Client SDK
+
+> Back to [README](../README.md)
+
+Your deployed agent exposes these endpoints:
+
+| Endpoint | Use case |
+|----------|----------|
+| \`GET /health\` | Health checks for load balancers |
+| \`GET /api/docs\` | Interactive API documentation (Scalar) |
+| \`GET /api/openapi.json\` | OpenAPI 3.1 spec (machine-readable) |
+| \`GET /api/auth/session\` | Session status + CSRF token for browser clients |
+| \`POST /api/auth/login\` | Passphrase login for browser sessions |
+| \`POST /api/auth/logout\` | End browser session |
+| \`GET /api/conversations\` | List stored conversations |
+| \`POST /api/conversations\` | Create conversation |
+| \`GET /api/conversations/:conversationId\` | Get conversation transcript |
+| \`PATCH /api/conversations/:conversationId\` | Rename conversation |
+| \`DELETE /api/conversations/:conversationId\` | Delete conversation |
+| \`POST /api/conversations/:conversationId/messages\` | Stream a new assistant response |
+| \`GET /api/conversations/:conversationId/events\` | Attach to live SSE stream |
+| \`POST /api/conversations/:conversationId/stop\` | Cancel an in-flight run |
+| \`POST /api/approvals/:approvalId\` | Resolve tool approval request |
+| \`GET /api/uploads/:key\` | Retrieve uploaded file |
+| \`GET\\|POST /api/cron/:jobName\` | Trigger a cron job (see [Cron Jobs](../README.md#cron-jobs)) |
+| \`GET /api/browser/status\` | Browser session status (when browser is enabled) |
+| \`GET /api/browser/stream\` | SSE stream of live browser viewport frames |
+| \`POST /api/browser/input\` | Send input events to the browser session |
+| \`POST /api/browser/navigate\` | Navigate the browser to a URL |
+
+> **Tip:** Visit \`/api/docs\` on any running agent for interactive API documentation with request examples and full schema details.
+
+## POST /api/conversations/:conversationId/messages (streaming)
+
+\`\`\`bash
+curl -N -X POST https://my-agent.vercel.app/api/conversations/<conversation-id>/messages \\
+  -H "Content-Type: application/json" \\
+  -d '{"message": "Write a hello world function"}'
+\`\`\`
+
+Response: Server-Sent Events (\`run:started\`, \`model:chunk\`, \`tool:*\`, \`run:completed\`).
+
+On serverless deployments with \`PONCHO_MAX_DURATION\` set, the \`run:completed\` event may
+include \`continuation: true\` in \`result\`, indicating the agent stopped early due to a
+platform timeout and the client should send another message (e.g., \`"Continue"\`) on the
+same conversation to resume.
+
+## Build a custom chat UI
+
+You can build your own chat frontend by calling Poncho's conversation endpoints directly.
+
+Typical UI flow:
+
+1. Create a conversation: \`POST /api/conversations\`
+2. Send a message and stream events: \`POST /api/conversations/:conversationId/messages\`
+3. Append \`model:chunk\` events into the in-progress assistant message
+4. Render \`tool:*\` events as activity status
+5. Finalize on \`run:completed\` (or handle \`run:error\` / \`run:cancelled\`)
+6. Reload full transcript on refresh: \`GET /api/conversations/:conversationId\`
+
+Minimal browser example (SSE parsing):
+
+\`\`\`typescript
+async function streamMessage(conversationId: string, message: string) {
+  const response = await fetch(
+    \`/api/conversations/\${encodeURIComponent(conversationId)}/messages\`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ message }),
+      credentials: "include", // keep for session auth
+    },
+  );
+
+  if (!response.ok || !response.body) {
+    throw new Error(\`Streaming request failed: HTTP \${response.status}\`);
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const frames = buffer.split("\\n\\n");
+    buffer = frames.pop() ?? "";
+
+    for (const frame of frames) {
+      const lines = frame
+        .split("\\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+
+      const eventLine = lines.find((line) => line.startsWith("event:"));
+      const dataLine = lines.find((line) => line.startsWith("data:"));
+      if (!eventLine || !dataLine) continue;
+
+      const eventName = eventLine.slice("event:".length).trim();
+      const payload = JSON.parse(dataLine.slice("data:".length).trim());
+
+      if (eventName === "model:chunk") {
+        // Append payload.content to the active assistant message
+      } else if (eventName === "tool:started") {
+        // Show "running tool" activity
+      } else if (eventName === "tool:completed") {
+        // Mark tool activity as complete
+      } else if (eventName === "run:completed") {
+        // Finalize assistant message
+      } else if (eventName === "run:error" || eventName === "run:cancelled") {
+        // Show interrupted/error state in UI
+      }
+    }
+  }
+}
+\`\`\`
+
+Useful optional endpoints for richer UIs:
+
+- \`POST /api/conversations/:conversationId/stop\` with \`{ "runId": "<run-id>" }\` to cancel an in-flight run
+- \`GET /api/conversations/:conversationId/events\` to attach/re-attach to a live event stream
+- \`POST /api/approvals/:approvalId\` with \`{ "approved": true|false }\` to resolve \`tool:approval:required\`
+
+Auth notes for custom frontends:
+
+- Browser session mode: \`GET /api/auth/session\`, then \`POST /api/auth/login\`, and send \`x-csrf-token\` on mutating requests.
+- API token mode: send \`Authorization: Bearer <PONCHO_AUTH_TOKEN>\` on API requests.
+
+## Headless mode (API-only)
+
+If you're building your own frontend or using the agent purely as an API, disable the built-in Web UI:
+
+\`\`\`javascript
+// poncho.config.js
+export default {
+  webUi: false,
+}
+\`\`\`
+
+When \`webUi\` is \`false\`:
+- The built-in chat UI at \`/\` is disabled (returns 404).
+- All \`/api/*\` endpoints, \`/health\`, and \`/api/docs\` continue to work normally.
+- Messaging adapter routes (e.g., Slack) are unaffected.
+
+This is useful for API-only deployments where a separate frontend (e.g., a Next.js app) calls the Poncho API via a backend-for-frontend pattern.
+
+## TypeScript/JavaScript Client
+
+Install the client SDK for type-safe access:
+
+\`\`\`bash
+npm install @poncho-ai/client
+\`\`\`
+
+\`\`\`typescript
+import { AgentClient } from '@poncho-ai/client'
+
+const agent = new AgentClient({
+  url: 'https://my-agent.vercel.app',
+  apiKey: 'your-api-key'  // Optional, if auth enabled
+})
+
+// Create and send in one call (conversation() returns a stateful helper)
+const conv = agent.conversation()
+const first = await conv.send('What is 2 + 2?')
+console.log(first.result.response)
+const followUp = await conv.send('And what is 3 + 3?')
+
+// Or manage conversations explicitly
+const created = await agent.createConversation({ title: 'Session' })
+const response = await agent.sendMessage(created.conversationId, 'What is 2 + 2?')
+console.log(response.result.response)
+
+// Send with file attachments
+await agent.sendMessage(created.conversationId, 'Describe this image', {
+  files: [{ data: base64Data, mediaType: 'image/png', filename: 'photo.png' }],
+})
+
+// One-shot run (creates a conversation automatically)
+const result = await agent.run({ task: 'Write a haiku about coding' })
+
+// Stream events (creates a conversation automatically)
+for await (const event of agent.stream({ task: 'Write a story' })) {
+  if (event.type === 'model:chunk') process.stdout.write(event.content)
+}
+
+// List, get, delete conversations
+const conversations = await agent.listConversations()
+const transcript = await agent.getConversation(created.conversationId)
+await agent.deleteConversation(created.conversationId)
+\`\`\`
+
+## Multi-turn Conversations
+
+Conversations are persisted and keyed by \`conversationId\`.
+
+Typical flow:
+
+1. \`POST /api/conversations\`
+2. \`POST /api/conversations/:conversationId/messages\`
+3. Repeat step 2 for follow-up turns
+4. \`GET /api/conversations/:conversationId\` to fetch full transcript
+
+## File Attachments
+
+Agents support multimodal inputs \u2014 attach files to any message via the Web UI, API, or client SDK.
+
+### Web UI
+
+Click the attach button (paperclip icon), drag files onto the chat, or paste from your clipboard. Attached files appear as previews above the composer before sending.
+
+### HTTP API
+
+Send files as \`multipart/form-data\` or as base64-encoded JSON:
+
+\`\`\`bash
+# multipart/form-data
+curl -N -X POST "http://localhost:3000/api/conversations/<id>/messages" \\
+  -F "message=Describe this image" \\
+  -F "files=@screenshot.png"
+
+# JSON with base64
+curl -N -X POST "http://localhost:3000/api/conversations/<id>/messages" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "message": "Describe this image",
+    "files": [{
+      "data": "<base64-encoded>",
+      "mediaType": "image/png",
+      "filename": "screenshot.png"
+    }]
+  }'
+\`\`\`
+
+### Client SDK
+
+\`\`\`typescript
+const response = await agent.sendMessage(conversationId, 'Describe this image', {
+  files: [{ data: base64Data, mediaType: 'image/png', filename: 'screenshot.png' }],
+})
+\`\`\`
+
+### Upload storage
+
+By default, uploaded files are stored on the local filesystem. For production deployments, configure a cloud upload provider:
+
+\`\`\`javascript
+// poncho.config.js
+export default {
+  uploads: {
+    provider: 'vercel-blob',  // 'local' | 'vercel-blob' | 's3'
+    access: 'public',         // vercel-blob access mode (default: 'public')
+  },
+  // Or S3-compatible storage:
+  uploads: {
+    provider: 's3',
+    bucket: 'my-agent-uploads',
+    region: 'us-east-1',
+    endpoint: 'https://s3.amazonaws.com',  // optional, for S3-compatible services
+  },
+}
+\`\`\`
+
+Environment variables for upload providers:
+
+| Provider | Required env vars |
+|----------|-------------------|
+| \`vercel-blob\` | \`BLOB_READ_WRITE_TOKEN\` |
+| \`s3\` | \`AWS_ACCESS_KEY_ID\`, \`AWS_SECRET_ACCESS_KEY\`, \`PONCHO_UPLOADS_BUCKET\` (or \`uploads.bucket\` in config) |
+`,
+  "features": `# Platform Features
+
+> Back to [README](../README.md)
+
+## Web UI
+
+The built-in web UI at \`http://localhost:3000\` provides a full-featured chat interface:
+
+- **Conversation sidebar**: create, switch between, rename, and delete conversations. Each conversation has a persistent URL (\`/c/:conversationId\`).
+- **Streaming responses**: assistant text and tool activity stream in real time with structured sections (text blocks, tool call groups).
+- **Context window progress**: a circular ring around the send button shows how much of the model's context window is used. The ring updates as the model responds and as tool results come in, with warning (70%) and critical (90%) color thresholds. Context usage is persisted per conversation so the ring stays accurate when switching between conversations.
+- **File attachments**: attach images, PDFs, text files, and more via the attach button, drag-and-drop, or clipboard paste. Supported types include images, video, PDF, CSV, JSON, HTML, and plain text (up to 25 MB each).
+- **Image lightbox**: click any image in the chat to view it full-size.
+- **Tool approval**: when a tool requires approval, the UI shows an inline Approve/Deny prompt.
+- **Stop streaming**: click the send button while a response is streaming to cancel the current run.
+- **Installable PWA**: the web UI includes a manifest and service worker, so it can be installed as a standalone app on desktop and mobile.
+
+Disable the built-in UI for API-only deployments by setting \`webUi: false\` in \`poncho.config.js\`.
+
+## Messaging Integrations
+
+Connect your Poncho agent to messaging platforms so it responds to @mentions.
+
+### Slack
+
+#### 1. Create a Slack App
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app "From scratch"
+2. Under **OAuth & Permissions**, add these Bot Token Scopes:
+   - \`app_mentions:read\`
+   - \`chat:write\`
+   - \`reactions:write\`
+3. Under **Event Subscriptions**, enable events:
+   - Set the Request URL to \`https://<your-deployed-agent>/api/messaging/slack\`
+   - Subscribe to the \`app_mention\` bot event
+4. Install the app to your workspace (generates a Bot Token \`xoxb-...\`)
+5. Copy the **Signing Secret** from the Basic Information page
+
+#### 2. Configure your agent
+
+Add environment variables to \`.env\`:
+
+\`\`\`
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_SIGNING_SECRET=...
+\`\`\`
+
+Add messaging to \`poncho.config.js\`:
+
+\`\`\`javascript
+export default {
+  // ... your existing config ...
+  messaging: [
+    { platform: 'slack' }
+  ]
+}
+\`\`\`
+
+#### 3. Deploy
+
+The messaging endpoint works on all deployment targets (Vercel, Docker, Fly.io, etc.). For local development with Slack, use a tunnel like [ngrok](https://ngrok.com) to expose your local server.
+
+**Vercel deployments:** install \`@vercel/functions\` so Poncho can keep the serverless function alive while the agent processes messages:
+
+\`\`\`bash
+npm install @vercel/functions
+\`\`\`
+
+This is detected automatically at runtime -- no extra configuration needed.
+
+#### How it works
+
+- When a user @mentions your bot in Slack, the agent receives the message and responds in the same thread.
+- Each Slack thread maps to a separate Poncho conversation with persistent history.
+- The bot adds an "eyes" reaction while processing and removes it when done.
+- Long responses are automatically split into multiple messages.
+
+#### Custom environment variable names
+
+If you need different env var names (e.g., running multiple Slack integrations):
+
+\`\`\`javascript
+messaging: [
+  {
+    platform: 'slack',
+    botTokenEnv: 'MY_SLACK_BOT_TOKEN',
+    signingSecretEnv: 'MY_SLACK_SIGNING_SECRET',
+  }
+]
+\`\`\`
+
+### Telegram
+
+#### 1. Create a Telegram Bot
+
+1. Open [Telegram](https://telegram.org) and start a chat with [@BotFather](https://t.me/BotFather)
+2. Send \`/newbot\` and follow the prompts to create your bot
+3. Copy the **Bot Token** (looks like \`123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11\`)
+
+> **Privacy mode** is enabled by default, which means the bot only receives messages that @mention it in groups. This is the desired behavior -- no changes needed.
+
+#### 2. Configure your agent
+
+Add environment variables to \`.env\`:
+
+\`\`\`
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+TELEGRAM_WEBHOOK_SECRET=my-secret-token
+\`\`\`
+
+The webhook secret is optional but recommended. It can be any string up to 256 characters (\`A-Z\`, \`a-z\`, \`0-9\`, \`_\`, \`-\`).
+
+Add messaging to \`poncho.config.js\`:
+
+\`\`\`javascript
+export default {
+  // ... your existing config ...
+  messaging: [
+    { platform: 'telegram' }
+  ]
+}
+\`\`\`
+
+#### 3. Set up the webhook
+
+After deploying your agent, register the webhook URL with Telegram:
+
+\`\`\`bash
+curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \\
+  -H "Content-Type: application/json" \\
+  -d '{"url": "https://<your-deployed-agent>/api/messaging/telegram", "secret_token": "<YOUR_WEBHOOK_SECRET>"}'
+\`\`\`
+
+Omit the \`secret_token\` field if you're not using a webhook secret.
+
+For local development, use a tunnel like [ngrok](https://ngrok.com) to expose your local server, then register the tunnel URL as the webhook.
+
+#### 4. Deploy
+
+The messaging endpoint works on all deployment targets (Vercel, Docker, Fly.io, etc.).
+
+**Vercel deployments:** install \`@vercel/functions\` so Poncho can keep the serverless function alive while the agent processes messages:
+
+\`\`\`bash
+npm install @vercel/functions
+\`\`\`
+
+#### How it works
+
+- **Private chats**: the bot responds to all messages.
+- **Groups**: the bot only responds when @mentioned (e.g., \`@mybot what's the weather?\`). The mention is stripped before the message reaches the agent.
+- **Forum topics**: each topic in a supergroup is treated as a separate conversation.
+- The bot shows a "typing..." indicator while processing.
+- Long responses are automatically split into multiple messages (4096 char limit).
+- **Photos and documents** sent to the bot are forwarded to the agent as file attachments.
+- Use \`/new\` to reset the conversation and start fresh. In groups, use \`/new@botusername\`.
+
+#### Restricting access
+
+By default any Telegram user can message your bot. To restrict it to specific users, add their numeric Telegram user IDs:
+
+\`\`\`javascript
+messaging: [
+  {
+    platform: 'telegram',
+    allowedUserIds: [1056240469, 9876543210],
+  }
+]
+\`\`\`
+
+Messages from anyone not on the list are silently ignored. You can find your user ID by messaging [@userinfobot](https://t.me/userinfobot) on Telegram.
+
+#### Custom environment variable names
+
+If you need different env var names (e.g., running multiple Telegram integrations):
+
+\`\`\`javascript
+messaging: [
+  {
+    platform: 'telegram',
+    botTokenEnv: 'MY_TELEGRAM_BOT_TOKEN',
+    webhookSecretEnv: 'MY_TELEGRAM_WEBHOOK_SECRET',
+  }
+]
+\`\`\`
+
+### Email (Resend)
+
+#### 1. Set up Resend
+
+1. Create an account at [resend.com](https://resend.com) and add your domain
+2. Enable **Inbound** on your domain in the Resend dashboard
+3. Create a **Webhook** subscribing to the \`email.received\` event
+   - Set the endpoint URL to \`https://<your-deployed-agent>/api/messaging/resend\`
+4. Copy the webhook **Signing Secret** from the webhook details page
+5. Create an API key at [resend.com/api-keys](https://resend.com/api-keys)
+
+#### 2. Configure your agent
+
+Add environment variables to \`.env\`:
+
+\`\`\`
+RESEND_API_KEY=re_...
+RESEND_WEBHOOK_SECRET=whsec_...
+RESEND_FROM=Agent <agent@yourdomain.com>
+RESEND_REPLY_TO=support@yourdomain.com   # optional
+\`\`\`
+
+Add messaging to \`poncho.config.js\`:
+
+\`\`\`javascript
+export default {
+  // ... your existing config ...
+  messaging: [
+    { platform: 'resend' }
+  ]
+}
+\`\`\`
+
+Install the Resend SDK:
+
+\`\`\`bash
+npm install resend
+\`\`\`
+
+#### 3. Deploy
+
+The messaging endpoint works on all deployment targets (Vercel, Docker, Fly.io, etc.). For local development, use a tunnel like [ngrok](https://ngrok.com) to expose your local server and set it as your Resend webhook URL.
+
+**Vercel deployments:** install \`@vercel/functions\` so Poncho can keep the serverless function alive while the agent processes messages:
+
+\`\`\`bash
+npm install @vercel/functions
+\`\`\`
+
+#### How it works
+
+- When someone emails your agent's address, the agent receives the message and replies in the same email thread.
+- Each email thread maps to a separate Poncho conversation with persistent history.
+- Email attachments are passed to the agent as file inputs.
+- Agent responses are formatted as HTML emails with proper markdown rendering.
+- Quoted reply content is automatically stripped so the agent only sees the new message.
+- The incoming email's sender and subject are included in the task header (\`From:\` / \`Subject:\`) so the agent knows who sent the email.
+
+#### Response modes
+
+Resend email supports two response modes:
+
+- **\`"auto-reply"\`** (default): The agent's text response is automatically sent back as an email reply. Simple and zero-config.
+- **\`"tool"\`**: Auto-reply is disabled. Instead, the agent gets a \`send_email\` tool with full control over recipients, subject, body, CC/BCC, and threading. Use this for agents that need to send emails to different people, compose custom subjects, or decide whether to reply at all.
+
+#### Options
+
+\`\`\`javascript
+messaging: [
+  {
+    platform: 'resend',
+    // Optional: restrict who can email the agent
+    allowedSenders: ['*@mycompany.com', 'partner@external.com'],
+    // Optional: custom env var names
+    apiKeyEnv: 'MY_RESEND_API_KEY',
+    webhookSecretEnv: 'MY_RESEND_WEBHOOK_SECRET',
+    fromEnv: 'MY_RESEND_FROM',
+    replyToEnv: 'MY_RESEND_REPLY_TO',
+  }
+]
+\`\`\`
+
+**Tool mode** gives the agent explicit email control:
+
+\`\`\`javascript
+messaging: [
+  {
+    platform: 'resend',
+    mode: 'tool',
+    // Optional: restrict who the agent can email (glob patterns)
+    allowedRecipients: ['*@mycompany.com', 'partner@external.com'],
+    // Optional: max emails per agent run (default: 10)
+    maxSendsPerRun: 5,
+  }
+]
+\`\`\`
+
+In tool mode the agent can call \`send_email\` with:
+- \`to\` (required): recipient email addresses
+- \`subject\` (required): email subject
+- \`body\` (required): markdown content (auto-converted to HTML)
+- \`cc\`, \`bcc\` (optional): additional recipients
+- \`in_reply_to\` (optional): message ID for threading as a reply; omit for a standalone email
+
+### Custom Messaging Adapters
+
+The \`MessagingAdapter\` interface from \`@poncho-ai/messaging\` is the extension point for adding other messaging platforms (SendGrid, Postmark, Discord, etc.). Implement the interface and wire it with \`AgentBridge\`:
+
+\`\`\`typescript
+import { AgentBridge, type MessagingAdapter } from '@poncho-ai/messaging';
+// Shared email utilities for threading (optional, useful for email adapters)
+import { parseReferences, deriveRootMessageId, buildReplyHeaders } from '@poncho-ai/messaging';
+\`\`\`
+
+See the \`SlackAdapter\` and \`ResendAdapter\` source code for reference implementations.
+
+## Browser Automation (Experimental)
+
+Give your agent the ability to browse the web with a headless Chromium browser. Powered by [\`agent-browser\`](https://github.com/vercel-labs/agent-browser).
+
+\`\`\`javascript
+// poncho.config.js
+export default {
+  browser: true,
+  // or with options:
+  browser: {
+    viewport: { width: 1280, height: 720 },
+    quality: 80,
+    everyNthFrame: 2,
+    headless: true,
+    profileDir: "~/.poncho/browser-profiles",
+    stealth: true,           // Anti-bot-detection (default: true)
+    userAgent: "custom UA",  // Override the default stealth user-agent
+  },
+}
+\`\`\`
+
+When \`browser\` is enabled, the agent gets eight tools:
+
+- \`browser_open\` \u2014 Navigate to a URL. Starts real-time viewport streaming.
+- \`browser_snapshot\` \u2014 Get the page as a compact accessibility tree with element refs (\`@e1\`, \`@e2\`, ...).
+- \`browser_click\` \u2014 Click an element by ref.
+- \`browser_type\` \u2014 Type text into a form field by ref.
+- \`browser_content\` \u2014 Get the visible text content of the current page as plain text.
+- \`browser_screenshot\` \u2014 Take a PNG screenshot (sent to the model as an image).
+- \`browser_scroll\` \u2014 Scroll the page up or down.
+- \`browser_close\` \u2014 Save session and close the browser.
+
+The agent uses the snapshot/ref pattern: call \`browser_snapshot\` to get refs, then \`browser_click @e2\` or \`browser_type @e3 "hello"\`. Re-snapshot after each interaction since refs change when the page updates.
+
+### Live viewport
+
+The web UI shows a real-time browser viewport panel alongside the chat when a browser session is active. Frames stream via CDP screencast through the \`/api/browser/stream\` SSE endpoint.
+
+### Session persistence
+
+Browser sessions are stored in profile directories (\`~/.poncho/browser-profiles/<agent-id>/\`). Cookies, localStorage, and other browser state persist across runs, so the agent can pick up where it left off (e.g., staying logged in across cron job runs).
+
+### Stealth mode
+
+Stealth mode is **enabled by default** (\`stealth: true\`) and reduces bot-detection fingerprints so websites treat the browser like a regular user session. It applies:
+
+- A realistic Chrome user-agent string (matching the host OS)
+- \`--disable-blink-features=AutomationControlled\` flag
+- \`navigator.webdriver\` overridden to \`false\`
+- \`window.chrome\` shim for headless Chromium
+- Fake \`navigator.plugins\` (3 standard Chrome plugins)
+- \`navigator.languages\` fallback (\`['en-US', 'en']\`)
+- WebGL vendor/renderer patched to hide SwiftShader
+- \`Notification.permission\` patched for headless mode
+- Browser-level \`--user-agent\` flag (covers Web Workers)
+
+To disable stealth mode (e.g., for trusted internal sites), set \`stealth: false\`. To use a custom user-agent while keeping other stealth patches, set \`userAgent\`:
+
+\`\`\`javascript
+browser: {
+  stealth: true,             // default
+  userAgent: "MyBot/1.0",    // overrides the auto-detected Chrome UA
+}
+\`\`\`
+
+### Setup
+
+Install the browser package in your agent project:
+
+\`\`\`bash
+pnpm add @poncho-ai/browser
+\`\`\`
+
+Then set \`browser: true\` in \`poncho.config.js\`. Chromium is downloaded automatically via a \`postinstall\` hook (skipped when \`CI\` or \`SERVERLESS\` env vars are set).
+
+**Serverless deployments** (Lambda, Vercel, etc.): use \`@sparticuz/chromium\` instead of the bundled Chromium:
+
+\`\`\`bash
+pnpm add @sparticuz/chromium
+\`\`\`
+
+\`\`\`javascript
+// poncho.config.js
+import chromium from "@sparticuz/chromium";
+
+export default {
+  browser: {
+    executablePath: await chromium.executablePath(),
+    headless: true,
+  },
+};
+\`\`\`
+
+## Subagents
+
+Poncho agents can spawn recursive copies of themselves as **subagents**. Each subagent runs in its own independent conversation with full access to the agent's tools and skills. The parent agent controls the subagent lifecycle and receives results directly.
+
+Subagents are useful when an agent needs to parallelize work, delegate a subtask, or isolate a line of investigation without polluting the main conversation context.
+
+### How it works
+
+When the agent decides to use a subagent, it calls \`spawn_subagent\` with a task description. The subagent runs to completion and the result is returned to the parent \u2014 the call is **blocking**, so the parent waits for the subagent to finish before continuing.
+
+The parent can also send follow-up messages to existing subagents with \`message_subagent\`, stop a running subagent with \`stop_subagent\`, or list all its subagents with \`list_subagents\`.
+
+### Available tools
+
+| Tool | Description |
+|------|-------------|
+| \`spawn_subagent\` | Create a new subagent with a task. Blocks until the subagent completes and returns the result. |
+| \`message_subagent\` | Send a follow-up message to an existing subagent. Blocks until it responds. |
+| \`stop_subagent\` | Stop a running subagent. |
+| \`list_subagents\` | List all subagents for the current conversation with their IDs, tasks, and statuses. |
+
+### Limits
+
+- **Max depth**: 3 levels of nesting (an agent can spawn a subagent, which can spawn another, but no deeper).
+- **Max concurrent**: 5 subagents per parent conversation.
+
+### Memory isolation
+
+Subagents have **read-only** access to the parent agent's persistent memory. They can recall information but cannot modify the main memory document. This prevents subagents from accidentally overwriting each other's memory updates.
+
+### Approvals
+
+When a subagent invokes a tool that requires approval, the approval request is **tunneled to the parent conversation**. You'll see the approval prompt inline in the parent's message thread with a label indicating which subagent is asking. The parent conversation also shows an orange dot in the sidebar while any subagent is waiting for approval.
+
+### Web UI
+
+In the web UI, subagent conversations appear **nested under their parent** in the sidebar (tree-style indentation). Clicking a subagent conversation shows it in read-only mode \u2014 you can view the full context but cannot send messages, since the parent agent controls the subagent.
+
+When the parent conversation is active, \`spawn_subagent\` tool calls in the tool activity timeline are clickable links that navigate to the subagent's conversation.
+
+## Persistent Memory
+
+When \`memory.enabled\` is true in \`poncho.config.js\`, the harness enables a simple memory model:
+
+- A single persistent main memory document is loaded at run start and interpolated into the system prompt under \`## Persistent Memory\`.
+- \`memory_main_update\` can replace or append to that document. The tool description instructs the model to proactively evaluate each turn whether durable memory should be updated.
+- \`conversation_recall\` can search recent prior conversations (keyword scoring) when historical context is relevant (\`as we discussed\`, \`last time\`, etc.).
+
+\`\`\`javascript
+// poncho.config.js
+export default {
+  storage: {
+    provider: 'local',           // 'local' | 'memory' | 'redis' | 'upstash' | 'dynamodb'
+    memory: {
+      enabled: true,
+      maxRecallConversations: 20, // Bounds conversation_recall scan size
+    },
+  },
+}
+\`\`\`
+
+Available memory tools:
+
+- \`memory_main_get\`
+- \`memory_main_update\`
+- \`conversation_recall\`
+`,
+  "configuration": `# Configuration & Security
+
+> Back to [README](../README.md)
+
+## Credential Pattern
+
+All credentials in \`poncho.config.js\` use **env var name** fields (\`*Env\` suffix). The config specifies *which* environment variable to read \u2014 never the secret value itself. Every \`*Env\` field has a sensible default, so you only need to set the field when your env var name differs from the convention:
+
+| Config field | Default env var | Purpose |
+|---|---|---|
+| \`providers.anthropic.apiKeyEnv\` | \`ANTHROPIC_API_KEY\` | Anthropic model API key |
+| \`providers.openai.apiKeyEnv\` | \`OPENAI_API_KEY\` | OpenAI model API key |
+| \`auth.tokenEnv\` | \`PONCHO_AUTH_TOKEN\` | Auth passphrase / bearer token |
+| \`storage.urlEnv\` | \`UPSTASH_REDIS_REST_URL\` / \`REDIS_URL\` | Storage connection URL |
+| \`storage.tokenEnv\` | \`UPSTASH_REDIS_REST_TOKEN\` | Upstash REST token |
+| \`telemetry.latitude.apiKeyEnv\` | \`LATITUDE_API_KEY\` | Latitude API key |
+| \`telemetry.latitude.projectIdEnv\` | \`LATITUDE_PROJECT_ID\` | Latitude project ID |
+| \`messaging[].botTokenEnv\` | \`SLACK_BOT_TOKEN\` | Slack bot token |
+| \`messaging[].signingSecretEnv\` | \`SLACK_SIGNING_SECRET\` | Slack signing secret |
+| \`messaging[].botTokenEnv\` | \`TELEGRAM_BOT_TOKEN\` | Telegram bot token |
+| \`messaging[].webhookSecretEnv\` | \`TELEGRAM_WEBHOOK_SECRET\` | Telegram webhook secret (optional) |
+| \`messaging[].apiKeyEnv\` | \`RESEND_API_KEY\` | Resend API key |
+| \`messaging[].webhookSecretEnv\` | \`RESEND_WEBHOOK_SECRET\` | Resend webhook signing secret |
+| \`messaging[].fromEnv\` | \`RESEND_FROM\` | Resend sender address |
+| \`messaging[].replyToEnv\` | \`RESEND_REPLY_TO\` | Resend reply-to address (optional) |
+| \`mcp[].auth.tokenEnv\` | *(user-defined)* | MCP server bearer token |
+
+## Config File Reference (\`poncho.config.js\`)
+
+\`\`\`javascript
+export default {
+  // Custom harness (default: @poncho-ai/harness)
+  harness: '@poncho-ai/harness',  // or './my-harness.js'
+
+  // MCP servers (remote)
+  mcp: [
+    // Remote: Connect to external server
+    {
+      name: 'github',
+      url: 'https://mcp.example.com/github',
+      auth: { type: 'bearer', tokenEnv: 'GITHUB_TOKEN' },
+    }
+  ],
+
+  // Extra directories to scan for skills (skills/ is always scanned)
+  skillPaths: ['.cursor/skills'],
+
+  // Tool access: true (available), false (disabled), 'approval' (requires human approval)
+  // Any tool name works \u2014 harness tools, adapter tools (send_email), MCP tools, etc.
+  tools: {
+    list_directory: true,          // available (default)
+    read_file: true,               // available (default)
+    write_file: true,              // gated by environment for writes
+    delete_file: 'approval',       // requires human approval
+    delete_directory: 'approval',  // requires human approval
+    send_email: 'approval',        // requires human approval
+    byEnvironment: {
+      production: {
+        write_file: false,         // disable writes in production
+        delete_file: false,        // disable deletes in production
+        delete_directory: false,   // disable deletes in production
+        send_email: 'approval',    // keep approval in production
+      },
+      development: {
+        send_email: true,          // skip approval in dev
+      },
+    },
+  },
+
+  // Authentication (protects both Web UI and API)
+  auth: {
+    required: true,
+    type: 'bearer',              // 'bearer' | 'header' | 'custom'
+    // tokenEnv: 'PONCHO_AUTH_TOKEN',  // env var name (default)
+  },
+  // When auth.required is true:
+  // - Web UI: users enter the passphrase (value of PONCHO_AUTH_TOKEN env var)
+  // - API: clients include Authorization: Bearer <token> header
+
+  // Model provider API key env var overrides (optional)
+  providers: {
+    // anthropic: { apiKeyEnv: 'ANTHROPIC_API_KEY' },  // default
+    // openai: { apiKeyEnv: 'OPENAI_API_KEY' },        // default
+  },
+
+  // Unified storage (preferred). Replaces separate \`state\` and \`memory\` blocks.
+  // Credentials are read from env vars; override the var name with *Env fields.
+  storage: {
+    provider: 'upstash',         // 'local' | 'memory' | 'redis' | 'upstash' | 'dynamodb'
+    // urlEnv: 'UPSTASH_REDIS_REST_URL',     // default (falls back to KV_REST_API_URL)
+    // tokenEnv: 'UPSTASH_REDIS_REST_TOKEN', // default (falls back to KV_REST_API_TOKEN)
+    ttl: {
+      conversations: 3600,       // seconds
+      memory: 0,                 // 0/undefined means no expiration
+    },
+    memory: {
+      enabled: true,
+      maxRecallConversations: 20, // Bounds conversation_recall scan size
+    },
+  },
+
+  // Telemetry destination
+  telemetry: {
+    enabled: true,
+    otlp: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+    // Or use Latitude (reads from LATITUDE_API_KEY and LATITUDE_PROJECT_ID env vars by default)
+    latitude: {
+      // apiKeyEnv: 'LATITUDE_API_KEY',       // default
+      // projectIdEnv: 'LATITUDE_PROJECT_ID', // default
+      path: 'your/prompt-path',               // optional, defaults to agent name
+    },
+  },
+
+  // Messaging platform integrations
+  messaging: [
+    { platform: 'slack' },                                 // Uses SLACK_BOT_TOKEN + SLACK_SIGNING_SECRET
+    // { platform: 'slack', botTokenEnv: 'MY_BOT_TOKEN' }, // Custom env var names
+    { platform: 'telegram' },                              // Uses TELEGRAM_BOT_TOKEN (+ optional TELEGRAM_WEBHOOK_SECRET)
+    // { platform: 'telegram', botTokenEnv: 'MY_TG_TOKEN' }, // Custom env var names
+    { platform: 'resend' },                                // Uses RESEND_API_KEY + RESEND_WEBHOOK_SECRET + RESEND_FROM
+    // { platform: 'resend', mode: 'tool', replyToEnv: 'RESEND_REPLY_TO' }, // Tool mode with custom reply-to
+  ],
+
+  // File upload storage (default: local filesystem)
+  uploads: {
+    provider: 'local',           // 'local' | 'vercel-blob' | 's3'
+    // access: 'public',         // vercel-blob access mode
+    // bucket: 'my-uploads',     // S3 bucket name
+    // region: 'us-east-1',      // S3 region
+    // endpoint: '...',          // S3-compatible endpoint
+  },
+
+  // Browser automation (requires @poncho-ai/browser)
+  // browser: true,
+  // browser: {
+  //   viewport: { width: 1280, height: 720 },
+  //   quality: 80,
+  //   everyNthFrame: 2,
+  //   headless: true,
+  //   profileDir: '~/.poncho/browser-profiles',
+  //   executablePath: '/path/to/chromium',
+  //   stealth: true,           // Anti-bot-detection (default: true)
+  //   userAgent: 'custom UA',  // Override the default stealth user-agent
+  // },
+
+  // Headless mode: disable the built-in Web UI (API-only)
+  // webUi: false,
+
+}
+\`\`\`
+
+\`provider: 'local'\` stores runtime state under \`~/.poncho/store\` (or \`/tmp/.poncho/store\` on serverless runtimes), scoped by both agent name and stable agent id:
+
+\`\`\`text
+~/.poncho/store
+\u2514\u2500\u2500 my-agent--agent_01f4f5d7e9c7432da51f8c6b9e2b1a0c
+    \u251C\u2500\u2500 memory.json
+    \u251C\u2500\u2500 state.json
+    \u251C\u2500\u2500 onboarding-state.json
+    \u2514\u2500\u2500 conversations
+        \u251C\u2500\u2500 index.json
+        \u251C\u2500\u2500 20260217T154233Z--conv_01j9x8a12bcd.json
+        \u2514\u2500\u2500 20260218T101004Z--conv_01j9x8b45efg.json
+\`\`\`
+
+Remote storage keys are namespaced and versioned, for example \`poncho:v1:<agentId>:...\`.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| \`ANTHROPIC_API_KEY\` | Yes* | Claude API key |
+| \`OPENAI_API_KEY\` | No | OpenAI API key (if using OpenAI) |
+| \`PONCHO_AUTH_TOKEN\` | No | Unified auth token (Web UI passphrase + API Bearer token) |
+| \`OTEL_EXPORTER_OTLP_ENDPOINT\` | No | Telemetry destination |
+| \`LATITUDE_API_KEY\` | No | Latitude dashboard integration |
+| \`LATITUDE_PROJECT_ID\` | No | Latitude project identifier for capture traces |
+| \`LATITUDE_PATH\` | No | Latitude prompt path for grouping traces |
+| \`KV_REST_API_URL\` | No | Upstash REST URL (Vercel Marketplace naming) |
+| \`KV_REST_API_TOKEN\` | No | Upstash REST write token (Vercel Marketplace naming) |
+| \`UPSTASH_REDIS_REST_URL\` | No | Upstash REST URL (direct Upstash naming) |
+| \`UPSTASH_REDIS_REST_TOKEN\` | No | Upstash REST write token (direct Upstash naming) |
+| \`REDIS_URL\` | No | For Redis state storage |
+| \`SLACK_BOT_TOKEN\` | No | Slack Bot Token (for messaging integration) |
+| \`SLACK_SIGNING_SECRET\` | No | Slack Signing Secret (for messaging integration) |
+| \`TELEGRAM_BOT_TOKEN\` | No | Telegram Bot Token (from @BotFather) |
+| \`TELEGRAM_WEBHOOK_SECRET\` | No | Telegram webhook secret token (optional) |
+| \`RESEND_API_KEY\` | No | Resend API key (for email messaging) |
+| \`RESEND_WEBHOOK_SECRET\` | No | Resend webhook signing secret |
+| \`RESEND_FROM\` | No | Sender address for email replies |
+| \`RESEND_REPLY_TO\` | No | Reply-to address for outgoing emails (optional) |
+| \`BLOB_READ_WRITE_TOKEN\` | No | Vercel Blob token (for \`uploads.provider: 'vercel-blob'\`) |
+| \`PONCHO_UPLOADS_BUCKET\` | No | S3 bucket name (for \`uploads.provider: 's3'\`) |
+
+*Required if using Anthropic models (default).
+
+## Observability
+
+### Local development
+
+Logs print to console:
+
+\`\`\`
+[event] run:started {"type":"run:started","runId":"run_abc123","agentId":"my-agent"}
+[event] tool:started {"type":"tool:started","tool":"read_file","input":{"path":"README.md"}}
+[event] tool:completed {"type":"tool:completed","tool":"read_file","duration":45,"output":{"path":"README.md","content":"..."}}
+[event] run:completed {"type":"run:completed","runId":"run_abc123","result":{"status":"completed","response":"...","steps":3,"tokens":{"input":1500,"output":840}}}
+\`\`\`
+
+### Production telemetry
+
+Send events to your observability stack:
+
+\`\`\`bash
+# Environment variable
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com
+\`\`\`
+
+Or configure in code:
+
+\`\`\`javascript
+// poncho.config.js
+export default {
+  telemetry: {
+    otlp: 'https://otel.example.com',
+    // Or custom handler
+    handler: async (event) => {
+      await sendToMyLoggingService(event)
+    }
+  }
+}
+\`\`\`
+
+### Latitude integration (optional)
+
+Send traces to [Latitude](https://latitude.so) for a dashboard with cost tracking and prompt management:
+
+\`\`\`bash
+LATITUDE_API_KEY=lat_xxx
+LATITUDE_PROJECT_ID=123
+LATITUDE_PATH=agents/my-agent/run
+\`\`\`
+
+Or configure via \`poncho.config.js\`:
+
+\`\`\`javascript
+telemetry: {
+  latitude: {
+    // apiKeyEnv: 'LATITUDE_API_KEY',       // default
+    // projectIdEnv: 'LATITUDE_PROJECT_ID', // default
+    path: 'your/prompt-path',
+  },
+}
+\`\`\`
+
+## Security
+
+### Protect your endpoint
+
+Enable authentication to secure both the Web UI and API:
+
+\`\`\`javascript
+// poncho.config.js
+export default {
+  auth: {
+    required: true,
+    type: 'bearer'  // Default: validates against PONCHO_AUTH_TOKEN
+  }
+}
+\`\`\`
+
+\`\`\`bash
+# .env
+PONCHO_AUTH_TOKEN=your-secret-token-here
+\`\`\`
+
+With \`auth.required: true\`:
+- **Web UI**: Users must enter \`PONCHO_AUTH_TOKEN\` as the passphrase to login
+- **API**: Clients must include \`Authorization: Bearer <PONCHO_AUTH_TOKEN>\` header
+
+For custom validation:
+
+\`\`\`javascript
+// poncho.config.js
+export default {
+  auth: {
+    required: true,
+    type: 'custom',
+    validate: async (token) => {
+      // Custom logic: check database, verify JWT, etc.
+      return token === process.env.PONCHO_AUTH_TOKEN
+    }
+  }
+}
+\`\`\`
+
+### Require approval for dangerous tools
+
+Use \`approval-required\` in your \`AGENT.md\` or \`SKILL.md\` frontmatter to gate specific tools:
+
+\`\`\`yaml
+---
+allowed-tools:
+  - mcp:linear/*
+approval-required:
+  - mcp:linear/list_initiatives
+---
+\`\`\`
+
+When a gated tool is called, the harness emits a \`tool:approval:required\` event and pauses until approval is granted or denied. In the web UI and interactive CLI, the user is prompted before execution continues.
+`,
+  "troubleshooting": `# Error Handling & Troubleshooting
+
+> Back to [README](../README.md)
+
+## Error Types
+
+These error codes appear in \`run:error\` SSE events:
+
+| Code | Description |
+|------|-------------|
+| \`MAX_STEPS_EXCEEDED\` | Agent hit the step limit without completing |
+| \`TIMEOUT\` | Agent exceeded the timeout |
+| \`MODEL_TIMEOUT\` | Model API call timed out |
+| \`MODEL_ERROR\` | Model API returned an error |
+| \`CONTENT_FILTER\` | Response blocked by the provider's content filter |
+| \`AUTH_ERROR\` | Authentication failed |
+
+## Tool Errors Are Recoverable
+
+When a tool fails, the error is sent back to the model via a \`tool:error\` event. The model can retry with different parameters, try a different tool, or ask the user for help:
+
+\`\`\`
+event: tool:error
+data: {"tool": "fetch-url", "error": "Connection timeout", "recoverable": true}
+
+event: model:chunk
+data: {"content": "I couldn't fetch that URL. Let me try a different approach..."}
+\`\`\`
+
+## Fatal Errors End the Run
+
+Timeout, max steps, or model API errors end the run immediately:
+
+\`\`\`
+event: run:error
+data: {"runId": "run_abc", "error": {"code": "TIMEOUT", "message": "Run exceeded 60 second timeout"}}
+\`\`\`
+
+## Handle Errors in Your Client
+
+\`\`\`typescript
+const agent = new AgentClient({ url: 'https://my-agent.vercel.app' })
+
+try {
+  const result = await agent.run({ task: 'Do something' })
+} catch (error) {
+  console.error('Agent run failed:', error.message)
+}
+\`\`\`
+
+## Troubleshooting
+
+### "ANTHROPIC_API_KEY not set"
+
+Make sure you have a \`.env\` file with your API key:
+
+\`\`\`bash
+echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
+\`\`\`
+
+### "MCP server failed to connect"
+
+Check that:
+1. A remote MCP server is configured (\`poncho mcp list\`)
+2. The MCP URL is correct and reachable (\`http://\` or \`https://\`)
+3. Required environment variables/secrets are set
+4. Any required auth headers/tokens expected by the remote server are configured
+
+### Agent keeps running forever
+
+Set execution limits:
+
+\`\`\`yaml
+---
+limits:
+  maxSteps: 20
+  timeout: 60  # 1 minute (in seconds)
+---
+\`\`\`
+
+### Vercel deploy issues
+
+- After upgrading \`@poncho-ai/cli\`, re-run \`poncho build vercel --force\` to refresh generated deploy files.
+- If Vercel fails during \`pnpm install\` due to a lockfile mismatch, run \`pnpm install --no-frozen-lockfile\` locally and commit \`pnpm-lock.yaml\`.
+- Deploy from the project root: \`vercel deploy --prod\`.
+`
+};
+
+// src/default-tools.ts
 var resolveSafePath = (workingDir, inputPath) => {
   const base = resolve4(workingDir);
   const target = resolve4(base, inputPath);
@@ -534,6 +1671,31 @@ var createDeleteDirectoryTool = (workingDir) => defineTool({
     return { path, deleted: true };
   }
 });
+var PONCHO_DOCS_TOPICS = Object.keys(PONCHO_DOCS);
+var ponchoDocsTool = defineTool({
+  name: "poncho_docs",
+  description: `Read detailed Poncho framework documentation by topic. Available topics: ${PONCHO_DOCS_TOPICS.join(", ")}.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      topic: {
+        type: "string",
+        enum: PONCHO_DOCS_TOPICS,
+        description: "Documentation topic to read"
+      }
+    },
+    required: ["topic"],
+    additionalProperties: false
+  },
+  handler: async (input) => {
+    const topic = typeof input.topic === "string" ? input.topic : "";
+    const content = PONCHO_DOCS[topic];
+    if (!content) {
+      return { error: `Unknown topic "${topic}". Available: ${PONCHO_DOCS_TOPICS.join(", ")}` };
+    }
+    return { topic, content };
+  }
+});
 
 // src/harness.ts
 import { randomUUID as randomUUID3 } from "crypto";
@@ -3141,7 +4303,15 @@ Since all fields have defaults, you only need to specify \`*Env\` when your env
 - If shell/CLI access is unavailable, ask the user to run needed commands and provide exact copy-paste commands.
 - For setup, skills, MCP, auth, storage, telemetry, or "how do I..." questions, proactively read \`README.md\` with \`read_file\` before answering.
 - Prefer quoting concrete commands and examples from \`README.md\` over guessing.
-- Keep edits minimal, preserve unrelated settings/code, and summarize what changed.`;
+- Keep edits minimal, preserve unrelated settings/code, and summarize what changed.
+
+## Detailed Documentation
+
+For topics not covered above, use the \`poncho_docs\` tool to load full documentation on demand:
+- \`api\` \u2014 HTTP API endpoints, SSE events, TypeScript client SDK, file attachments, upload providers
+- \`features\` \u2014 Web UI details, browser automation, subagents, persistent memory, custom messaging adapters
+- \`configuration\` \u2014 Full config reference, env vars, auth types, storage, telemetry, tool approval
+- \`troubleshooting\` \u2014 Error codes, recoverable vs fatal errors, common issues and fixes`;
 function extractMediaFromToolOutput(output) {
   const mediaItems = [];
   function walk(node) {
@@ -3251,6 +4421,9 @@ var AgentHarness = class {
     if (this.isToolEnabled("delete_directory")) {
       this.registerIfMissing(createDeleteDirectoryTool(this.workingDir));
     }
+    if (this.environment === "development" && this.isToolEnabled("poncho_docs")) {
+      this.registerIfMissing(ponchoDocsTool);
+    }
   }
   shouldEnableWriteTool() {
     const override = process.env.PONCHO_FS_WRITE?.toLowerCase();
@@ -5867,6 +7040,7 @@ export {
   normalizeScriptPolicyPath,
   parseAgentFile,
   parseAgentMarkdown,
+  ponchoDocsTool,
   readSkillResource,
   renderAgentPrompt,
   resolveAgentIdentity,