@ngxtm/devkit 3.7.0 → 3.8.0

package/merged-commands/cloudflare-expert.md

@@ -0,0 +1,227 @@
+---
+name: cloudflare-expert
+description: Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use PROACTIVELY for any Cloudflare development task.
+---
+
+# Cloudflare Platform Skill
+
+Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.
+
+## How to Use This Skill
+
+### Reference File Structure
+
+Each product in `./references/<product>/` contains a `README.md` as the entry point, which may be structured in one of two ways:
+
+**Multi-file format (5 files):**
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `README.md` | Overview, when to use, getting started | **Always read first** |
+| `api.md` | Runtime API, types, method signatures | Writing code |
+| `configuration.md` | wrangler.toml, bindings, setup | Configuring a project |
+| `patterns.md` | Common patterns, best practices | Implementation guidance |
+| `gotchas.md` | Pitfalls, limitations, edge cases | Debugging, avoiding mistakes |
+
+**Single-file format:** All information consolidated in `README.md`.
+
+### Reading Order
+
+1. Start with `README.md`
+2. Then read additional files relevant to your task (if multi-file format):
+   - Building feature → `api.md` + `patterns.md`
+   - Setting up project → `configuration.md`
+   - Troubleshooting → `gotchas.md`
+
+### Example Paths
+
+```
+./references/workflows/README.md         # Start here for Workflows
+./references/workflows/api.md            # Workflow class, step methods
+./references/durable-objects/gotchas.md  # DO limitations
+./references/workers-ai/README.md        # Single-file - all Workers AI docs
+```
+
+## Quick Decision Trees
+
+### "I need to run code"
+
+```
+Need to run code?
+├─ Serverless functions at the edge → workers/
+├─ Full-stack web app with Git deploys → pages/
+├─ Stateful coordination/real-time → durable-objects/
+├─ Long-running multi-step jobs → workflows/
+├─ Run containers → containers/
+├─ Multi-tenant (customers deploy code) → workers-for-platforms/
+└─ Scheduled tasks (cron) → cron-triggers/
+```
+
+### "I need to store data"
+
+```
+Need storage?
+├─ Key-value (config, sessions, cache) → kv/
+├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
+├─ Object/file storage (S3-compatible) → r2/
+├─ Message queue (async processing) → queues/
+├─ Vector embeddings (AI/semantic search) → vectorize/
+├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
+├─ Secrets management → secrets-store/
+└─ Streaming ETL to R2 → pipelines/
+```
+
+### "I need AI/ML"
+
+```
+Need AI?
+├─ Run inference (LLMs, embeddings, images) → workers-ai/
+├─ Vector database for RAG/search → vectorize/
+├─ Build stateful AI agents → agents-sdk/
+├─ Gateway for any AI provider (caching, routing) → ai-gateway/
+└─ AI-powered search widget → ai-search/
+```
+
+### "I need networking/connectivity"
+
+```
+Need networking?
+├─ Expose local service to internet → tunnel/
+├─ TCP/UDP proxy (non-HTTP) → spectrum/
+├─ WebRTC TURN server → turn/
+├─ Private network connectivity → network-interconnect/
+├─ Optimize routing → argo-smart-routing/
+└─ Real-time video/audio → realtimekit/ or realtime-sfu/
+```
+
+### "I need security"
+
+```
+Need security?
+├─ Web Application Firewall → waf/
+├─ DDoS protection → ddos/
+├─ Bot detection/management → bot-management/
+├─ API protection → api-shield/
+├─ CAPTCHA alternative → turnstile/
+└─ Credential leak detection → waf/ (managed ruleset)
+```
+
+### "I need media/content"
+
+```
+Need media?
+├─ Image optimization/transformation → images/
+├─ Video streaming/encoding → stream/
+├─ Browser automation/screenshots → browser-rendering/
+└─ Third-party script management → zaraz/
+```
+
+### "I need infrastructure-as-code"
+
+```
+Need IaC?
+├─ Pulumi → pulumi/
+├─ Terraform → terraform/
+└─ Direct API → api/
+```
+
+## Product Index
+
+### Compute & Runtime
+| Product | Entry File |
+|---------|------------|
+| Workers | `./references/workers/README.md` |
+| Pages | `./references/pages/README.md` |
+| Pages Functions | `./references/pages-functions/README.md` |
+| Durable Objects | `./references/durable-objects/README.md` |
+| Workflows | `./references/workflows/README.md` |
+| Containers | `./references/containers/README.md` |
+| Workers for Platforms | `./references/workers-for-platforms/README.md` |
+| Cron Triggers | `./references/cron-triggers/README.md` |
+| Tail Workers | `./references/tail-workers/README.md` |
+| Snippets | `./references/snippets/README.md` |
+| Smart Placement | `./references/smart-placement/README.md` |
+
+### Storage & Data
+| Product | Entry File |
+|---------|------------|
+| KV | `./references/kv/README.md` |
+| D1 | `./references/d1/README.md` |
+| R2 | `./references/r2/README.md` |
+| Queues | `./references/queues/README.md` |
+| Hyperdrive | `./references/hyperdrive/README.md` |
+| DO Storage | `./references/do-storage/README.md` |
+| Secrets Store | `./references/secrets-store/README.md` |
+| Pipelines | `./references/pipelines/README.md` |
+| R2 Data Catalog | `./references/r2-data-catalog/README.md` |
+| R2 SQL | `./references/r2-sql/README.md` |
+
+### AI & Machine Learning
+| Product | Entry File |
+|---------|------------|
+| Workers AI | `./references/workers-ai/README.md` |
+| Vectorize | `./references/vectorize/README.md` |
+| Agents SDK | `./references/agents-sdk/README.md` |
+| AI Gateway | `./references/ai-gateway/README.md` |
+| AI Search | `./references/ai-search/README.md` |
+
+### Networking & Connectivity
+| Product | Entry File |
+|---------|------------|
+| Tunnel | `./references/tunnel/README.md` |
+| Spectrum | `./references/spectrum/README.md` |
+| TURN | `./references/turn/README.md` |
+| Network Interconnect | `./references/network-interconnect/README.md` |
+| Argo Smart Routing | `./references/argo-smart-routing/README.md` |
+| Workers VPC | `./references/workers-vpc/README.md` |
+
+### Security
+| Product | Entry File |
+|---------|------------|
+| WAF | `./references/waf/README.md` |
+| DDoS Protection | `./references/ddos/README.md` |
+| Bot Management | `./references/bot-management/README.md` |
+| API Shield | `./references/api-shield/README.md` |
+| Turnstile | `./references/turnstile/README.md` |
+
+### Media & Content
+| Product | Entry File |
+|---------|------------|
+| Images | `./references/images/README.md` |
+| Stream | `./references/stream/README.md` |
+| Browser Rendering | `./references/browser-rendering/README.md` |
+| Zaraz | `./references/zaraz/README.md` |
+
+### Real-Time Communication
+| Product | Entry File |
+|---------|------------|
+| RealtimeKit | `./references/realtimekit/README.md` |
+| Realtime SFU | `./references/realtime-sfu/README.md` |
+
+### Developer Tools
+| Product | Entry File |
+|---------|------------|
+| Wrangler | `./references/wrangler/README.md` |
+| Miniflare | `./references/miniflare/README.md` |
+| C3 | `./references/c3/README.md` |
+| Observability | `./references/observability/README.md` |
+| Analytics Engine | `./references/analytics-engine/README.md` |
+| Web Analytics | `./references/web-analytics/README.md` |
+| Sandbox | `./references/sandbox/README.md` |
+| Workerd | `./references/workerd/README.md` |
+| Workers Playground | `./references/workers-playground/README.md` |
+
+### Infrastructure as Code
+| Product | Entry File |
+|---------|------------|
+| Pulumi | `./references/pulumi/README.md` |
+| Terraform | `./references/terraform/README.md` |
+| API | `./references/api/README.md` |
+
+### Other Services
+| Product | Entry File |
+|---------|------------|
+| Email Routing | `./references/email-routing/README.md` |
+| Email Workers | `./references/email-workers/README.md` |
+| Static Assets | `./references/static-assets/README.md` |
+| Bindings | `./references/bindings/README.md` |
+| Cache Reserve | `./references/cache-reserve/README.md` |

package/merged-commands/code-documentation-code-explain.md

@@ -0,0 +1,46 @@
+---
+name: code-documentation-code-explain
+description: "You are a code education expert specializing in explaining complex code through clear narratives, visual diagrams, and step-by-step breakdowns. Transform difficult concepts into understandable explanations."
+---
+
+# Code Explanation and Analysis
+
+You are a code education expert specializing in explaining complex code through clear narratives, visual diagrams, and step-by-step breakdowns. Transform difficult concepts into understandable explanations for developers at all levels.
+
+## Use this skill when
+
+- Explaining complex code, algorithms, or system behavior
+- Creating onboarding walkthroughs or learning materials
+- Producing step-by-step breakdowns with diagrams
+- Teaching patterns or debugging reasoning
+
+## Do not use this skill when
+
+- The request is to implement new features or refactors
+- You only need API docs or user documentation
+- There is no code or design to analyze
+
+## Context
+The user needs help understanding complex code sections, algorithms, design patterns, or system architectures. Focus on clarity, visual aids, and progressive disclosure of complexity to facilitate learning and onboarding.
+
+## Requirements
+$ARGUMENTS
+
+## Instructions
+
+- Assess structure, dependencies, and complexity hotspots.
+- Explain the high-level flow, then drill into key components.
+- Use diagrams, pseudocode, or examples when useful.
+- Call out pitfalls, edge cases, and key terminology.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Output Format
+
+- High-level summary of purpose and flow
+- Step-by-step walkthrough of key parts
+- Diagram or annotated snippet when helpful
+- Pitfalls, edge cases, and suggested next steps
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed examples and templates.

package/merged-commands/code-documentation-doc-generate.md

@@ -0,0 +1,48 @@
+---
+name: code-documentation-doc-generate
+description: "You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user guides, and technical references using AI-powered analysis and industry best practices."
+---
+
+# Automated Documentation Generation
+
+You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user guides, and technical references using AI-powered analysis and industry best practices.
+
+## Use this skill when
+
+- Generating API, architecture, or user documentation from code
+- Building documentation pipelines or automation
+- Standardizing docs across a repository
+
+## Do not use this skill when
+
+- The project has no codebase or source of truth
+- You only need ad-hoc explanations
+- You cannot access code or requirements
+
+## Context
+The user needs automated documentation generation that extracts information from code, creates clear explanations, and maintains consistency across documentation types. Focus on creating living documentation that stays synchronized with code.
+
+## Requirements
+$ARGUMENTS
+
+## Instructions
+
+- Identify required doc types and target audiences.
+- Extract information from code, configs, and comments.
+- Generate docs with consistent terminology and structure.
+- Add automation (linting, CI) and validate accuracy.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Safety
+
+- Avoid exposing secrets, internal URLs, or sensitive data in docs.
+
+## Output Format
+
+- Documentation plan and artifacts to generate
+- File paths and tooling configuration
+- Assumptions, gaps, and follow-up tasks
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed examples and templates.

package/merged-commands/code-documentation.md

@@ -0,0 +1,263 @@
+---
+name: code-documentation
+description: Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
+source: wshobson/agents
+license: MIT
+---
+
+# Code Documentation
+
+## README Structure
+
+### Standard README Template
+```markdown
+# Project Name
+
+Brief description of what this project does.
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Installation
+
+Detailed installation instructions...
+
+## Usage
+
+\`\`\`typescript
+import { something } from 'project';
+
+// Example usage
+const result = something.doThing();
+\`\`\`
+
+## API Reference
+
+### `functionName(param: Type): ReturnType`
+
+Description of what the function does.
+
+**Parameters:**
+- `param` - Description of parameter
+
+**Returns:** Description of return value
+
+**Example:**
+\`\`\`typescript
+const result = functionName('value');
+\`\`\`
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option1` | `string` | `'default'` | What it does |
+
+## Contributing
+
+How to contribute...
+
+## License
+
+MIT
+```
+
+## API Documentation
+
+### JSDoc/TSDoc Style
+```typescript
+/**
+ * Creates a new user account.
+ *
+ * @param userData - The user data for account creation
+ * @param options - Optional configuration
+ * @returns The created user object
+ * @throws {ValidationError} If email is invalid
+ * @example
+ * ```ts
+ * const user = await createUser({
+ *   email: 'user@example.com',
+ *   name: 'John'
+ * });
+ * ```
+ */
+async function createUser(
+  userData: UserInput,
+  options?: CreateOptions
+): Promise<User> {
+  // Implementation
+}
+
+/**
+ * Configuration options for the API client.
+ */
+interface ClientConfig {
+  /** The API base URL */
+  baseUrl: string;
+  /** Request timeout in milliseconds @default 5000 */
+  timeout?: number;
+  /** Custom headers to include in requests */
+  headers?: Record<string, string>;
+}
+```
+
+### OpenAPI/Swagger
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+
+paths:
+  /users:
+    post:
+      summary: Create a user
+      description: Creates a new user account
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserInput'
+      responses:
+        '201':
+          description: User created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        '400':
+          description: Invalid input
+
+components:
+  schemas:
+    UserInput:
+      type: object
+      required:
+        - email
+        - name
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+        name:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+```
+
+## Inline Comments
+
+### When to Comment
+```typescript
+// GOOD: Explain WHY, not WHAT
+
+// Use binary search because the list is always sorted and
+// can contain millions of items - O(log n) vs O(n)
+const index = binarySearch(items, target);
+
+// GOOD: Explain complex business logic
+// Users get 20% discount if they've been members for 2+ years
+// AND have made 10+ purchases (per marketing team decision Q4 2024)
+if (user.memberYears >= 2 && user.purchaseCount >= 10) {
+  applyDiscount(0.2);
+}
+
+// GOOD: Document workarounds
+// HACK: Safari doesn't support this API, fallback to polling
+// TODO: Remove when Safari adds support (tracking: webkit.org/b/12345)
+if (!window.IntersectionObserver) {
+  startPolling();
+}
+```
+
+### When NOT to Comment
+```typescript
+// BAD: Stating the obvious
+// Increment counter by 1
+counter++;
+
+// BAD: Explaining clear code
+// Check if user is admin
+if (user.role === 'admin') { ... }
+
+// BAD: Outdated comments (worse than no comment)
+// Returns the user's full name  <-- Actually returns email now!
+function getUserIdentifier(user) {
+  return user.email;
+}
+```
+
+## Architecture Documentation
+
+### ADR (Architecture Decision Record)
+```markdown
+# ADR-001: Use PostgreSQL for Primary Database
+
+## Status
+Accepted
+
+## Context
+We need a database for storing user data and transactions.
+Options considered: PostgreSQL, MySQL, MongoDB, DynamoDB.
+
+## Decision
+Use PostgreSQL with Supabase hosting.
+
+## Rationale
+- Strong ACID compliance needed for financial data
+- Team has PostgreSQL experience
+- Supabase provides auth and realtime features
+- pgvector extension for future AI features
+
+## Consequences
+- Need to manage schema migrations
+- May need read replicas for scale
+- Team needs to learn Supabase-specific features
+```
+
+### Component Documentation
+```markdown
+## Authentication Module
+
+### Overview
+Handles user authentication using JWT tokens with refresh rotation.
+
+### Flow
+1. User submits credentials to `/auth/login`
+2. Server validates and returns access + refresh tokens
+3. Access token used for API requests (15min expiry)
+4. Refresh token used to get new access token (7d expiry)
+
+### Dependencies
+- `jsonwebtoken` - Token generation/validation
+- `bcrypt` - Password hashing
+- `redis` - Refresh token storage
+
+### Configuration
+- `JWT_SECRET` - Secret for signing tokens
+- `ACCESS_TOKEN_EXPIRY` - Access token lifetime
+- `REFRESH_TOKEN_EXPIRY` - Refresh token lifetime
+```
+
+## Documentation Principles
+
+1. **Write for your audience** - New devs vs API consumers
+2. **Keep it close to code** - Docs in same repo, near relevant code
+3. **Update with code** - Stale docs are worse than none
+4. **Examples over explanations** - Show, don't just tell
+5. **Progressive disclosure** - Quick start first, details later

package/merged-commands/code-documenter.md

@@ -0,0 +1,95 @@
+---
+name: code-documenter
+description: Use when adding docstrings, creating API documentation, or building documentation sites. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, tutorials, user guides.
+triggers:
+  - documentation
+  - docstrings
+  - OpenAPI
+  - Swagger
+  - JSDoc
+  - comments
+  - API docs
+  - tutorials
+  - user guides
+  - doc site
+role: specialist
+scope: implementation
+output-format: code
+---
+
+# Code Documenter
+
+Documentation specialist for inline documentation, API specs, documentation sites, and developer guides.
+
+## Role Definition
+
+You are a senior technical writer with 8+ years of experience documenting software. You specialize in language-specific docstring formats, OpenAPI/Swagger specifications, interactive documentation portals, static site generation, and creating comprehensive guides that developers actually use.
+
+## When to Use This Skill
+
+- Adding docstrings to functions and classes
+- Creating OpenAPI/Swagger documentation
+- Building documentation sites (Docusaurus, MkDocs, VitePress)
+- Documenting APIs with framework-specific patterns
+- Creating interactive API portals (Swagger UI, Redoc, Stoplight)
+- Writing getting started guides and tutorials
+- Documenting multi-protocol APIs (REST, GraphQL, WebSocket, gRPC)
+- Generating documentation reports and coverage metrics
+
+## Core Workflow
+
+1. **Discover** - Ask for format preference and exclusions
+2. **Detect** - Identify language and framework
+3. **Analyze** - Find undocumented code
+4. **Document** - Apply consistent format
+5. **Report** - Generate coverage summary
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Python Docstrings | `references/python-docstrings.md` | Google, NumPy, Sphinx styles |
+| TypeScript JSDoc | `references/typescript-jsdoc.md` | JSDoc patterns, TypeScript |
+| FastAPI/Django API | `references/api-docs-fastapi-django.md` | Python API documentation |
+| NestJS/Express API | `references/api-docs-nestjs-express.md` | Node.js API documentation |
+| Coverage Reports | `references/coverage-reports.md` | Generating documentation reports |
+| Documentation Systems | `references/documentation-systems.md` | Doc sites, static generators, search, testing |
+| Interactive API Docs | `references/interactive-api-docs.md` | OpenAPI 3.1, portals, GraphQL, WebSocket, gRPC, SDKs |
+| User Guides & Tutorials | `references/user-guides-tutorials.md` | Getting started, tutorials, troubleshooting, FAQs |
+
+## Constraints
+
+### MUST DO
+- Ask for format preference before starting
+- Detect framework for correct API doc strategy
+- Document all public functions/classes
+- Include parameter types and descriptions
+- Document exceptions/errors
+- Test code examples in documentation
+- Generate coverage report
+
+### MUST NOT DO
+- Assume docstring format without asking
+- Apply wrong API doc strategy for framework
+- Write inaccurate or untested documentation
+- Skip error documentation
+- Document obvious getters/setters verbosely
+- Create documentation that's hard to maintain
+
+## Output Formats
+
+Depending on the task, provide:
+1. **Code Documentation:** Documented files + coverage report
+2. **API Docs:** OpenAPI specs + portal configuration
+3. **Doc Sites:** Site configuration + content structure + build instructions
+4. **Guides/Tutorials:** Structured markdown with examples + diagrams
+
+## Knowledge Reference
+
+Google/NumPy/Sphinx docstrings, JSDoc, OpenAPI 3.0/3.1, AsyncAPI, gRPC/protobuf, FastAPI, Django, NestJS, Express, GraphQL, Docusaurus, MkDocs, VitePress, Swagger UI, Redoc, Stoplight
+
+## Related Skills
+
+**Spec Miner** - Informs from code analysis | **Fullstack Guardian** - Documents during implementation | **Code Reviewer** - Checks documentation quality