memory-journal-mcp 7.7.0 → 8.0.0

package/skills/agents-sdk/references/workflows.md

@@ -0,0 +1,136 @@
+# Workflows Integration
+
+Fetch `docs/workflows.md` from `https://github.com/cloudflare/agents/tree/main/docs` for complete documentation.
+
+## Overview
+
+Agents handle real-time communication; Workflows handle durable execution. Together they enable:
+
+- Long-running background tasks with automatic retries
+- Human-in-the-loop approval flows
+- Multi-step pipelines that survive failures
+
+| Use Case                     | Recommendation   |
+| ---------------------------- | ---------------- |
+| Chat/messaging               | Agent only       |
+| Quick API calls (<30s)       | Agent only       |
+| Background processing (<30s) | Agent `queue()`  |
+| Long-running tasks (>30s)    | Agent + Workflow |
+| Human approval flows         | Agent + Workflow |
+
+## AgentWorkflow Base Class
+
+```typescript
+import { AgentWorkflow } from 'agents/workflows'
+import type { AgentWorkflowEvent, AgentWorkflowStep } from 'agents/workflows'
+
+type TaskParams = { taskId: string; data: string }
+
+export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> {
+  async run(event: AgentWorkflowEvent<TaskParams>, step: AgentWorkflowStep) {
+    const params = event.payload
+
+    // Durable step - retries on failure
+    const result = await step.do('process', async () => {
+      return processData(params.data)
+    })
+
+    // Non-durable: progress reporting
+    await this.reportProgress({ step: 'process', percent: 0.5 })
+
+    // Non-durable: broadcast to connected clients
+    this.broadcastToClients({ type: 'update', taskId: params.taskId })
+
+    // Durable: merge state via step
+    await step.mergeAgentState({ lastProcessed: params.taskId })
+
+    // Durable: report completion
+    await step.reportComplete(result)
+
+    return result
+  }
+}
+```
+
+## Wrangler Configuration
+
+```jsonc
+{
+  "workflows": [
+    {
+      "name": "processing-workflow",
+      "binding": "PROCESSING_WORKFLOW",
+      "class_name": "ProcessingWorkflow",
+    },
+  ],
+  "durable_objects": {
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }],
+}
+```
+
+## Agent Methods for Workflows
+
+```typescript
+// Start a workflow
+const instance = await this.runWorkflow("ProcessingWorkflow", { taskId: "123", data: "..." });
+
+// Send event to waiting workflow
+await this.sendWorkflowEvent("ProcessingWorkflow", workflowId, { type: "approve" });
+
+// Query workflows
+const workflow = await this.getWorkflow(workflowId);
+const workflows = await this.getWorkflows({ status: "running" });
+
+// Control workflows
+await this.approveWorkflow(workflowId);
+await this.rejectWorkflow(workflowId);
+await this.terminateWorkflow(workflowId);
+await this.pauseWorkflow(workflowId);
+await this.resumeWorkflow(workflowId);
+
+// Delete workflows
+await this.deleteWorkflow(workflowId);
+await this.deleteWorkflows({ status: "complete", before: new Date(...) });
+```
+
+## Lifecycle Callbacks
+
+```typescript
+export class MyAgent extends Agent<Env, State> {
+  async onWorkflowProgress(workflowName: string, workflowId: string, progress: unknown) {
+    // Workflow reported progress via this.reportProgress()
+    this.broadcast({ type: 'progress', workflowId, progress })
+  }
+
+  async onWorkflowComplete(workflowName: string, workflowId: string, result?: unknown) {
+    // Workflow finished successfully
+  }
+
+  async onWorkflowError(workflowName: string, workflowId: string, error: Error) {
+    // Workflow failed
+  }
+
+  async onWorkflowEvent(workflowName: string, workflowId: string, event: unknown) {
+    // Workflow received an event via sendWorkflowEvent()
+  }
+}
+```
+
+## Human-in-the-Loop
+
+```typescript
+// In workflow: wait for approval
+const approved = await step.waitForEvent<{ approved: boolean }>('approval', {
+  timeout: '7d',
+})
+
+if (!approved.approved) {
+  throw new Error('Rejected')
+}
+
+// From agent: approve or reject
+await this.approveWorkflow(workflowId) // Sends { approved: true }
+await this.rejectWorkflow(workflowId) // Sends { approved: false }
+```

package/skills/auth-identity/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: auth-identity
+description: |
+  Standards for Authentication and Identity management. Use when configuring OAuth, JWTs, sessions, RBAC (Role-Based Access Control), or integrating auth providers (Auth0, Clerk, NextAuth). SECURITY: Implementing auth requires strict fallback logic. Never fail-open. Handle token expiration and revocation gracefully.
+---
+
+# Authentication & Identity
+
+This skill outlines the strict security requirements and architectural patterns for implementing Authentication and Identity (AuthN/AuthZ) in modern applications.
+
+## Security Gates (CRITICAL)
+
+> **CRITICAL HITL GATE**: You MUST stop and ask the user for explicit confirmation before modifying authentication flows, updating token expiration times, changing cookie settings (`httpOnly`, `Secure`), or adding new OAuth providers.
+> Auth changes carry high risk of introducing vulnerabilities. Never silently commit auth logic.
+
+## 1. OAuth & OIDC (OpenID Connect)
+
+- **Standard Flow**: Always use the **Authorization Code flow with PKCE** (Proof Key for Code Exchange) for SPAs and mobile apps. Never use the Implicit Flow (it is deprecated and insecure).
+- **State Parameter**: Always implement and validate the `state` parameter to prevent CSRF (Cross-Site Request Forgery) attacks during the OAuth callback.
+- **Provider Scopes**: Request the minimum necessary scopes. Never request `offline_access` (refresh tokens) unless explicitly required and approved by the user.
+
+## 2. JWT (JSON Web Tokens)
+
+- **Signing Algorithms**: Always use asymmetric algorithms (e.g., `RS256`, `EdDSA`) if the token needs to be verified by multiple services. Use `HS256` only if the issuer and verifier are the exact same service. NEVER allow the `none` algorithm.
+- **Payload Data**: Never put sensitive data (PII, passwords, internal IDs) inside a JWT payload. JWTs are Base64 encoded, not encrypted.
+- **Expiration**: Keep short-lived access tokens (e.g., 15-60 minutes). Use Refresh Tokens for extending sessions.
+- **Validation**: Always strictly validate the `exp` (expiration), `iss` (issuer), and `aud` (audience) claims on every request.
+
+## 3. Session & Storage Management
+
+- **Web Storage**: Never store JWTs or session IDs in `localStorage` or `sessionStorage` where they are vulnerable to XSS (Cross-Site Scripting) attacks.
+- **Cookies**: Always store session tokens in cookies with strict attributes:
+  - `HttpOnly`: True (prevents JavaScript access)
+  - `Secure`: True (requires HTTPS)
+  - `SameSite`: `Lax` or `Strict` (prevents CSRF)
+- **Invalidation**: Ensure sessions can be revoked on the server side (e.g., via a Redis blocklist or database `sessions` table).
+
+## 4. RBAC (Role-Based Access Control)
+
+- **Defense in Depth**: UI-level checks (e.g., hiding a button) are not security. You MUST enforce authorization at the API/Controller layer.
+- **Middleware**: Implement route-level middleware to protect endpoints.
+- **Ownership Validation**: Beyond checking if a user is an "admin" or "user", always verify that the user _owns_ the specific resource they are trying to access (e.g., `WHERE user_id = ?`).
+
+## 5. Common Providers (NextAuth, Clerk, Auth0)
+
+- **NextAuth / Auth.js**: Keep the secret strictly in `.env.local`. Do not expose the secret to the client.
+- **Clerk**: Use the Clerk middleware to protect routes. Ensure the publishable key is public, but the secret key remains on the server.
+- **Auth0**: Validate the Auth0 domain and audience strictly in your SDK configuration.

package/skills/autonomous-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autonomous-dev
-description: Harness for autonomous software development. Enforces lifecycle through alignment gates (PROJECT.md), adversarial generator/evaluator agents, CI/CD pipeline automation, and strict Git workflows (Conventional Commits, Branching).
+description: Harness for autonomous software development. Use when fixing or remediating known issues (including security vulnerabilities). Enforces lifecycle through alignment gates (PROJECT.md), adversarial generator/evaluator agents, and autonomous orchestration of project issues. NOT for setting up standalone CI/CD pipelines.
 ---
 
 # Autonomous Development Workflow
@@ -9,13 +9,19 @@ This skill provides a deterministic software engineering harness, designed to wr
 
 ## 1. Project Alignment Gate (PROJECT.md)
 
-Before beginning implementation, you MUST cross-reference the proposed feature against `PROJECT.md` at the repository root.
+Before beginning implementation, you MUST cross-reference the proposed feature against `PROJECT.md` at the repository root. If `PROJECT.md` is missing, ask the user to clarify the project goals or constraints before proceeding.
 
-- **In-Scope**: Proceed with confidence.
+- **In-Scope**: Confirm the feature directly serves a goal in `PROJECT.md`. Proceed.
 - **Out-of-Scope**: Hard block. Halt work immediately and inform the user.
 - **Constraints**: Abide strictly by the constraints (language, architecture, dependencies) defined in the project file.
 
-## 2. Generator / Evaluator Pipeline
+## 2. Security Safety Nets
+
+- **Execution Sandboxing**: Never run unknown or unverified shell scripts directly. Execute isolated tasks within the `tmp/` scratch directory.
+- **Secret Protection**: Check for exposed credentials or PII in diffs before committing. Never commit `.env`.
+- **Command Gates**: Do not execute destructive commands (`rm -rf`, `git reset --hard`) without explicit Human-in-the-Loop approval.
+
+## 3. Generator / Evaluator Pipeline
 
 Features cannot simply be written and committed. They must navigate a rigid pipeline based on the adversarial evaluation pattern:
 
@@ -27,26 +33,9 @@ Features cannot simply be written and committed. They must navigate a rigid pipe
 5. **Adversarial Review**: Self-evaluate the code as a skeptical reviewer (evaluator). Actively search for edge cases, security vulnerabilities, efficiency loss, and anti-patterns.
 6. **Documentation**: Ensure docs stay tightly in sync with the codebase after the feature clears CI.
 
-## 3. Git Workflow & Versioning
-
-Enforce strict version control standards on all changes:
-
-- **Branching**: Use feature branches (`feature/my-feature`), bugfix branches (`fix/bug-name`), or standard trunk-based branching flows depending on the repository context.
-- **Atomic Commits**: Group distinct changes into smaller, logical, single-purpose commits. Do not lump refactoring with new logic.
-- **Conventional Commits**: You MUST format all commits according to the Conventional Commits specification:
-  - `feat: <description>` for new features (MINOR bump)
-  - `fix: <description>` for bug fixes (PATCH bump)
-  - `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `build:`, `ci:`, `chore:` for specific maintenance scopes.
-  - Suffix `!` for breaking changes (e.g., `feat!: remove API v1`) (MAJOR bump).
+## 4. Workflow Orchestration
 
-## 4. Continuous Integration/Deployment (CI/CD)
-
-When designing automation and pipelines:
-
-- **GitHub Actions First**: Prioritize GitHub Actions for CI/CD pipeline orchestration, favoring Reusable Workflows and matrix builds.
-- **Validation Blocks**: Every PR or merge MUST require passing lint, test, and type-check gates.
-- **Automation Constraints**: Automate Semantic Versioning (using conventional commits) to power automated release notes and changelog generation.
-- **Security Scans**: Mandate security scanning (e.g. CodeQL, Trivy) on standard PR flows.
+Follow strict version control (Conventional Commits, atomic commits) and CI/CD automation rules. Test code locally before creating PRs.
 
 ## 5. Context Management & Drift Prevention
 
@@ -54,3 +43,37 @@ As the context window fills up, context anxiety can degrade performance.
 
 - Recognize when the session has spanned too many features or files (e.g., beyond 4-5 features).
 - Use session summaries or persistent memories to bookmark state, clear the context, and resume with a fresh perspective.
+
+## 6. Output Templates
+
+**Generator Plan Output:**
+
+```markdown
+### Feature Plan: [Feature Name]
+
+**Scope:** [In-Scope/Out-of-Scope based on PROJECT.md]
+**Constraints:** [Key constraints to respect]
+**Acceptance Criteria:**
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+```
+
+**Evaluator Review Output:**
+
+```markdown
+### Adversarial Review: [Feature Name]
+
+**Pass/Fail:** [Result]
+**Security Risks:** [Identified risks or "None"]
+**Edge Cases Missed:** [Edge cases]
+**Required Fixes:** [List of fixes before proceeding]
+```
+
+## Synergies
+
+| Skill/Workflow         | Relationship                                                                     |
+| ---------------------- | -------------------------------------------------------------------------------- |
+| `github-commander`     | Complementary — handles issue orchestration while this handles the dev lifecycle |
+| `adversarial-planner`  | Can be used during the Planning phase of the Generator pipeline                  |
+| `adversarial-security` | Can be used during the Evaluator phase                                           |

package/skills/autonomous-dev/references/workflow_orchestration.md

@@ -0,0 +1,22 @@
+# Workflow Orchestration
+
+## Git Workflow & Versioning
+
+Enforce strict version control standards on all changes:
+
+- **Branching**: Use feature branches (`feature/my-feature`), bugfix branches (`fix/bug-name`), or standard trunk-based branching flows depending on the repository context.
+- **Atomic Commits**: Group distinct changes into smaller, logical, single-purpose commits. Do not lump refactoring with new logic.
+- **Conventional Commits**: You MUST format all commits according to the Conventional Commits specification:
+  - `feat: <description>` for new features (MINOR bump)
+  - `fix: <description>` for bug fixes (PATCH bump)
+  - `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `build:`, `ci:`, `chore:` for specific maintenance scopes.
+  - Suffix `!` for breaking changes (e.g., `feat!: remove API v1`) (MAJOR bump).
+
+## Continuous Integration/Deployment (CI/CD)
+
+When designing automation and pipelines:
+
+- **GitHub Actions First**: Prioritize GitHub Actions for CI/CD pipeline orchestration, favoring Reusable Workflows and matrix builds.
+- **Validation Blocks**: Every PR or merge MUST require passing lint, test, and type-check gates.
+- **Automation Constraints**: Automate Semantic Versioning (using conventional commits) to power automated release notes and changelog generation.
+- **Security Scans**: Mandate security scanning (e.g. CodeQL, Trivy) on standard PR flows.

package/skills/aws/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: aws
+description: |
+  Comprehensive AWS (Amazon Web Services) best practices and infrastructure guidelines. Use when deploying to AWS, writing CloudFormation/CDK/Terraform for AWS, configuring IAM permissions, S3 buckets, EC2 instances, Lambda functions, or ECS/EKS clusters. Do NOT trigger for generic "deploy my app" requests without clarifying the target platform.
+---
+
+# Amazon Web Services (AWS) Best Practices
+
+**STOP.** Your knowledge of AWS may be outdated. Prefer retrieval over pre-training for any version-sensitive AWS configuration. Fetch current documentation when in doubt.
+
+Production-grade standards for designing, deploying, and managing infrastructure on AWS.
+
+## 1. Security & IAM (Identity and Access Management)
+
+- **Principle of Least Privilege (PoLP)**: Never use `*` (wildcard) actions or resources in IAM policies unless absolutely required (e.g., specific S3 list actions). Scope policies to specific ARNs and exact actions.
+- **Root Account**: Never use the root account for day-to-day operations. Use AWS SSO (IAM Identity Center) or assume roles.
+- **Secrets Management**: Never hardcode secrets in code or environment variables attached to instances. Always use **AWS Secrets Manager** or **AWS Systems Manager Parameter Store (SSM)**.
+
+## 2. Serverless (Lambda & API Gateway)
+
+- **Cold Starts**: Minimize cold starts in Lambda by keeping deployment packages small. For Node.js/TypeScript, use tools like `esbuild` to bundle and tree-shake code.
+- **Concurrency**: Set reserved concurrency for critical functions to ensure they always have execution capacity.
+- **Idempotency**: Lambda functions should be idempotent, especially when triggered by SQS, SNS, or EventBridge, as AWS guarantees at-least-once delivery (not exactly-once).
+
+## 3. Storage & Databases (S3, DynamoDB, RDS)
+
+- **S3 Security**: ALWAYS enable "Block Public Access" at the bucket level unless serving a static website. Enforce server-side encryption (`AES256` or `aws:kms`).
+- **DynamoDB**: Prefer single-table design when access patterns are strictly known. Use On-Demand capacity for unpredictable workloads and Provisioned capacity (with Auto Scaling) for predictable workloads to save costs.
+- **RDS**: Never place RDS instances in public subnets. They must reside in private subnets, accessed via Bastion Hosts, VPN, or Session Manager.
+
+## 4. Networking (VPC)
+
+- **Multi-AZ**: Always deploy critical resources (NAT Gateways, RDS, ALB, ECS) across at least two Availability Zones for high availability.
+- **Security Groups**: Security Groups are stateful. Only allow necessary inbound ports (e.g., 443 for HTTPS). Do not open `0.0.0.0/0` on port 22 or 3306.
+
+## 5. Infrastructure as Code (IaC)
+
+- **Tooling**: Prefer AWS CDK or Terraform over raw CloudFormation templates.
+- **Immutability**: Never make manual changes in the AWS Console (ClickOps). All infrastructure changes must be codified, reviewed, and deployed via CI/CD.

package/skills/azure/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: azure
+description: |
+  Microsoft Azure best practices. Use when deploying to Azure App Service, Azure Functions, AKS (Azure Kubernetes Service), Cosmos DB, configuring Azure Entra ID (Active Directory), or managing Azure Resource Manager (ARM/Bicep) templates. Do NOT trigger for generic "deploy my app" requests without clarifying the target platform.
+---
+
+# Microsoft Azure Best Practices
+
+**STOP.** Your knowledge of Azure may be outdated. Prefer retrieval over pre-training for any version-sensitive Azure configuration. Fetch current documentation when in doubt.
+
+Standards for deploying and managing workloads securely on Microsoft Azure.
+
+## 1. Identity & Access (Azure Entra ID / Active Directory)
+
+- **Managed Identities**: Use System-Assigned or User-Assigned Managed Identities for Azure resources (VMs, App Services, Functions) to authenticate to other Azure services (Key Vault, SQL, Storage) without managing credentials.
+- **RBAC**: Use Azure Role-Based Access Control. Assign roles to Entra ID Groups rather than individual users to simplify lifecycle management.
+- **Key Vault**: Never store secrets in application configuration files. Store them in Azure Key Vault and reference them using Key Vault References in App Services/Functions.
+
+## 2. Compute (App Service, Functions, AKS)
+
+- **Azure Functions**: For production serverless, use the Premium plan to avoid cold starts and gain VNet integration capabilities, unless strict cost minimization on the Consumption plan is required.
+- **AKS (Azure Kubernetes Service)**: Use Azure CNI for advanced networking. Enable Microsoft Entra ID integration for Kubernetes RBAC. Use Azure Policy to enforce pod security standards.
+- **App Service**: Enable VNet Integration to access private resources. Turn on "Always On" (Basic tier and above) to prevent the worker process from idling out.
+
+## 3. Data (Cosmos DB, Azure SQL, Storage)
+
+- **Cosmos DB**: Carefully choose the Partition Key, as it determines scalability and performance. Changes to the partition key require data migration.
+- **Azure SQL Database**: Enable Transparent Data Encryption (TDE). Use Private Endpoints (Azure Private Link) to ensure database traffic never traverses the public internet.
+- **Storage Accounts**: Disable public network access on Storage Accounts. Use Shared Access Signatures (SAS) with short expiration times for temporary client access to blobs.
+
+## 4. Networking & Security
+
+- **Virtual Networks (VNet)**: Implement a Hub-and-Spoke topology for enterprise deployments. Use Azure Firewall in the hub and Network Security Groups (NSGs) on the spokes.
+- **Front Door / App Gateway**: Use Azure Front Door for global load balancing and WAF. Use Application Gateway for regional layer-7 load balancing.
+
+## 5. Infrastructure as Code (IaC)
+
+- **Bicep & Terraform**: Prefer Bicep (Azure's native declarative DSL) or Terraform over verbose JSON ARM templates.

package/skills/bin/sync.js

@@ -38,7 +38,13 @@ for (const item of items) {
     const targetPath = path.join(targetDir, item)
 
     if (fs.statSync(sourcePath).isDirectory()) {
-        fs.cpSync(sourcePath, targetPath, { recursive: true })
+        fs.cpSync(sourcePath, targetPath, {
+            recursive: true,
+            filter: (src) => {
+                const base = path.basename(src)
+                return base !== 'node_modules' && base !== 'package-lock.json'
+            },
+        })
         console.log(`  \x1b[32m\u2714\x1b[0m ${item}`)
         count++
     }

package/skills/biome/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: biome
+description: |
+  Biome formatting and linting standards. Use when configuring Biome (biome.json) for fast formatting, linting, and sorting imports. NOT for Prettier or ESLint configuration. Do NOT trigger for generic formatting/linting tasks unless Biome is explicitly requested.
+---
+
+# Biome Guidelines
+
+Biome is a high-performance toolchain for web projects, intended to replace Prettier and ESLint in modern codebases.
+
+## 1. Configuration (`biome.json`)
+
+- **Single Config**: Define all rules in a unified `biome.json` at the root of the project.
+- **Formatting Match**: Configure Biome's formatter to match standard Prettier settings (e.g., `lineWidth: 80`, `indentStyle: "space"`).
+- **Import Sorting**: Enable `organizeImports` to automatically sort and group imports on save.
+
+```json
+{
+  "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json",
+  "formatter": {
+    "enabled": true,
+    "formatWithErrors": false,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "style": {
+        "useImportType": "error"
+      }
+    }
+  }
+}
+```
+
+## 2. CI/CD Integration
+
+- **Check Command**: Run `npx @biomejs/biome ci .` in CI pipelines. This command checks formatting, runs the linter, and verifies import sorting all in one pass. It fails if any violations are found.
+- **Pre-commit Hooks**: Integrate `biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}` into Husky/lint-staged to format code before committing.
+
+## 3. Editor Integration
+
+- **VS Code**: Ensure the `.vscode/settings.json` sets Biome as the default formatter and enables "format on save" and "organize imports on save".
+
+```json
+{
+  "editor.defaultFormatter": "biomejs.biome",
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports.biome": "explicit"
+  }
+}
+```

package/skills/bun/SKILL.md

@@ -1,6 +1,9 @@
 ---
-title: Bun Development
-description: Master the Bun all-in-one toolkit — runtime, package manager, test runner, and bundler.
+name: bun
+description: |
+  Master the Bun all-in-one toolkit — runtime, package manager, test runner, and bundler.
+  Use when writing, running, testing, or bundling TypeScript/JavaScript with Bun.
+  Triggers on "bun", "bunx", "bun install", "bun test", "bun run". If the user asks to 'write tests' without specifying the type, you MUST ask 'Unit, E2E, or both?' before proceeding.
 ---
 
 Bun is a fast, all-in-one JavaScript runtime, bundler, test runner, and package manager designed as a drop-in replacement for Node.js. When working on projects that use Bun, AI agents should leverage its integrated tooling and native APIs to maximize performance and simplify development.
@@ -79,6 +82,9 @@ await Bun.write('data.json', JSON.stringify({ a: 1 }))
 
 Replace `child_process` and `zx` with the native Bun shell (`$`).
 
+> [!CAUTION]
+> **Command Injection Risk**: Never interpolate untrusted user input directly into a `Bun.$` template literal (`Bun.$`echo ${userInput}``) as it operates like `exec()`. Always use array arguments `Bun.$`echo ${["arg1", "arg2"]}` for untrusted data.
+
 ```typescript
 import { $ } from 'bun'
 

package/skills/cloudflare/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: cloudflare
+description: (GENERIC ROUTING ONLY) General Cloudflare platform skill for infrastructure, storage, and networking. Use when choosing between Cloudflare products (KV vs D1 vs R2) or doing general Cloudflare tasks. NOT for building AI agents (use agents-sdk). NOT for building MCP servers (use mcp-builder). NOT for deploying applications unless Cloudflare is the explicit target platform. Do NOT use for code-reviewing Workers (use workers-best-practices instead) or for CLI deployment/management (use wrangler instead). NOT for orchestrating CI/CD pipelines (use github-actions instead). NOT for AWS, GCP, Azure, Render, or generic container deployment. Use specific skills like `wrangler` or `workers-best-practices` when the task is narrowly scoped.
+references:
+  - workers
+  - pages
+  - d1
+  - durable-objects
+  - workers-ai
+---
+
+# Cloudflare Platform Skill
+
+Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.
+
+Your knowledge of Cloudflare APIs, types, limits, and pricing may be outdated. **Prefer retrieval over pre-training** — the references in this skill are starting points, not source of truth.
+
+## Retrieval Sources
+
+Fetch the **latest** information before citing specific numbers, API signatures, or configuration options. Do not rely on baked-in knowledge or these reference files alone.
+
+| Source                 | How to retrieve                                                       | Use for                                                   |
+| ---------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
+| Cloudflare docs        | `cloudflare-docs` search tool or `https://developers.cloudflare.com/` | Limits, pricing, API reference, compatibility dates/flags |
+| Workers types          | `npm pack @cloudflare/workers-types` or check `node_modules`          | Type signatures, binding shapes, handler types            |
+| Wrangler config schema | `node_modules/wrangler/config-schema.json`                            | Config fields, binding shapes, allowed values             |
+| Product changelogs     | `https://developers.cloudflare.com/changelog/`                        | Recent changes to limits, features, deprecations          |
+
+When a reference file and the docs disagree, **trust the docs**. This is especially important for: numeric limits, pricing tiers, type signatures, and configuration options.
+
+## Quick Decision Trees
+
+See **[decision-trees.md](references/decision-trees.md)** for routing logic across Cloudflare's product suite (compute, storage, AI, networking, security, etc.).
+
+## Product Index
+
+See [references/product-index.md](references/product-index.md) for the full mapping of Cloudflare products to their reference paths.

package/skills/cloudflare/references/agents-sdk/README.md

@@ -0,0 +1,95 @@
+# Cloudflare Agents SDK
+
+Cloudflare Agents SDK enables building AI-powered agents on Durable Objects with state, WebSockets, SQL, scheduling, and AI integration.
+
+## Core Value
+
+Build stateful, globally distributed AI agents with persistent memory, real-time connections, scheduled tasks, and async workflows.
+
+## When to Use
+
+- Persistent state + memory required
+- Real-time WebSocket connections
+- Long-running workflows (minutes/hours)
+- Chat interfaces with AI models
+- Scheduled/recurring tasks with state
+- DB queries with agent state
+
+## What Type of Agent?
+
+| Use Case                | Class         | Key Features                                      |
+| ----------------------- | ------------- | ------------------------------------------------- |
+| AI chat interface       | `AIChatAgent` | Auto-streaming, tools, message history, resumable |
+| MCP tool provider       | `Agent` + MCP | Expose tools to AI systems                        |
+| Custom logic/routing    | `Agent`       | Full control, WebSockets, email, SQL              |
+| Real-time collaboration | `Agent`       | WebSocket state, broadcasts                       |
+| Email processing        | `Agent`       | `onEmail()` handler                               |
+
+## Quick Start
+
+**AI Chat Agent:**
+
+```typescript
+import { AIChatAgent } from 'agents'
+import { openai } from '@ai-sdk/openai'
+
+export class ChatAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    return this.streamText({
+      model: openai('gpt-4'),
+      messages: this.messages,
+      onFinish,
+    })
+  }
+}
+```
+
+**Base Agent:**
+
+```typescript
+import { Agent } from 'agents'
+
+export class MyAgent extends Agent<Env> {
+  onStart() {
+    this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY)`
+  }
+
+  async onRequest(request: Request) {
+    return Response.json({ state: this.state })
+  }
+}
+```
+
+## Reading Order
+
+| Task               | Files to Read                                 |
+| ------------------ | --------------------------------------------- |
+| Quick start        | README only                                   |
+| Build chat agent   | README → api.md (AIChatAgent) → patterns.md   |
+| Setup project      | README → configuration.md                     |
+| Add React frontend | README → api.md (Client Hooks) → patterns.md  |
+| Build MCP server   | api.md (MCP) → patterns.md                    |
+| Background tasks   | api.md (Scheduling, Task Queue) → patterns.md |
+| Debug issues       | gotchas.md                                    |
+
+## Package Entry Points
+
+| Import            | Purpose                                     |
+| ----------------- | ------------------------------------------- |
+| `agents`          | Server-side Agent classes, lifecycle        |
+| `agents/react`    | `useAgent()` hook for WebSocket connections |
+| `agents/ai-react` | `useAgentChat()` hook for AI chat UIs       |
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - SDK setup, wrangler config, routing
+- [api.md](./api.md) - Agent classes, lifecycle, client hooks
+- [patterns.md](./patterns.md) - Common workflows, best practices
+- [gotchas.md](./gotchas.md) - Common issues, limits
+
+## See Also
+
+- durable-objects - Agent infrastructure
+- d1 - External database integration
+- workers-ai - AI model integration
+- vectorize - Vector search for RAG patterns