[G6] New page: Cloudflare Workers, with the limits stated first

[LinuxDevil]

Goal

The Cloudflare Worker target has the tightest limits of the three deploy targets (three provider types, two tools, spec files only, KV stores), and they are buried 130 lines into the cloudflare-worker section of docs/deployment.md, among bindings, KV key tables, cron and consistency notes. A reader choosing a target should see "what works here" first. Give the target its own page with a table of limits at the top, and make deployment.md link to it. Audit 2 section 4, "Missing guides"; plan row G6.

Current state

Checked on main at cc5ddb8.

• docs/deployment.md (327 lines): ## \cloudflare-worker`starts at line 132 and holds### Bindings, sessions and the API on Workers(176),### Optional peers in node and docker builds(227; not Worker-specific),### Cron triggers and `handleScheduled`(236),### Durable execution (pause/resume) on Workers(265, including KV consistency and the bundle-size paragraph), then## Custom targets(323). The limits are in a bullet list at lines 151-166: providersmock, openai, anthropiconly;ollamaandopenrouterunsupported; toolscurrent-dateandday-nameonly,httpunsupported (SSRF protection needsnode:dnsand a pinned connection);lousho build` rejects anything else.
• Source of those limits: src/deploy/adapters/cloudflare.ts:41 (WORKER_SUPPORTED_TOOLS = ['current-date', 'day-name']), :52 (WORKER_SUPPORTED_PROVIDERS = ['mock', 'openai', 'anthropic']), :264-286 (assertProviderSupported, assertToolsSupported, both LOUSHO_DEPLOY_FAILED with "Use --target=node-server or --target=docker"), the generated Worker runtime in src/deploy/ (runtime.worker.ts, shims/). docs/deployment.md:46-47 says "The Cloudflare Worker target still takes spec files only" (agent directories work for node-server and docker).
• Other Worker limits stated in the same section: sandboxed tool execution is not supported (src/deploy/shims/sandboxCore.worker.ts:17); stdio MCP and the file session store are replaced by shims that fail when used (docs/deployment.md near line 313); KV is eventually consistent (the caveat at 285-300); cron is UTC, five fields, one-minute granularity (LOUSHO_SCHEDULE_INVALID); KVStore is not exported from any entry point (docs/deployment.md:206-208, grepped in src/index.ts and package.json exports: not found; the plan's wave-0 ticket R2 adds a ./kv export).
• Inbound links to anchors in this section (grepped docs/, README.md, src/, apps/agent-forge/src, examples/, packages/): docs/providers.md:228 (deployment.md#cloudflare-worker), docs/schedules.md:122 (deployment.md#cron-triggers-and-handlescheduled). docs/errors.md mentions the target in its codes (LOUSHO_DEPLOY_FAILED, line 609) without anchors.
• docs/providers.md section ## Where each provider runs (line 224) repeats the provider limits.
• Two wave-2 and wave-0 tickets will change what is true here: R2 (exports the KV store) and M3 (agent directories, TypeScript tools, OpenRouter and the http tool on Workers). This ticket documents the state of main when it is written; the limits table is the one place M3 will edit.

Scope

In: a new page docs/cloudflare-workers.md titled # Cloudflare Workers with this outline (decided):

1. Intro, three sentences: what --target=cloudflare-worker generates (a module Worker, wrangler.toml, dist/worker.js checked for node: imports), that it needs tsup and wrangler, and the command (npx lousho build --target=cloudflare-worker --agent=agent.yaml).
2. ## What works and what does not: a table with columns Feature, Worker, node-server / docker: spec files (yes, yes); agent directories (no, yes); providers (mock, openai, anthropic / all); built-in tools (current-date, day-name / all, including http); tools written in TypeScript (no; spec files cannot hold code); sandboxed tool execution (no / yes); MCP servers (stdio MCP is shimmed to fail on Workers per docs/deployment.md near line 313; confirm in src/deploy/shims/node.worker.ts whether HTTP servers work, and write only what you confirm); sessions, checkpoints, approvals (KV / file or SQLite); schedules (cron triggers only, UTC / full cron with timezone); bundle (check size). Verify every cell against the source file named above; a cell you cannot confirm says "not verified" and the pull request lists it.
3. ## Build and deploy: the commands from deployment.md (wrangler dev, wrangler secret put, wrangler deploy), the ai version note (builds with ai v4 or v7 and the matching @ai-sdk/*, no nodejs_compat), and the <TYPE>_API_KEY bindings.
4. ## Bindings: the LOUSHO_API_TOKEN and AGENT_CHECKPOINTS table, the wrangler.toml KV block, the curl example. Move from deployment.md.
5. ## Sessions, checkpoints and approvals: the KV key table, ttl, approvals decided on another isolate, the deprecated { "message" } body. Move.
6. ## Scheduled runs: the cron-triggers text and the handleScheduled snippet. Move (heading becomes ## Scheduled runs).
7. ## Consistency: the eventual-consistency caveat and why KV rather than D1 or Durable Objects. Move, unchanged.
8. ## Bundle size and Node builtins: the node: check, the four allowed getBuiltinModule ids and the size figures. Move, unchanged.

• In docs/deployment.md: keep ## \cloudflare-worker`with a short summary (the three sentences of the intro and the limits as a three-line list) and a link to the new page; delete the moved subsections### Bindings, sessions and the API on Workers, ### Cron triggers and handleScheduled, ### Durable execution (pause/resume) on Workers. Keep ### Optional peers in node and docker builds` where it is (it is not Worker-specific).
• Repoint docs/providers.md:228 to ./cloudflare-workers.md and docs/schedules.md:122 to ./cloudflare-workers.md#scheduled-runs.
• README docs table: add a Cloudflare Workers row (or extend the Deployment row with a link).
• CHANGELOG entry under ## [Unreleased] (docs). Run npm run docs:llms.
  Out: changing the Worker target (M3, R2); exporting KVStore (R2); the docs-site and Arabic work (G9).

Acceptance criteria

• docs/cloudflare-workers.md exists with the outline above; every TypeScript snippet passes npm run docs:verify-snippets -- --skip-build.
• The "what works" table is the first content after the intro, and every cell is checked against the source (list the checked source lines in the pull request).
• docs/deployment.md no longer contains the three moved subsections; its summary links to the new page; grep -rn "deployment.md#cron-triggers-and-handlescheduled" docs finds nothing.
• npx vitest run docs/docs-links.test.ts and npm run docs:llms:check pass; CHANGELOG entry added.
• For G9 (list in the pull request description): cloudflare-workers is a new page (needs a PAGES entry in scripts/sync-sdk-docs.mjs, a navigation entry in docs.json for both languages, and an Arabic translation); deployment is restructured (three headings removed), so its Arabic page needs a full re-sync; the Arabic text of the moved sections can be moved into the new page.

Live test

None: this ticket spends nothing.

Dependencies

None. Conflicts: R2 (wave 0) edits docs/deployment.md around the KVStore paragraph (lines 206-208, 265-320): if R2 has merged, keep its wording in the moved text; M3 (wave 2) later edits the new page's table. README docs table (G1, G3, G4a, G4b, G4c, G5a, G5b).

Notes for the implementer

• Move text; do not rewrite it, except the intro and the table. The consistency paragraph and the node: check paragraph are carefully worded.
• Do not claim that openrouter or the http tool will be supported; say what is true today.
• Do not edit docs/providers.md beyond the one link (G8 owns that page's stale statements).
• No ticket ids (LOU-...) in the text you write.

---

Round 2 ticket G6. Before starting, read the agent brief (worktree rules, verification list, live-test budget) and the plan. One ticket is one pull request; put Closes #<this issue> in it.

[LinuxDevil]

Starting G6 (Cloudflare Workers page) plus #288 link fixes and fileStore in approvals.md. Model: Claude Sonnet 5.5, 2026-10-02.