{"owner":"cloudflare","repo":"agents","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n## Project overview\n\nCloudflare Agents SDK — a framework for building stateful AI agents on Cloudflare Workers. This is a monorepo containing the core SDK packages, examples, guides, sites, and documentation.\n\n## Repository structure\n\n```\npackages/          # Published npm packages (need changesets for changes)\n  agents/          # Core SDK (see packages/agents/AGENTS.md)\n  ai-chat/         # @cloudflare/ai-chat — higher-level AI chat agent\n  hono-agents/     # Hono framework integration\n  codemode/        # @cloudflare/codemode — experimental code generation\n\nexamples/          # Self-contained demo apps (see examples/AGENTS.md)\n  playground/      # Main showcase app — all SDK features in one UI (uses Kumo design system)\n  mcp/             # MCP server example\n  mcp-client/      # MCP client example\n  ...              # ~20 examples total\n\nexperimental/      # Work-in-progress experiments (not published, no stability guarantees)\n\nsite/              # Deployed websites\n  agents/          # agents.cloudflare.com (Astro)\n  ai-playground/   # Workers AI playground (React + Vite)\n\nguides/            # In-depth pattern tutorials with narrative READMEs (see guides/AGENTS.md)\n  anthropic-patterns/\n  human-in-the-loop/\n\nopenai-sdk/        # Examples using @openai/agents SDK\n  basic/ chess-app/ handoffs/ human-in-the-loop/ ...\n\ndocs/              # Markdown docs for developers.cloudflare.com (see docs/AGENTS.md)\ndesign/            # Architecture and design decision records (see design/AGENTS.md)\nscripts/           # Repo-wide tooling (typecheck, export checks, update checks)\n```\n\n## Nested AGENTS.md files\n\nSome directories have their own AGENTS.md with deeper guidance:\n\n| File                        | Scope                                                                     |\n| --------------------------- | ------------------------------------------------------------------------- |\n| `packages/agents/AGENTS.md` | Core SDK internals — exports, source layout, build, testing, architecture |\n| `examples/AGENTS.md`        | Example conventions — required structure, consistency rules, known issues |\n| `guides/AGENTS.md`          | Guide conventions — how guides differ from examples, README expectations  |\n| `docs/AGENTS.md`            | Writing user-facing docs — Diátaxis framework, upstream sync, style       |\n| `design/AGENTS.md`          | Design records and RFCs — format, workflow, relationship to docs          |\n\n## Setup\n\n```bash\npnpm install       # installs all workspaces\n```\n\nNode 24+ required. Uses pnpm workspaces with [Nx](https://nx.dev) for task orchestration, caching, and affected detection.\n\n## Commands\n\nRun from the repo root:\n\n| Command                            | What it does                                                       |\n| ---------------------------------- | ------------------------------------------------------------------ |\n| `pnpm run build`                   | Builds all packages via Nx (cached, dependency-ordered)            |\n| `pnpm run check`                   | Full CI check: sherif + export checks + oxfmt + oxlint + typecheck |\n| `pnpm run test`                    | Runs all tests via Nx (cached)                                     |\n| `pnpm run test:react`              | Runs Playwright-based React hook tests for agents                  |\n| `pnpm run typecheck`               | TypeScript type checking across the repo (custom script)           |\n| `pnpm run format`                  | Oxfmt format all files                                             |\n| `pnpm run check:exports`           | Verifies package.json exports match actual build output            |\n| `pnpm exec nx affected -t build`   | Build only packages affected by current changes                    |\n| `pnpm exec nx affected -t test`    | Test only packages affected by current changes                     |\n| `pnpm exec nx run <project>:build` | Build a single project (and its dependencies)                      |\n\nRun an example locally:\n\n```bash\ncd examples/playground   # or any example\npnpm dev                 # starts Vite dev server + Workers runtime via @cloudflare/vite-plugin\n```\n\nExample apps will normally hot reload when the dev server is running. When the dev server is running, make sure to rebuild changed packages (`pnpm run build`) to see changes reflected in the running app.\n\n## Code standards\n\n### TypeScript\n\n- Strict mode enabled (`agents/tsconfig`)\n- Target: ES2021, module: ES2022, moduleResolution: bundler\n- `verbatimModuleSyntax: true` — use explicit `import type` for type-only imports\n- JSX: `react-jsx`\n\n### Linting — Oxlint\n\nConfig in `.oxlintrc.json`. Plugins: `react`, `jsx-a11y`, `typescript`, `react-hooks`. Key rules:\n\n- `no-explicit-any: \"error\"` — never use `any`, use `unknown` and narrow\n- `no-unused-vars: \"error\"` — with `varsIgnorePattern: \"^_\"` and `argsIgnorePattern: \"^_\"`\n- `correctness` category set to `\"error\"` — catches common mistakes\n- `jsx-a11y` rules enabled — accessibility violations are errors\n- `react-hooks/exhaustive-deps: \"warn\"` — warns on missing hook dependencies\n\nOxlint does **not** handle formatting — Oxfmt does.\n\n### Formatting — Oxfmt\n\n- Run `pnpm run format` to format all files\n- Config in `.oxfmtrc.json` (`trailingComma: \"none\"`, `printWidth: 80`)\n\n### Workers conventions\n\n- Always TypeScript, always ES modules\n- `wrangler.jsonc` (not `.toml`) for configuration\n- All wrangler configs use `compatibility_date: \"2026-06-11\"` and `compatibility_flags: [\"nodejs_compat\"]`\n- Never hardcode secrets — use `wrangler secret put` or `.env`\n- No native/FFI dependencies (must run in Workers runtime)\n\n## Testing\n\nTests use **vitest** with `@cloudflare/vitest-pool-workers` for running inside the Workers runtime.\n\n```bash\npnpm run test             # agents + ai-chat unit/integration tests\npnpm run test:react       # Playwright-based React hook tests (agents package)\n```\n\nTest locations:\n\n- `packages/agents/src/tests/` — core SDK tests\n- `packages/agents/src/react-tests/` — React hook tests (Playwright + vitest-browser-react)\n- `packages/ai-chat/src/tests/` — AI chat tests\n- `packages/agents/src/tests-d/` — type-level tests (`.test-d.ts`)\n\nEach test directory has its own `vitest.config.ts` and (for Workers tests) a `wrangler.jsonc`.\n\nFor a repo-wide rollup of **what proves feature X works, at which layer, and which CI run guards it** — plus the tracked skip/quarantine debt — see [`design/test-coverage-matrix.md`](design/test-coverage-matrix.md).\n\n## Contributing\n\n### Changesets\n\nChanges to `packages/` that affect the public API or fix bugs need a changeset:\n\n```bash\npnpm exec changeset       # interactive prompt — pick packages, semver bump, description\n```\n\nThis creates a markdown file in `.changeset/` that gets consumed during release.\n\nExamples, guides, and sites don't need changesets.\n\n### Pull request process\n\nCI runs on every PR (`pnpm install --frozen-lockfile && pnpm run build && pnpm run check && pnpm exec nx affected -t test`); the workflow is in `.github/workflows/pullrequest.yml`. On push to `main` the Release workflow (`.github/workflows/release.yml`) runs the same steps but uses `nx run-many -t test` as a safety net against under-reported affected projects, then publishes via changesets. All checks must pass.\n\n### Generated files\n\n- `env.d.ts` files are generated by `wrangler types` — regenerate with `pnpm exec wrangler types` inside the relevant example/package, don't hand-edit\n- `pnpm-lock.yaml` — regenerated by `pnpm install`, don't hand-edit\n\n## Learned Workspace Facts\n\n- `packages/shell/` is published as `@cloudflare/shell` — an experimental sandboxed JS execution and filesystem runtime for agents, built on the same dynamic Worker loader machinery as `@cloudflare/codemode`.\n- To run code against a `Workspace`: import `stateTools` from `@cloudflare/shell/workers` and `DynamicWorkerExecutor`/`resolveProvider` from `@cloudflare/codemode`; use `executor.execute(code, [resolveProvider(stateTools(workspace))])`.\n\n## Learned User Preferences\n\n- Keep `Workspace` as a pure durable filesystem — do not embed execution or session logic inside it. Execution is a caller concern wired via `@cloudflare/codemode` + `stateTools`.\n- When a package boundary feels wrong (e.g., a helper package depending on a larger package just for an adapter), prefer moving the adapter out rather than carrying the dependency.\n\n## Boundaries\n\n**Always:**\n\n- Run `pnpm run check` before considering work done\n- Use `import type` for type-only imports (enforced by `verbatimModuleSyntax`)\n- Keep examples simple and self-contained — they're user-facing learning material\n- Use Cloudflare Workers APIs (KV, D1, R2, Durable Objects, etc.) over third-party equivalents\n- Use Workers AI for LLM calls in examples — not third-party APIs like OpenAI or Anthropic\n\n**Ask first:**\n\n- Adding new dependencies to `packages/` (these ship to users)\n- Changing `wrangler.jsonc` compatibility dates across the repo\n- Modifying CI workflows\n\n**Never:**\n\n- Hardcode secrets or API keys\n- Add native/FFI/C-binding dependencies\n- Use `any` — Oxlint will reject it\n- Use CommonJS or Service Worker format — ES modules only\n- Modify `node_modules/` or `dist/` directories\n- Force push to main\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n## Project overview\n\nCloudflare Agents SDK — a framework for building stateful AI agents on Cloudflare Workers. This is a monorepo containing the core SDK packages, examples, guides, sites, and documentation.\n\n## Repository structure\n\n```\npackages/          # Published npm packages (need changesets for changes)\n  agents/          # Core SDK (see packages/agents/AGENTS.md)\n  ai-chat/         # @cloudflare/ai-chat — higher-level AI chat agent\n  hono-agents/     # Hono framework integration\n  codemode/        # @cloudflare/codemode — experimental code generation\n\nexamples/          # Self-contained demo apps (see examples/AGENTS.md)\n  playground/      # Main showcase app — all SDK features in one UI (uses Kumo design system)\n  mcp/             # MCP server example\n  mcp-client/      # MCP client example\n  ...              # ~20 examples total\n\nexperimental/      # Work-in-progress experiments (not published, no stability guarantees)\n\nsite/              # Deployed websites\n  agents/          # agents.cloudflare.com (Astro)\n  ai-playground/   # Workers AI playground (React + Vite)\n\nguides/            # In-depth pattern tutorials with narrative READMEs (see guides/AGENTS.md)\n  anthropic-patterns/\n  human-in-the-loop/\n\nopenai-sdk/        # Examples using @openai/agents SDK\n  basic/ chess-app/ handoffs/ human-in-the-loop/ ...\n\ndocs/              # Markdown docs for developers.cloudflare.com (see docs/AGENTS.md)\ndesign/            # Architecture and design decision records (see design/AGENTS.md)\nscripts/           # Repo-wide tooling (typecheck, export checks, update checks)\n```\n\n## Nested AGENTS.md files\n\nSome directories have their own AGENTS.md with deeper guidance:\n\n| File                        | Scope                                                                     |\n| --------------------------- | ------------------------------------------------------------------------- |\n| `packages/agents/AGENTS.md` | Core SDK internals — exports, source layout, build, testing, architecture |\n| `examples/AGENTS.md`        | Example conventions — required structure, consistency rules, known issues |\n| `guides/AGENTS.md`          | Guide conventions — how guides differ from examples, README expectations  |\n| `docs/AGENTS.md`            | Writing user-facing docs — Diátaxis framework, upstream sync, style       |\n| `design/AGENTS.md`          | Design records and RFCs — format, workflow, relationship to docs          |\n\n## Setup\n\n```bash\npnpm install       # installs all workspaces\n```\n\nNode 24+ required. Uses pnpm workspaces with [Nx](https://nx.dev) for task orchestration, caching, and affected detection.\n\n## Commands\n\nRun from the repo root:\n\n| Command                            | What it does                                                       |\n| ---------------------------------- | ------------------------------------------------------------------ |\n| `pnpm run build`                   | Builds all packages via Nx (cached, dependency-ordered)            |\n| `pnpm run check`                   | Full CI check: sherif + export checks + oxfmt + oxlint + typecheck |\n| `pnpm run test`                    | Runs all tests via Nx (cached)                                     |\n| `pnpm run test:react`              | Runs Playwright-based React hook tests for agents                  |\n| `pnpm run typecheck`               | TypeScript type checking across the repo (custom script)           |\n| `pnpm run format`                  | Oxfmt format all files                                             |\n| `pnpm run check:exports`           | Verifies package.json exports match actual build output            |\n| `pnpm exec nx affected -t build`   | Build only packages affected by current changes                    |\n| `pnpm exec nx affected -t test`    | Test only packages affected by current changes                     |\n| `pnpm exec nx run <project>:build` | Build a single project (and its dependencies)                      |\n\nRun an example locally:\n\n```bash\ncd examples/playground   # or any example\npnpm dev                 # starts Vite dev server + Workers runtime via @cloudflare/vite-plugin\n```\n\nExample apps will normally hot reload when the dev server is running. When the dev server is running, make sure to rebuild changed packages (`pnpm run build`) to see changes reflected in the running app.\n\n## Code standards\n\n### TypeScript\n\n- Strict mode enabled (`agents/tsconfig`)\n- Target: ES2021, module: ES2022, moduleResolution: bundler\n- `verbatimModuleSyntax: true` — use explicit `import type` for type-only imports\n- JSX: `react-jsx`\n\n### Linting — Oxlint\n\nConfig in `.oxlintrc.json`. Plugins: `react`, `jsx-a11y`, `typescript`, `react-hooks`. Key rules:\n\n- `no-explicit-any: \"error\"` — never use `any`, use `unknown` and narrow\n- `no-unused-vars: \"error\"` — with `varsIgnorePattern: \"^_\"` and `argsIgnorePattern: \"^_\"`\n- `correctness` category set to `\"error\"` — catches common mistakes\n- `jsx-a11y` rules enabled — accessibility violations are errors\n- `react-hooks/exhaustive-deps: \"warn\"` — warns on missing hook dependencies\n\nOxlint does **not** handle formatting — Oxfmt does.\n\n### Formatting — Oxfmt\n\n- Run `pnpm run format` to format all files\n- Config in `.oxfmtrc.json` (`trailingComma: \"none\"`, `printWidth: 80`)\n\n### Workers conventions\n\n- Always TypeScript, always ES modules\n- `wrangler.jsonc` (not `.toml`) for configuration\n- All wrangler configs use `compatibility_date: \"2026-06-11\"` and `compatibility_flags: [\"nodejs_compat\"]`\n- Never hardcode secrets — use `wrangler secret put` or `.env`\n- No native/FFI dependencies (must run in Workers runtime)\n\n## Testing\n\nTests use **vitest** with `@cloudflare/vitest-pool-workers` for running inside the Workers runtime.\n\n```bash\npnpm run test             # agents + ai-chat unit/integration tests\npnpm run test:react       # Playwright-based React hook tests (agents package)\n```\n\nTest locations:\n\n- `packages/agents/src/tests/` — core SDK tests\n- `packages/agents/src/react-tests/` — React hook tests (Playwright + vitest-browser-react)\n- `packages/ai-chat/src/tests/` — AI chat tests\n- `packages/agents/src/tests-d/` — type-level tests (`.test-d.ts`)\n\nEach test directory has its own `vitest.config.ts` and (for Workers tests) a `wrangler.jsonc`.\n\nFor a repo-wide rollup of **what proves feature X works, at which layer, and which CI run guards it** — plus the tracked skip/quarantine debt — see [`design/test-coverage-matrix.md`](design/test-coverage-matrix.md).\n\n## Contributing\n\n### Changesets\n\nChanges to `packages/` that affect the public API or fix bugs need a changeset:\n\n```bash\npnpm exec changeset       # interactive prompt — pick packages, semver bump, description\n```\n\nThis creates a markdown file in `.changeset/` that gets consumed during release.\n\nExamples, guides, and sites don't need changesets.\n\n### Pull request process\n\nCI runs on every PR (`pnpm install --frozen-lockfile && pnpm run build && pnpm run check && pnpm exec nx affected -t test`); the workflow is in `.github/workflows/pullrequest.yml`. On push to `main` the Release workflow (`.github/workflows/release.yml`) runs the same steps but uses `nx run-many -t test` as a safety net against under-reported affected projects, then publishes via changesets. All checks must pass.\n\n### Generated files\n\n- `env.d.ts` files are generated by `wrangler types` — regenerate with `pnpm exec wrangler types` inside the relevant example/package, don't hand-edit\n- `pnpm-lock.yaml` — regenerated by `pnpm install`, don't hand-edit\n\n## Learned Workspace Facts\n\n- `packages/shell/` is published as `@cloudflare/shell` — an experimental sandboxed JS execution and filesystem runtime for agents, built on the same dynamic Worker loader machinery as `@cloudflare/codemode`.\n- To run code against a `Workspace`: import `stateTools` from `@cloudflare/shell/workers` and `DynamicWorkerExecutor`/`resolveProvider` from `@cloudflare/codemode`; use `executor.execute(code, [resolveProvider(stateTools(workspace))])`.\n\n## Learned User Preferences\n\n- Keep `Workspace` as a pure durable filesystem — do not embed execution or session logic inside it. Execution is a caller concern wired via `@cloudflare/codemode` + `stateTools`.\n- When a package boundary feels wrong (e.g., a helper package depending on a larger package just for an adapter), prefer moving the adapter out rather than carrying the dependency.\n\n## Boundaries\n\n**Always:**\n\n- Run `pnpm run check` before considering work done\n- Use `import type` for type-only imports (enforced by `verbatimModuleSyntax`)\n- Keep examples simple and self-contained — they're user-facing learning material\n- Use Cloudflare Workers APIs (KV, D1, R2, Durable Objects, etc.) over third-party equivalents\n- Use Workers AI for LLM calls in examples — not third-party APIs like OpenAI or Anthropic\n\n**Ask first:**\n\n- Adding new dependencies to `packages/` (these ship to users)\n- Changing `wrangler.jsonc` compatibility dates across the repo\n- Modifying CI workflows\n\n**Never:**\n\n- Hardcode secrets or API keys\n- Add native/FFI/C-binding dependencies\n- Use `any` — Oxlint will reject it\n- Use CommonJS or Service Worker format — ES modules only\n- Modify `node_modules/` or `dist/` directories\n- Force push to main\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n## Project overview\n\nCloudflare Agents SDK — a framework for building stateful AI agents on Cloudflare Workers. This is a monorepo containing the core SDK packages, examples, guides, sites, and documentation.\n\n## Repository structure\n\n```\npackages/          # Published npm packages (need changesets for changes)\n  agents/          # Core SDK (see packages/agents/AGENTS.md)\n  ai-chat/         # @cloudflare/ai-chat — higher-level AI chat agent\n  hono-agents/     # Hono framework integration\n  codemode/        # @cloudflare/codemode — experimental code generation\n\nexamples/          # Self-contained demo apps (see examples/AGENTS.md)\n  playground/      # Main showcase app — all SDK features in one UI (uses Kumo design system)\n  mcp/             # MCP server example\n  mcp-client/      # MCP client example\n  ...              # ~20 examples total\n\nexperimental/      # Work-in-progress experiments (not published, no stability guarantees)\n\nsite/              # Deployed websites\n  agents/          # agents.cloudflare.com (Astro)\n  ai-playground/   # Workers AI playground (React + Vite)\n\nguides/            # In-depth pattern tutorials with narrative READMEs (see guides/AGENTS.md)\n  anthropic-patterns/\n  human-in-the-loop/\n\nopenai-sdk/        # Examples using @openai/agents SDK\n  basic/ chess-app/ handoffs/ human-in-the-loop/ ...\n\ndocs/              # Markdown docs for developers.cloudflare.com (see docs/AGENTS.md)\ndesign/            # Architecture and design decision records (see design/AGENTS.md)\nscripts/           # Repo-wide tooling (typecheck, export checks, update checks)\n```\n\n## Nested AGENTS.md files\n\nSome directories have their own AGENTS.md with deeper guidance:\n\n| File                        | Scope                                                                     |\n| --------------------------- | ------------------------------------------------------------------------- |\n| `packages/agents/AGENTS.md` | Core SDK internals — exports, source layout, build, testing, architecture |\n| `examples/AGENTS.md`        | Example conventions — required structure, consistency rules, known issues |\n| `guides/AGENTS.md`          | Guide conventions — how guides differ from examples, README expectations  |\n| `docs/AGENTS.md`            | Writing user-facing docs — Diátaxis framework, upstream sync, style       |\n| `design/AGENTS.md`          | Design records and RFCs — format, workflow, relationship to docs          |\n\n## Setup\n\n```bash\npnpm install       # installs all workspaces\n```\n\nNode 24+ required. Uses pnpm workspaces with [Nx](https://nx.dev) for task orchestration, caching, and affected detection.\n\n## Commands\n\nRun from the repo root:\n\n| Command                            | What it does                                                       |\n| ---------------------------------- | ------------------------------------------------------------------ |\n| `pnpm run build`                   | Builds all packages via Nx (cached, dependency-ordered)            |\n| `pnpm run check`                   | Full CI check: sherif + export checks + oxfmt + oxlint + typecheck |\n| `pnpm run test`                    | Runs all tests via Nx (cached)                                     |\n| `pnpm run test:react`              | Runs Playwright-based React hook tests for agents                  |\n| `pnpm run typecheck`               | TypeScript type checking across the repo (custom script)           |\n| `pnpm run format`                  | Oxfmt format all files                                             |\n| `pnpm run check:exports`           | Verifies package.json exports match actual build output            |\n| `pnpm exec nx affected -t build`   | Build only packages affected by current changes                    |\n| `pnpm exec nx affected -t test`    | Test only packages affected by current changes                     |\n| `pnpm exec nx run <project>:build` | Build a single project (and its dependencies)                      |\n\nRun an example locally:\n\n```bash\ncd examples/playground   # or any example\npnpm dev                 # starts Vite dev server + Workers runtime via @cloudflare/vite-plugin\n```\n\nExample apps will normally hot reload when the dev server is running. When the dev server is running, make sure to rebuild changed packages (`pnpm run build`) to see changes reflected in the running app.\n\n## Code standards\n\n### TypeScript\n\n- Strict mode enabled (`agents/tsconfig`)\n- Target: ES2021, module: ES2022, moduleResolution: bundler\n- `verbatimModuleSyntax: true` — use explicit `import type` for type-only imports\n- JSX: `react-jsx`\n\n### Linting — Oxlint\n\nConfig in `.oxlintrc.json`. Plugins: `react`, `jsx-a11y`, `typescript`, `react-hooks`. Key rules:\n\n- `no-explicit-any: \"error\"` — never use `any`, use `unknown` and narrow\n- `no-unused-vars: \"error\"` — with `varsIgnorePattern: \"^_\"` and `argsIgnorePattern: \"^_\"`\n- `correctness` category set to `\"error\"` — catches common mistakes\n- `jsx-a11y` rules enabled — accessibility violations are errors\n- `react-hooks/exhaustive-deps: \"warn\"` — warns on missing hook dependencies\n\nOxlint does **not** handle formatting — Oxfmt does.\n\n### Formatting — Oxfmt\n\n- Run `pnpm run format` to format all files\n- Config in `.oxfmtrc.json` (`trailingComma: \"none\"`, `printWidth: 80`)\n\n### Workers conventions\n\n- Always TypeScript, always ES modules\n- `wrangler.jsonc` (not `.toml`) for configuration\n- All wrangler configs use `compatibility_date: \"2026-06-11\"` and `compatibility_flags: [\"nodejs_compat\"]`\n- Never hardcode secrets — use `wrangler secret put` or `.env`\n- No native/FFI dependencies (must run in Workers runtime)\n\n## Testing\n\nTests use **vitest** with `@cloudflare/vitest-pool-workers` for running inside the Workers runtime.\n\n```bash\npnpm run test             # agents + ai-chat unit/integration tests\npnpm run test:react       # Playwright-based React hook tests (agents package)\n```\n\nTest locations:\n\n- `packages/agents/src/tests/` — core SDK tests\n- `packages/agents/src/react-tests/` — React hook tests (Playwright + vitest-browser-react)\n- `packages/ai-chat/src/tests/` — AI chat tests\n- `packages/agents/src/tests-d/` — type-level tests (`.test-d.ts`)\n\nEach test directory has its own `vitest.config.ts` and (for Workers tests) a `wrangler.jsonc`.\n\nFor a repo-wide rollup of **what proves feature X works, at which layer, and which CI run guards it** — plus the tracked skip/quarantine debt — see [`design/test-coverage-matrix.md`](design/test-coverage-matrix.md).\n\n## Contributing\n\n### Changesets\n\nChanges to `packages/` that affect the public API or fix bugs need a changeset:\n\n```bash\npnpm exec changeset       # interactive prompt — pick packages, semver bump, description\n```\n\nThis creates a markdown file in `.changeset/` that gets consumed during release.\n\nExamples, guides, and sites don't need changesets.\n\n### Pull request process\n\nCI runs on every PR (`pnpm install --frozen-lockfile && pnpm run build && pnpm run check && pnpm exec nx affected -t test`); the workflow is in `.github/workflows/pullrequest.yml`. On push to `main` the Release workflow (`.github/workflows/release.yml`) runs the same steps but uses `nx run-many -t test` as a safety net against under-reported affected projects, then publishes via changesets. All checks must pass.\n\n### Generated files\n\n- `env.d.ts` files are generated by `wrangler types` — regenerate with `pnpm exec wrangler types` inside the relevant example/package, don't hand-edit\n- `pnpm-lock.yaml` — regenerated by `pnpm install`, don't hand-edit\n\n## Learned Workspace Facts\n\n- `packages/shell/` is published as `@cloudflare/shell` — an experimental sandboxed JS execution and filesystem runtime for agents, built on the same dynamic Worker loader machinery as `@cloudflare/codemode`.\n- To run code against a `Workspace`: import `stateTools` from `@cloudflare/shell/workers` and `DynamicWorkerExecutor`/`resolveProvider` from `@cloudflare/codemode`; use `executor.execute(code, [resolveProvider(stateTools(workspace))])`.\n\n## Learned User Preferences\n\n- Keep `Workspace` as a pure durable filesystem — do not embed execution or session logic inside it. Execution is a caller concern wired via `@cloudflare/codemode` + `stateTools`.\n- When a package boundary feels wrong (e.g., a helper package depending on a larger package just for an adapter), prefer moving the adapter out rather than carrying the dependency.\n\n## Boundaries\n\n**Always:**\n\n- Run `pnpm run check` before considering work done\n- Use `import type` for type-only imports (enforced by `verbatimModuleSyntax`)\n- Keep examples simple and self-contained — they're user-facing learning material\n- Use Cloudflare Workers APIs (KV, D1, R2, Durable Objects, etc.) over third-party equivalents\n- Use Workers AI for LLM calls in examples — not third-party APIs like OpenAI or Anthropic\n\n**Ask first:**\n\n- Adding new dependencies to `packages/` (these ship to users)\n- Changing `wrangler.jsonc` compatibility dates across the repo\n- Modifying CI workflows\n\n**Never:**\n\n- Hardcode secrets or API keys\n- Add native/FFI/C-binding dependencies\n- Use `any` — Oxlint will reject it\n- Use CommonJS or Service Worker format — ES modules only\n- Modify `node_modules/` or `dist/` directories\n- Force push to main\n","category":"root","tokens":2311}]}