{"owner":"cloudflare","repo":"vibesdk","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n## Tooling\n- Use Bun from the repository root. The tracked lockfile is `bun.lock`, the `space` workspace dependency uses `workspace:*`, and install/build hooks invoke Bun even when started through npm.\n- `bun run setup` is the interactive Cloudflare/resource bootstrap. Local development expects the generated `.dev.vars`; never commit `.dev.vars*` or `.prod.vars`.\n- `bun run dev` starts the React frontend and Worker together through `@cloudflare/vite-plugin` at `http://localhost:5173`. There is no separate Worker dev command.\n- `bun run dev:browser` is an optional local Chromium sidecar for the think agent's browser-console tool; absence only produces a warning.\n\n## Verification\n- Root checks: `bun run typecheck`, `bun run lint`, `bun run test`, `bun run build`.\n- `bun run build` builds `space` and the Vite/Worker bundle; it does not typecheck. Run `bun run typecheck` separately.\n- Focus a root test with `bunx vitest run path/to/file.test.ts`; test execution uses the Workers pool and `wrangler.test.jsonc`.\n- The root Vitest suite excludes all `sdk/test/**` and `container/monitor-cli.test.ts`. SDK tests use Bun: `bun run --cwd sdk test`.\n- SDK integration tests require a running root dev server and `VIBESDK_INTEGRATION_API_KEY`; run `bun run --cwd sdk test:integration`. They can take 5-10 minutes; `VIBESDK_INTEGRATION_RUN_PREVIEW=1` enables the slower preview case.\n- Root typecheck/lint do not validate `space` or `sdk`. For touched packages run `bun run --cwd space typecheck` / `bun run --cwd space build` and `bun run --cwd sdk package` as appropriate.\n- ESLint checks only `src/**` and `worker/**` and deliberately ignores tests; do not treat `bun run lint` as repository-wide validation.\n- Pre-commit typechecks staged TypeScript and runs related Vitest tests. `RUN_ALL_TESTS=1` selects its broader suite; `SKIP_TESTS=1` bypasses the hook.\n\n## Frontend UI\n- Tailwind CSS v4 via CSS-first setup in `src/index.css` (`@import 'tailwindcss'`, `@theme`, Kumo tokens); no `tailwind.config.*`.\n- Prefer `@cloudflare/kumo` for new UI. List components with `bun kumo ls`; component docs via `bun kumo doc Button` (swap name as needed). Legacy shadcn/Radix under `src/components/ui/` still exists—do not add new primitives there when Kumo covers the case.\n- Icons: `@phosphor-icons/react`. Dark mode is `data-mode=\"dark\"` on the root (not a `class` strategy).\n- Path aliases: `@/*` → `src/*`, `shared/*`, `worker/*` (see `tsconfig.app.json`).\n\n## Frontend Data Fetching\n- Use TanStack Query for frontend server state and network-call caching. `QueryClientProvider` is wired at the React root; configure shared defaults in `src/lib/query-client.ts`.\n- Keep TanStack query keys centralized in `src/lib/query-keys.ts`. Use hierarchical keys so broad invalidation works, for example `queryKeys.apps.all` should invalidate app list/favorite variants.\n- Frontend HTTP still goes through `src/lib/api-client.ts`; query functions should wrap existing `apiClient` methods rather than calling `fetch` directly from components.\n- Include user/account identity in query keys when cached data is user-specific, or explicitly clear/remove those queries on logout/user switch. `enabled: !!user` prevents fetching but does not clear old cached data.\n- Mutations that change cached server state must update cache with `queryClient.setQueryData` or invalidate the relevant `queryKeys` on success. Do not rely on a local `refetch()` in one component if sidebar or other shared UI consumes the same data.\n- Prefer query hooks (`useQuery`, `useMutation`) over ad-hoc loading/error state in React contexts. Context remains appropriate for client-only UI state or providers required by libraries.\n\n## Boundaries\n- `src/` is the React app (`src/main.tsx`, routes in `src/routes.tsx`). API contracts live in `src/api-types.ts`; frontend HTTP calls belong in `src/lib/api-client.ts`.\n- `worker/index.ts` is the Worker entrypoint and Durable Object export surface. Hono middleware/routes are wired by `worker/app.ts` and `worker/api/routes/index.ts`.\n- `space/` is the only declared workspace package. It provides the `SpaceDO` workspace and file layer used by the think agent, with durable git history stored through Cloudflare Artifacts, and is bundled before the root app; edit implementation in `space/src`, never generated `space/dist`, and keep the hand-maintained `space/types/index.d.ts` aligned with public exports.\n- `sdk/` is an independent Bun package with its own lockfile, scripts, and tests. It imports the platform WebSocket protocol from `worker/api/websocketTypes.ts`, so protocol changes must remain SDK-compatible.\n- Shared frontend/backend types belong in `shared/`; Worker-only types stay under `worker/`.\n- Architecture overview (ThinkAgent, SpaceDO, Artifacts, Dynamic Worker previews): `docs/llm.md`. Production deploy: `bun run deploy` (needs `.prod.vars`).\n\n## Change Paths\n- API endpoint: update `src/api-types.ts` -> `src/lib/api-client.ts` -> `worker/database/services/` (when persistence is needed) -> `worker/api/controllers/` -> `worker/api/routes/`, then register the route in `worker/api/routes/index.ts`.\n- WebSocket message: update `worker/api/websocketTypes.ts`, backend handling in `worker/agents/core/websocket.ts`, and frontend handling in `src/routes/chat/utils/handle-websocket-message.ts`; verify SDK tests because its protocol re-exports these types.\n- LLM tool: add it under `worker/agents/tools/toolkit/` and register it in `worker/agents/tools/customTools.ts` (`buildTools` or `buildDebugTools`). The think behavior has a separate tool path and bypasses `buildTools`.\n- Think tool: create it under `worker/agents/think/`, add SpaceDO RPC typing if needed, register it in `ThinkAgent.getTools()`, and update the relevant prompt or skill.\n- D1 schema source is `worker/database/schema.ts`; generate migrations into `migrations/` with `bun run db:generate`, then apply locally with `bun run db:migrate:local`.\n- After changing Wrangler bindings, run `bun run cf-typegen`; `worker-configuration.d.ts` is consumed by setup and TypeScript configs.\n\n## Constraints\n- Do not introduce new `any` types even though ESLint currently permits existing ones; find or define a concrete type. Frontend API types should import from `@/api-types`.\n- Worker code reads bindings from `env`; do not use Vite environment variables there.\n- All `/api/*` routes are owner-only by default in `worker/app.ts`; public routes must explicitly follow the existing auth override pattern.\n- User secrets RPC methods return `null`/`boolean` on failure rather than throwing; preserve that contract when editing `worker/services/secrets/`.\n- For usage-limit UI behavior and its cross-component invariants, read `docs/usage-limits-ui.md` before editing the badge, credits banner, or limit popups.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code when working with code in this repository.\n\n## Communication Style\n- Be professional, concise, and direct\n- Do NOT use emojis in code reviews, changelogs, or any generated content. You may use professional visual indicators or favor markdown formatting over emojis.\n- Focus on substance over style\n- Use clear technical language\n\n## Project Overview\n\nVibeSDK is an agentic full-stack application builder on Cloudflare.\n\n**Tech Stack:**\n- Frontend: React 19, TypeScript, Vite, TailwindCSS, React Router v7\n- Backend: Cloudflare Workers, Durable Objects, Hono, D1, R2, and KV\n- Agent: Cloudflare Think with AI Gateway model routing\n- Workspace: SpaceDO Durable Objects\n- Version history: Cloudflare Artifacts\n- Preview runtime: Worker Loader bindings and Dynamic Workers\n- Generated app data: Durable Object Facets with isolated SQLite\n- WebSocket: PartySocket for real-time communication\n\n**Project Structure:**\n- `/src` - React frontend, API types, and API client\n- `/worker/agents/think` - ThinkAgent, prompts, skills, workspace adapter, and tools\n- `/worker/agents/core/behaviors/think.ts` - Think host orchestration\n- `/worker/api` - Routes, controllers, handlers, and WebSocket types\n- `/worker/database` - D1 schema and services\n- `/space` - SpaceDO, Artifacts synchronization, preview bundling, and App Facets\n- `/sdk` - TypeScript client SDK\n- `/migrations` - D1 migrations\n- `/scripts` - Setup and deployment utilities\n\n## Key Architectural Patterns\n\n**ThinkAgent:**\n- One Agent backed by a Durable Object per app session\n- Owns conversation, context selection, skills, streaming, tools, and step limits\n- Uses explicit SpaceDO-backed tools; workspace bash is disabled\n\n**Workspace and Versioning:**\n- SpaceDO owns the isolated live workspace and files\n- Cloudflare Artifacts owns durable commits, branches, history, and restore points\n- `commit` saves without deploying; `deploy_space` commits and rebuilds the preview\n- Rollback applies a selected tree, creates a new commit, and redeploys\n\n**Preview Runtime:**\n- `@cloudflare/worker-bundler` builds committed project files\n- Worker Loader loads bundled modules as a Dynamic Worker\n- Generated `App` classes run as Durable Object Facets with isolated SQLite\n\n**WebSocket Communication:**\n- PartySocket carries realtime agent output, tools, files, and deployment state\n- Session state is restored on reconnect\n\n## Common Development Tasks\n\n**Change LLM Model for Operation:**\nEdit `/worker/agents/inferutils/config.ts` → `AGENT_CONFIG` object\n\n**Modify Think Agent Behavior:**\nEdit `worker/agents/think/ThinkAgent.ts`, the host behavior in `worker/agents/core/behaviors/think.ts`, and the relevant prompt or skill.\n\n**Add New WebSocket Message:**\n1. Add type to `worker/api/websocketTypes.ts`\n2. Handle in `worker/agents/core/websocket.ts`\n3. Handle in `src/routes/chat/utils/handle-websocket-message.ts`\n\n**Add New Think Tool:**\n1. Create the tool under `worker/agents/think/`\n2. Add required SpaceDO RPC typing to `space-workspace-ops.ts`\n3. Register it in `ThinkAgent.getTools()`\n4. Update the relevant prompt or skill\n5. Add focused tests\n\n**Add API Endpoint:**\n1. Define types in `src/api-types.ts`\n2. Add to `src/lib/api-client.ts`\n3. Create service in `worker/database/services/`\n4. Create controller in `worker/api/controllers/`\n5. Add route in `worker/api/routes/`\n6. Register in `worker/api/routes/index.ts`\n\n## Important Context\n\n**User Secrets Store (Durable Object):**\n- Location: `/worker/services/secrets/`\n- Purpose: Encrypted storage for user API keys with key rotation\n- Architecture: One DO per user, XChaCha20-Poly1305 encryption, SQLite backend\n- Key derivation: MEK → UMK → DEK (hierarchical PBKDF2)\n- Features: Key rotation, soft deletion, access tracking, expiration support\n- RPC Methods: Return `null`/`boolean` on error, never throw exceptions\n- Testing: 90 comprehensive tests in `/test/worker/services/secrets/`\n\n**Workspace and Git:**\n- SpaceDO provides workspace and file operations\n- Cloudflare Artifacts stores durable git history\n- Artifacts synchronization lives in `space/src/space/artifacts-sync.ts`\n- Rollback preserves history by creating a new commit\n\n**Abort Controller Pattern:**\n- `getOrCreateAbortController()` reuses controller for nested operations\n- Cleared after top-level operations complete\n- Shared by parent and nested tool calls\n- User abort cancels entire operation tree\n\n**Message Deduplication:**\n- Tool execution causes duplicate AI messages\n- Backend skips redundant LLM calls (empty tool results)\n- Frontend utilities deduplicate live and restored messages\n- System prompt teaches LLM not to repeat\n\n## Core Rules (Non-Negotiable)\n\n**1. Strict Type Safety**\n- NEVER use `any` type\n- Frontend imports types from `@/api-types` (single source of truth)\n- Search codebase for existing types before creating new ones\n\n**2. DRY Principle**\n- Search for similar functionality before implementing\n- Extract reusable utilities, hooks, and components\n- Never copy-paste code - refactor into shared functions\n\n**3. Follow Existing Patterns**\n- Frontend APIs: All in `/src/lib/api-client.ts`\n- Backend Routes: Controllers in `worker/api/controllers/`, routes in `worker/api/routes/`\n- Database Services: In `worker/database/services/`\n- Types: Shared in `shared/types/`, API in `src/api-types.ts`\n\n**4. Code Quality**\n- Production-ready code only - no TODOs or placeholders\n- No hacky workarounds\n- Comments explain purpose, not narration\n- No overly verbose AI-like comments\n\n**5. File Naming**\n- React Components: PascalCase.tsx\n- Utilities/Hooks: kebab-case.ts\n- Backend Services: PascalCase.ts\n\n## Common Pitfalls\n\n**Don't:**\n- Use `any` type (find or create proper types)\n- Copy-paste code (extract to utilities)\n- Use Vite env variables in Worker code\n- Forget to update types when changing APIs\n- Create new implementations without searching for existing ones\n- Use emojis in code or comments\n- Write verbose AI-like comments\n\n**Do:**\n- Search codebase thoroughly before creating new code\n- Follow existing patterns consistently\n- Keep comments concise and purposeful\n- Write production-ready code\n- Test thoroughly before submitting"},"files":{"AGENTS.md":"# AGENTS.md\n\n## Tooling\n- Use Bun from the repository root. The tracked lockfile is `bun.lock`, the `space` workspace dependency uses `workspace:*`, and install/build hooks invoke Bun even when started through npm.\n- `bun run setup` is the interactive Cloudflare/resource bootstrap. Local development expects the generated `.dev.vars`; never commit `.dev.vars*` or `.prod.vars`.\n- `bun run dev` starts the React frontend and Worker together through `@cloudflare/vite-plugin` at `http://localhost:5173`. There is no separate Worker dev command.\n- `bun run dev:browser` is an optional local Chromium sidecar for the think agent's browser-console tool; absence only produces a warning.\n\n## Verification\n- Root checks: `bun run typecheck`, `bun run lint`, `bun run test`, `bun run build`.\n- `bun run build` builds `space` and the Vite/Worker bundle; it does not typecheck. Run `bun run typecheck` separately.\n- Focus a root test with `bunx vitest run path/to/file.test.ts`; test execution uses the Workers pool and `wrangler.test.jsonc`.\n- The root Vitest suite excludes all `sdk/test/**` and `container/monitor-cli.test.ts`. SDK tests use Bun: `bun run --cwd sdk test`.\n- SDK integration tests require a running root dev server and `VIBESDK_INTEGRATION_API_KEY`; run `bun run --cwd sdk test:integration`. They can take 5-10 minutes; `VIBESDK_INTEGRATION_RUN_PREVIEW=1` enables the slower preview case.\n- Root typecheck/lint do not validate `space` or `sdk`. For touched packages run `bun run --cwd space typecheck` / `bun run --cwd space build` and `bun run --cwd sdk package` as appropriate.\n- ESLint checks only `src/**` and `worker/**` and deliberately ignores tests; do not treat `bun run lint` as repository-wide validation.\n- Pre-commit typechecks staged TypeScript and runs related Vitest tests. `RUN_ALL_TESTS=1` selects its broader suite; `SKIP_TESTS=1` bypasses the hook.\n\n## Frontend UI\n- Tailwind CSS v4 via CSS-first setup in `src/index.css` (`@import 'tailwindcss'`, `@theme`, Kumo tokens); no `tailwind.config.*`.\n- Prefer `@cloudflare/kumo` for new UI. List components with `bun kumo ls`; component docs via `bun kumo doc Button` (swap name as needed). Legacy shadcn/Radix under `src/components/ui/` still exists—do not add new primitives there when Kumo covers the case.\n- Icons: `@phosphor-icons/react`. Dark mode is `data-mode=\"dark\"` on the root (not a `class` strategy).\n- Path aliases: `@/*` → `src/*`, `shared/*`, `worker/*` (see `tsconfig.app.json`).\n\n## Frontend Data Fetching\n- Use TanStack Query for frontend server state and network-call caching. `QueryClientProvider` is wired at the React root; configure shared defaults in `src/lib/query-client.ts`.\n- Keep TanStack query keys centralized in `src/lib/query-keys.ts`. Use hierarchical keys so broad invalidation works, for example `queryKeys.apps.all` should invalidate app list/favorite variants.\n- Frontend HTTP still goes through `src/lib/api-client.ts`; query functions should wrap existing `apiClient` methods rather than calling `fetch` directly from components.\n- Include user/account identity in query keys when cached data is user-specific, or explicitly clear/remove those queries on logout/user switch. `enabled: !!user` prevents fetching but does not clear old cached data.\n- Mutations that change cached server state must update cache with `queryClient.setQueryData` or invalidate the relevant `queryKeys` on success. Do not rely on a local `refetch()` in one component if sidebar or other shared UI consumes the same data.\n- Prefer query hooks (`useQuery`, `useMutation`) over ad-hoc loading/error state in React contexts. Context remains appropriate for client-only UI state or providers required by libraries.\n\n## Boundaries\n- `src/` is the React app (`src/main.tsx`, routes in `src/routes.tsx`). API contracts live in `src/api-types.ts`; frontend HTTP calls belong in `src/lib/api-client.ts`.\n- `worker/index.ts` is the Worker entrypoint and Durable Object export surface. Hono middleware/routes are wired by `worker/app.ts` and `worker/api/routes/index.ts`.\n- `space/` is the only declared workspace package. It provides the `SpaceDO` workspace and file layer used by the think agent, with durable git history stored through Cloudflare Artifacts, and is bundled before the root app; edit implementation in `space/src`, never generated `space/dist`, and keep the hand-maintained `space/types/index.d.ts` aligned with public exports.\n- `sdk/` is an independent Bun package with its own lockfile, scripts, and tests. It imports the platform WebSocket protocol from `worker/api/websocketTypes.ts`, so protocol changes must remain SDK-compatible.\n- Shared frontend/backend types belong in `shared/`; Worker-only types stay under `worker/`.\n- Architecture overview (ThinkAgent, SpaceDO, Artifacts, Dynamic Worker previews): `docs/llm.md`. Production deploy: `bun run deploy` (needs `.prod.vars`).\n\n## Change Paths\n- API endpoint: update `src/api-types.ts` -> `src/lib/api-client.ts` -> `worker/database/services/` (when persistence is needed) -> `worker/api/controllers/` -> `worker/api/routes/`, then register the route in `worker/api/routes/index.ts`.\n- WebSocket message: update `worker/api/websocketTypes.ts`, backend handling in `worker/agents/core/websocket.ts`, and frontend handling in `src/routes/chat/utils/handle-websocket-message.ts`; verify SDK tests because its protocol re-exports these types.\n- LLM tool: add it under `worker/agents/tools/toolkit/` and register it in `worker/agents/tools/customTools.ts` (`buildTools` or `buildDebugTools`). The think behavior has a separate tool path and bypasses `buildTools`.\n- Think tool: create it under `worker/agents/think/`, add SpaceDO RPC typing if needed, register it in `ThinkAgent.getTools()`, and update the relevant prompt or skill.\n- D1 schema source is `worker/database/schema.ts`; generate migrations into `migrations/` with `bun run db:generate`, then apply locally with `bun run db:migrate:local`.\n- After changing Wrangler bindings, run `bun run cf-typegen`; `worker-configuration.d.ts` is consumed by setup and TypeScript configs.\n\n## Constraints\n- Do not introduce new `any` types even though ESLint currently permits existing ones; find or define a concrete type. Frontend API types should import from `@/api-types`.\n- Worker code reads bindings from `env`; do not use Vite environment variables there.\n- All `/api/*` routes are owner-only by default in `worker/app.ts`; public routes must explicitly follow the existing auth override pattern.\n- User secrets RPC methods return `null`/`boolean` on failure rather than throwing; preserve that contract when editing `worker/services/secrets/`.\n- For usage-limit UI behavior and its cross-component invariants, read `docs/usage-limits-ui.md` before editing the badge, credits banner, or limit popups.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code when working with code in this repository.\n\n## Communication Style\n- Be professional, concise, and direct\n- Do NOT use emojis in code reviews, changelogs, or any generated content. You may use professional visual indicators or favor markdown formatting over emojis.\n- Focus on substance over style\n- Use clear technical language\n\n## Project Overview\n\nVibeSDK is an agentic full-stack application builder on Cloudflare.\n\n**Tech Stack:**\n- Frontend: React 19, TypeScript, Vite, TailwindCSS, React Router v7\n- Backend: Cloudflare Workers, Durable Objects, Hono, D1, R2, and KV\n- Agent: Cloudflare Think with AI Gateway model routing\n- Workspace: SpaceDO Durable Objects\n- Version history: Cloudflare Artifacts\n- Preview runtime: Worker Loader bindings and Dynamic Workers\n- Generated app data: Durable Object Facets with isolated SQLite\n- WebSocket: PartySocket for real-time communication\n\n**Project Structure:**\n- `/src` - React frontend, API types, and API client\n- `/worker/agents/think` - ThinkAgent, prompts, skills, workspace adapter, and tools\n- `/worker/agents/core/behaviors/think.ts` - Think host orchestration\n- `/worker/api` - Routes, controllers, handlers, and WebSocket types\n- `/worker/database` - D1 schema and services\n- `/space` - SpaceDO, Artifacts synchronization, preview bundling, and App Facets\n- `/sdk` - TypeScript client SDK\n- `/migrations` - D1 migrations\n- `/scripts` - Setup and deployment utilities\n\n## Key Architectural Patterns\n\n**ThinkAgent:**\n- One Agent backed by a Durable Object per app session\n- Owns conversation, context selection, skills, streaming, tools, and step limits\n- Uses explicit SpaceDO-backed tools; workspace bash is disabled\n\n**Workspace and Versioning:**\n- SpaceDO owns the isolated live workspace and files\n- Cloudflare Artifacts owns durable commits, branches, history, and restore points\n- `commit` saves without deploying; `deploy_space` commits and rebuilds the preview\n- Rollback applies a selected tree, creates a new commit, and redeploys\n\n**Preview Runtime:**\n- `@cloudflare/worker-bundler` builds committed project files\n- Worker Loader loads bundled modules as a Dynamic Worker\n- Generated `App` classes run as Durable Object Facets with isolated SQLite\n\n**WebSocket Communication:**\n- PartySocket carries realtime agent output, tools, files, and deployment state\n- Session state is restored on reconnect\n\n## Common Development Tasks\n\n**Change LLM Model for Operation:**\nEdit `/worker/agents/inferutils/config.ts` → `AGENT_CONFIG` object\n\n**Modify Think Agent Behavior:**\nEdit `worker/agents/think/ThinkAgent.ts`, the host behavior in `worker/agents/core/behaviors/think.ts`, and the relevant prompt or skill.\n\n**Add New WebSocket Message:**\n1. Add type to `worker/api/websocketTypes.ts`\n2. Handle in `worker/agents/core/websocket.ts`\n3. Handle in `src/routes/chat/utils/handle-websocket-message.ts`\n\n**Add New Think Tool:**\n1. Create the tool under `worker/agents/think/`\n2. Add required SpaceDO RPC typing to `space-workspace-ops.ts`\n3. Register it in `ThinkAgent.getTools()`\n4. Update the relevant prompt or skill\n5. Add focused tests\n\n**Add API Endpoint:**\n1. Define types in `src/api-types.ts`\n2. Add to `src/lib/api-client.ts`\n3. Create service in `worker/database/services/`\n4. Create controller in `worker/api/controllers/`\n5. Add route in `worker/api/routes/`\n6. Register in `worker/api/routes/index.ts`\n\n## Important Context\n\n**User Secrets Store (Durable Object):**\n- Location: `/worker/services/secrets/`\n- Purpose: Encrypted storage for user API keys with key rotation\n- Architecture: One DO per user, XChaCha20-Poly1305 encryption, SQLite backend\n- Key derivation: MEK → UMK → DEK (hierarchical PBKDF2)\n- Features: Key rotation, soft deletion, access tracking, expiration support\n- RPC Methods: Return `null`/`boolean` on error, never throw exceptions\n- Testing: 90 comprehensive tests in `/test/worker/services/secrets/`\n\n**Workspace and Git:**\n- SpaceDO provides workspace and file operations\n- Cloudflare Artifacts stores durable git history\n- Artifacts synchronization lives in `space/src/space/artifacts-sync.ts`\n- Rollback preserves history by creating a new commit\n\n**Abort Controller Pattern:**\n- `getOrCreateAbortController()` reuses controller for nested operations\n- Cleared after top-level operations complete\n- Shared by parent and nested tool calls\n- User abort cancels entire operation tree\n\n**Message Deduplication:**\n- Tool execution causes duplicate AI messages\n- Backend skips redundant LLM calls (empty tool results)\n- Frontend utilities deduplicate live and restored messages\n- System prompt teaches LLM not to repeat\n\n## Core Rules (Non-Negotiable)\n\n**1. Strict Type Safety**\n- NEVER use `any` type\n- Frontend imports types from `@/api-types` (single source of truth)\n- Search codebase for existing types before creating new ones\n\n**2. DRY Principle**\n- Search for similar functionality before implementing\n- Extract reusable utilities, hooks, and components\n- Never copy-paste code - refactor into shared functions\n\n**3. Follow Existing Patterns**\n- Frontend APIs: All in `/src/lib/api-client.ts`\n- Backend Routes: Controllers in `worker/api/controllers/`, routes in `worker/api/routes/`\n- Database Services: In `worker/database/services/`\n- Types: Shared in `shared/types/`, API in `src/api-types.ts`\n\n**4. Code Quality**\n- Production-ready code only - no TODOs or placeholders\n- No hacky workarounds\n- Comments explain purpose, not narration\n- No overly verbose AI-like comments\n\n**5. File Naming**\n- React Components: PascalCase.tsx\n- Utilities/Hooks: kebab-case.ts\n- Backend Services: PascalCase.ts\n\n## Common Pitfalls\n\n**Don't:**\n- Use `any` type (find or create proper types)\n- Copy-paste code (extract to utilities)\n- Use Vite env variables in Worker code\n- Forget to update types when changing APIs\n- Create new implementations without searching for existing ones\n- Use emojis in code or comments\n- Write verbose AI-like comments\n\n**Do:**\n- Search codebase thoroughly before creating new code\n- Follow existing patterns consistently\n- Keep comments concise and purposeful\n- Write production-ready code\n- Test thoroughly before submitting"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n## Tooling\n- Use Bun from the repository root. The tracked lockfile is `bun.lock`, the `space` workspace dependency uses `workspace:*`, and install/build hooks invoke Bun even when started through npm.\n- `bun run setup` is the interactive Cloudflare/resource bootstrap. Local development expects the generated `.dev.vars`; never commit `.dev.vars*` or `.prod.vars`.\n- `bun run dev` starts the React frontend and Worker together through `@cloudflare/vite-plugin` at `http://localhost:5173`. There is no separate Worker dev command.\n- `bun run dev:browser` is an optional local Chromium sidecar for the think agent's browser-console tool; absence only produces a warning.\n\n## Verification\n- Root checks: `bun run typecheck`, `bun run lint`, `bun run test`, `bun run build`.\n- `bun run build` builds `space` and the Vite/Worker bundle; it does not typecheck. Run `bun run typecheck` separately.\n- Focus a root test with `bunx vitest run path/to/file.test.ts`; test execution uses the Workers pool and `wrangler.test.jsonc`.\n- The root Vitest suite excludes all `sdk/test/**` and `container/monitor-cli.test.ts`. SDK tests use Bun: `bun run --cwd sdk test`.\n- SDK integration tests require a running root dev server and `VIBESDK_INTEGRATION_API_KEY`; run `bun run --cwd sdk test:integration`. They can take 5-10 minutes; `VIBESDK_INTEGRATION_RUN_PREVIEW=1` enables the slower preview case.\n- Root typecheck/lint do not validate `space` or `sdk`. For touched packages run `bun run --cwd space typecheck` / `bun run --cwd space build` and `bun run --cwd sdk package` as appropriate.\n- ESLint checks only `src/**` and `worker/**` and deliberately ignores tests; do not treat `bun run lint` as repository-wide validation.\n- Pre-commit typechecks staged TypeScript and runs related Vitest tests. `RUN_ALL_TESTS=1` selects its broader suite; `SKIP_TESTS=1` bypasses the hook.\n\n## Frontend UI\n- Tailwind CSS v4 via CSS-first setup in `src/index.css` (`@import 'tailwindcss'`, `@theme`, Kumo tokens); no `tailwind.config.*`.\n- Prefer `@cloudflare/kumo` for new UI. List components with `bun kumo ls`; component docs via `bun kumo doc Button` (swap name as needed). Legacy shadcn/Radix under `src/components/ui/` still exists—do not add new primitives there when Kumo covers the case.\n- Icons: `@phosphor-icons/react`. Dark mode is `data-mode=\"dark\"` on the root (not a `class` strategy).\n- Path aliases: `@/*` → `src/*`, `shared/*`, `worker/*` (see `tsconfig.app.json`).\n\n## Frontend Data Fetching\n- Use TanStack Query for frontend server state and network-call caching. `QueryClientProvider` is wired at the React root; configure shared defaults in `src/lib/query-client.ts`.\n- Keep TanStack query keys centralized in `src/lib/query-keys.ts`. Use hierarchical keys so broad invalidation works, for example `queryKeys.apps.all` should invalidate app list/favorite variants.\n- Frontend HTTP still goes through `src/lib/api-client.ts`; query functions should wrap existing `apiClient` methods rather than calling `fetch` directly from components.\n- Include user/account identity in query keys when cached data is user-specific, or explicitly clear/remove those queries on logout/user switch. `enabled: !!user` prevents fetching but does not clear old cached data.\n- Mutations that change cached server state must update cache with `queryClient.setQueryData` or invalidate the relevant `queryKeys` on success. Do not rely on a local `refetch()` in one component if sidebar or other shared UI consumes the same data.\n- Prefer query hooks (`useQuery`, `useMutation`) over ad-hoc loading/error state in React contexts. Context remains appropriate for client-only UI state or providers required by libraries.\n\n## Boundaries\n- `src/` is the React app (`src/main.tsx`, routes in `src/routes.tsx`). API contracts live in `src/api-types.ts`; frontend HTTP calls belong in `src/lib/api-client.ts`.\n- `worker/index.ts` is the Worker entrypoint and Durable Object export surface. Hono middleware/routes are wired by `worker/app.ts` and `worker/api/routes/index.ts`.\n- `space/` is the only declared workspace package. It provides the `SpaceDO` workspace and file layer used by the think agent, with durable git history stored through Cloudflare Artifacts, and is bundled before the root app; edit implementation in `space/src`, never generated `space/dist`, and keep the hand-maintained `space/types/index.d.ts` aligned with public exports.\n- `sdk/` is an independent Bun package with its own lockfile, scripts, and tests. It imports the platform WebSocket protocol from `worker/api/websocketTypes.ts`, so protocol changes must remain SDK-compatible.\n- Shared frontend/backend types belong in `shared/`; Worker-only types stay under `worker/`.\n- Architecture overview (ThinkAgent, SpaceDO, Artifacts, Dynamic Worker previews): `docs/llm.md`. Production deploy: `bun run deploy` (needs `.prod.vars`).\n\n## Change Paths\n- API endpoint: update `src/api-types.ts` -> `src/lib/api-client.ts` -> `worker/database/services/` (when persistence is needed) -> `worker/api/controllers/` -> `worker/api/routes/`, then register the route in `worker/api/routes/index.ts`.\n- WebSocket message: update `worker/api/websocketTypes.ts`, backend handling in `worker/agents/core/websocket.ts`, and frontend handling in `src/routes/chat/utils/handle-websocket-message.ts`; verify SDK tests because its protocol re-exports these types.\n- LLM tool: add it under `worker/agents/tools/toolkit/` and register it in `worker/agents/tools/customTools.ts` (`buildTools` or `buildDebugTools`). The think behavior has a separate tool path and bypasses `buildTools`.\n- Think tool: create it under `worker/agents/think/`, add SpaceDO RPC typing if needed, register it in `ThinkAgent.getTools()`, and update the relevant prompt or skill.\n- D1 schema source is `worker/database/schema.ts`; generate migrations into `migrations/` with `bun run db:generate`, then apply locally with `bun run db:migrate:local`.\n- After changing Wrangler bindings, run `bun run cf-typegen`; `worker-configuration.d.ts` is consumed by setup and TypeScript configs.\n\n## Constraints\n- Do not introduce new `any` types even though ESLint currently permits existing ones; find or define a concrete type. Frontend API types should import from `@/api-types`.\n- Worker code reads bindings from `env`; do not use Vite environment variables there.\n- All `/api/*` routes are owner-only by default in `worker/app.ts`; public routes must explicitly follow the existing auth override pattern.\n- User secrets RPC methods return `null`/`boolean` on failure rather than throwing; preserve that contract when editing `worker/services/secrets/`.\n- For usage-limit UI behavior and its cross-component invariants, read `docs/usage-limits-ui.md` before editing the badge, credits banner, or limit popups.\n","category":"root","tokens":1703},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code when working with code in this repository.\n\n## Communication Style\n- Be professional, concise, and direct\n- Do NOT use emojis in code reviews, changelogs, or any generated content. You may use professional visual indicators or favor markdown formatting over emojis.\n- Focus on substance over style\n- Use clear technical language\n\n## Project Overview\n\nVibeSDK is an agentic full-stack application builder on Cloudflare.\n\n**Tech Stack:**\n- Frontend: React 19, TypeScript, Vite, TailwindCSS, React Router v7\n- Backend: Cloudflare Workers, Durable Objects, Hono, D1, R2, and KV\n- Agent: Cloudflare Think with AI Gateway model routing\n- Workspace: SpaceDO Durable Objects\n- Version history: Cloudflare Artifacts\n- Preview runtime: Worker Loader bindings and Dynamic Workers\n- Generated app data: Durable Object Facets with isolated SQLite\n- WebSocket: PartySocket for real-time communication\n\n**Project Structure:**\n- `/src` - React frontend, API types, and API client\n- `/worker/agents/think` - ThinkAgent, prompts, skills, workspace adapter, and tools\n- `/worker/agents/core/behaviors/think.ts` - Think host orchestration\n- `/worker/api` - Routes, controllers, handlers, and WebSocket types\n- `/worker/database` - D1 schema and services\n- `/space` - SpaceDO, Artifacts synchronization, preview bundling, and App Facets\n- `/sdk` - TypeScript client SDK\n- `/migrations` - D1 migrations\n- `/scripts` - Setup and deployment utilities\n\n## Key Architectural Patterns\n\n**ThinkAgent:**\n- One Agent backed by a Durable Object per app session\n- Owns conversation, context selection, skills, streaming, tools, and step limits\n- Uses explicit SpaceDO-backed tools; workspace bash is disabled\n\n**Workspace and Versioning:**\n- SpaceDO owns the isolated live workspace and files\n- Cloudflare Artifacts owns durable commits, branches, history, and restore points\n- `commit` saves without deploying; `deploy_space` commits and rebuilds the preview\n- Rollback applies a selected tree, creates a new commit, and redeploys\n\n**Preview Runtime:**\n- `@cloudflare/worker-bundler` builds committed project files\n- Worker Loader loads bundled modules as a Dynamic Worker\n- Generated `App` classes run as Durable Object Facets with isolated SQLite\n\n**WebSocket Communication:**\n- PartySocket carries realtime agent output, tools, files, and deployment state\n- Session state is restored on reconnect\n\n## Common Development Tasks\n\n**Change LLM Model for Operation:**\nEdit `/worker/agents/inferutils/config.ts` → `AGENT_CONFIG` object\n\n**Modify Think Agent Behavior:**\nEdit `worker/agents/think/ThinkAgent.ts`, the host behavior in `worker/agents/core/behaviors/think.ts`, and the relevant prompt or skill.\n\n**Add New WebSocket Message:**\n1. Add type to `worker/api/websocketTypes.ts`\n2. Handle in `worker/agents/core/websocket.ts`\n3. Handle in `src/routes/chat/utils/handle-websocket-message.ts`\n\n**Add New Think Tool:**\n1. Create the tool under `worker/agents/think/`\n2. Add required SpaceDO RPC typing to `space-workspace-ops.ts`\n3. Register it in `ThinkAgent.getTools()`\n4. Update the relevant prompt or skill\n5. Add focused tests\n\n**Add API Endpoint:**\n1. Define types in `src/api-types.ts`\n2. Add to `src/lib/api-client.ts`\n3. Create service in `worker/database/services/`\n4. Create controller in `worker/api/controllers/`\n5. Add route in `worker/api/routes/`\n6. Register in `worker/api/routes/index.ts`\n\n## Important Context\n\n**User Secrets Store (Durable Object):**\n- Location: `/worker/services/secrets/`\n- Purpose: Encrypted storage for user API keys with key rotation\n- Architecture: One DO per user, XChaCha20-Poly1305 encryption, SQLite backend\n- Key derivation: MEK → UMK → DEK (hierarchical PBKDF2)\n- Features: Key rotation, soft deletion, access tracking, expiration support\n- RPC Methods: Return `null`/`boolean` on error, never throw exceptions\n- Testing: 90 comprehensive tests in `/test/worker/services/secrets/`\n\n**Workspace and Git:**\n- SpaceDO provides workspace and file operations\n- Cloudflare Artifacts stores durable git history\n- Artifacts synchronization lives in `space/src/space/artifacts-sync.ts`\n- Rollback preserves history by creating a new commit\n\n**Abort Controller Pattern:**\n- `getOrCreateAbortController()` reuses controller for nested operations\n- Cleared after top-level operations complete\n- Shared by parent and nested tool calls\n- User abort cancels entire operation tree\n\n**Message Deduplication:**\n- Tool execution causes duplicate AI messages\n- Backend skips redundant LLM calls (empty tool results)\n- Frontend utilities deduplicate live and restored messages\n- System prompt teaches LLM not to repeat\n\n## Core Rules (Non-Negotiable)\n\n**1. Strict Type Safety**\n- NEVER use `any` type\n- Frontend imports types from `@/api-types` (single source of truth)\n- Search codebase for existing types before creating new ones\n\n**2. DRY Principle**\n- Search for similar functionality before implementing\n- Extract reusable utilities, hooks, and components\n- Never copy-paste code - refactor into shared functions\n\n**3. Follow Existing Patterns**\n- Frontend APIs: All in `/src/lib/api-client.ts`\n- Backend Routes: Controllers in `worker/api/controllers/`, routes in `worker/api/routes/`\n- Database Services: In `worker/database/services/`\n- Types: Shared in `shared/types/`, API in `src/api-types.ts`\n\n**4. Code Quality**\n- Production-ready code only - no TODOs or placeholders\n- No hacky workarounds\n- Comments explain purpose, not narration\n- No overly verbose AI-like comments\n\n**5. File Naming**\n- React Components: PascalCase.tsx\n- Utilities/Hooks: kebab-case.ts\n- Backend Services: PascalCase.ts\n\n## Common Pitfalls\n\n**Don't:**\n- Use `any` type (find or create proper types)\n- Copy-paste code (extract to utilities)\n- Use Vite env variables in Worker code\n- Forget to update types when changing APIs\n- Create new implementations without searching for existing ones\n- Use emojis in code or comments\n- Write verbose AI-like comments\n\n**Do:**\n- Search codebase thoroughly before creating new code\n- Follow existing patterns consistently\n- Keep comments concise and purposeful\n- Write production-ready code\n- Test thoroughly before submitting","category":"root","tokens":1551}]}