@bffless/skills 1.7.0

package/plugins/bffless/skills/cache-and-storage/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: cache-and-storage
+description: Cache rules for HTTP caching headers, storage backends, API keys for CI/CD, and user roles/permissions
+---
+
+# Cache Rules, Storage & API Keys
+
+## Cache Rules
+
+Docs: https://docs.bffless.app/configuration/cache-rules
+
+Cache rules control HTTP caching headers per path pattern. Rules are evaluated by priority (higher number = evaluated first).
+
+### MCP: Create cache rule
+
+```
+create_cache_rule(
+  projectId: "uuid",
+  pathPattern: "*.js",              // glob pattern
+  name: "JavaScript assets",       // optional display name
+  description: "Cache JS files",   // optional
+  browserMaxAge: 3600,              // Cache-Control max-age (seconds)
+  cdnMaxAge: 86400,                 // s-maxage for CDN (seconds)
+  staleWhileRevalidate: 600,        // stale-while-revalidate window
+  immutable: false,                 // mark as immutable (infinite cache)
+  isEnabled: true,
+  priority: 10                      // higher = evaluated first
+)
+```
+
+### MCP: List cache rules
+
+```
+list_cache_rules(projectId: "uuid")
+```
+
+### MCP: Delete cache rule
+
+```
+delete_cache_rule(id: "uuid")
+```
+
+### Recommended patterns
+
+| Pattern | browserMaxAge | cdnMaxAge | immutable | Use Case |
+|---------|--------------|-----------|-----------|----------|
+| `*.js` | 3600 | 86400 | false | Versioned JS bundles |
+| `*.css` | 3600 | 86400 | false | Stylesheets |
+| `*.png`, `*.jpg`, `*.webp` | 86400 | 604800 | false | Images |
+| `index.html` | 300 | 300 | false | HTML entry point (changes often) |
+| `assets/*` | 31536000 | 31536000 | true | Hashed/fingerprinted assets |
+
+---
+
+## Storage Backends
+
+Docs: https://docs.bffless.app/configuration/storage
+
+BFFLESS supports multiple storage backends for uploaded files:
+
+| Backend | Use Case |
+|---------|----------|
+| **Local** | Development only |
+| **MinIO** | Self-hosted S3-compatible |
+| **AWS S3** | Amazon S3 |
+| **Google Cloud Storage** | GCS (S3 compatibility mode) |
+| **Azure Blob Storage** | Azure |
+
+Storage key format: `{owner}/{repo}/{commitSha}/{path/to/file}`
+
+Configured via `STORAGE_TYPE` environment variable. Credentials are encrypted at rest with AES-256.
+
+---
+
+## API Keys
+
+Docs: https://docs.bffless.app/reference/security
+
+API keys authenticate CI/CD pipelines and programmatic access.
+
+### Types
+
+- **Project-scoped** - Only works for a specific repository (`owner/repo`)
+- **Global** - Works across all projects (admin only)
+
+### MCP: Create API key
+
+```
+create_api_key(
+  name: "GitHub Actions CI",
+  repository: "owner/repo",        // omit for global key
+  isGlobal: false,                  // true for global (admin only)
+  expiresAt: "2027-01-01T00:00:00Z" // optional expiration
+)
+```
+
+Returns the raw key **only once** at creation. Store it securely (e.g., GitHub Actions secret).
+
+### MCP: List API keys
+
+```
+list_api_keys(page?: 1, limit?: 20)
+```
+
+Returns key metadata (name, repository, lastUsedAt, expiresAt) but NOT the raw key.
+
+### MCP: Delete API key
+
+```
+delete_api_key(id: "uuid")
+```
+
+### Usage
+
+API keys are passed via the `X-API-Key` header:
+```
+curl -H "X-API-Key: bff_xxxxxxxxxxxx" https://admin.yourdomain.com/api/...
+```
+
+---
+
+## Users & Roles
+
+### Global roles
+
+| Role | Access |
+|------|--------|
+| `admin` | Full system access, manage users, global API keys |
+| `user` | Create/manage own projects |
+| `member` | Access only granted projects (default for new users) |
+
+### Project roles
+
+| Role | Access |
+|------|--------|
+| `owner` | Full control, delete/transfer project |
+| `admin` | Manage permissions, full CRUD |
+| `contributor` | Create deployments, upload assets |
+| `viewer` | Read-only access |
+
+### MCP: List users
+
+```
+list_users(search?: "email@", role?: "admin", sortBy?: "createdAt", sortOrder?: "desc", page?: 1, limit?: 20)
+```
+
+### MCP: Update user role
+
+```
+update_user_role(id: "user-uuid", role: "admin")   // "admin" | "user"
+```

package/plugins/bffless/skills/chat/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: chat
+description: Adding AI chat to a site with full page or popup widget layouts, skills, streaming, and message persistence
+---
+
+# Chat
+
+**Docs**: https://docs.bffless.app/features/chat/
+
+Add an AI-powered chat experience to any site — no backend code required. Choose between a full page chat interface or a popup widget, give your chatbot domain knowledge with skills, and let BFFless handle streaming, persistence, and deployment.
+
+## Overview
+
+BFFless Chat provides:
+
+- **No backend code** — configure everything through the admin UI
+- **Streaming responses** — real-time token-by-token output via Server-Sent Events
+- **Skills** — domain-specific knowledge from markdown files deployed with your site
+- **Message persistence** — conversations and messages saved automatically to DB Records
+- **A/B testable** — combine with traffic splitting to test different skills or prompts
+- **Two layouts** — full page chat or floating popup widget
+
+## Quick Start
+
+### 1. Generate a Chat Schema
+
+1. Go to **Pipelines → DB Records**
+2. Click **Generate Schema**
+3. Select **Chat Schema**
+4. Enter a name (e.g., `support`)
+5. Choose a scope:
+   - **User-scoped** — conversations tied to authenticated users
+   - **Guest-scoped** — conversations accessible without authentication
+6. Click **Generate**
+
+This creates:
+- A `{name}_conversations` DB Record for conversation metadata
+- A `{name}_messages` DB Record for individual messages
+- A pipeline with a `POST /api/chat` endpoint pre-configured with the AI handler
+
+### 2. Configure an AI Provider
+
+1. Navigate to **Settings → AI**
+2. Select a provider (OpenAI, Anthropic, or Google AI)
+3. Enter your API key
+4. Choose a default model
+5. Click **Test Connection** to verify
+6. Save
+
+### 3. Connect Your Frontend
+
+Use the AI SDK's `useChat` hook:
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+
+function Chat() {
+  const { messages, input, handleInputChange, handleSubmit, status } = useChat({
+    api: '/api/chat',
+  });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.parts.map(p => p.text).join('')}
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} placeholder="Type a message..." />
+        <button type="submit" disabled={status === 'streaming'}>Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+### 4. Deploy
+
+Push your code to GitHub and deploy with the `bffless/upload-artifact` GitHub Action. Your chat endpoint is live as soon as the deployment completes.
+
+## Chat Layouts
+
+### Full Page Chat
+
+A standalone chat page that takes over the full viewport. Includes suggested prompts, real-time streaming with markdown rendering, and a clean conversational UI.
+
+Best for: dedicated support pages, knowledge base assistants, internal tools.
+
+### Popup Widget
+
+A floating chat bubble that opens a slide-up chat panel. Users can start a new conversation or close the widget without losing context. The widget stays accessible on any page.
+
+Best for: landing pages, documentation sites, e-commerce — anywhere you want chat available without dedicating a full page.
+
+## Skills
+
+Skills are markdown files that give your chatbot domain-specific knowledge. Deploy them alongside your site and the AI loads relevant skills on-demand during conversations.
+
+Skills are **versioned with each deployment** — when an alias points to a commit, the skills for that commit are used. This makes them git-managed, rollback-safe, and A/B testable with traffic splitting.
+
+### Creating a Skill
+
+Add a `SKILL.md` file to `.bffless/skills/<skill-name>/`:
+
+```markdown
+---
+name: pricing-faq
+description: Answer questions about pricing, plans, and billing
+---
+
+# Pricing FAQ
+
+(Your knowledge content here in markdown)
+```
+
+### Deploying Skills
+
+Upload skills alongside your build artifacts:
+
+```yaml
+- name: Deploy build
+  uses: bffless/upload-artifact@v1
+  with:
+    source: dist
+
+- name: Deploy skills
+  uses: bffless/upload-artifact@v1
+  with:
+    source: .bffless
+```
+
+### Configuring Skills in Pipelines
+
+Set the skills mode in the AI handler configuration:
+
+| Mode | Description |
+|------|-------------|
+| **None** | Disable all skills (default) |
+| **All** | Enable all uploaded skills |
+| **Selected** | Enable only specific skills by name |
+
+## Message Persistence
+
+When enabled, conversations and messages are automatically saved to DB Records. The handler manages:
+
+- **Conversations**: chat_id, message_count, total_tokens, model
+- **Messages**: conversation_id, role, content, tokens_used
+
+Message persistence is optional — for simple use cases, skip it entirely and chat works without any database configuration.
+
+## Configuration
+
+Key settings for the AI chat handler:
+
+| Setting | Description | Options / Default |
+|---------|-------------|-------------------|
+| **Mode** | Chat or Completion | `chat`, `completion` |
+| **Provider** | AI provider | `openai`, `anthropic`, `google` |
+| **Model** | Specific model | Provider-dependent |
+| **System Prompt** | Instructions for the AI | Free-text |
+| **Response Format** | Stream or JSON | `stream`, `message` |
+| **Skills Mode** | Which skills to enable | `none`, `all`, `selected` |
+| **Temperature** | Response creativity | `0` – `2` (default: `0.7`) |
+| **Max Tokens** | Maximum output length | `256` – `100000` (default: `4096`) |
+| **Max History** | Messages in context | `0` – `200` (default: `50`) |
+
+## Supported Providers
+
+| Provider | Models | Default |
+|----------|--------|---------|
+| OpenAI | gpt-4o, gpt-4-turbo, gpt-4, gpt-4o-mini, gpt-3.5-turbo | gpt-4o |
+| Anthropic | claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5 | claude-sonnet-4-6 |
+| Google AI | gemini-1.5-pro, gemini-1.5-flash, gemini-1.5-flash-8b | gemini-1.5-pro |
+
+## Demo
+
+- Full page chat: https://chat.docs.bffless.app/
+- Popup widget: https://chat.docs.bffless.app/popup/
+- Source code: https://github.com/bffless/demo-chat
+
+## Troubleshooting
+
+**Chat responses not streaming?**
+- Verify response format is set to **Stream (SSE)**
+- Ensure the AI handler is the **last step** in your pipeline
+- Check frontend is using `useChat` from `@ai-sdk/react`
+
+**Skills not loading?**
+- Verify `.bffless/skills/` exists in your deployment
+- Ensure skills mode is set to **All** or **Selected** (not None)
+- Check each skill has valid `SKILL.md` with YAML frontmatter (name and description)
+
+**Messages not persisting?**
+- Ensure **Message Persistence** is enabled in the AI handler config
+- Verify both Conversations Schema and Messages Schema are selected

package/plugins/bffless/skills/pipelines/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: pipelines
+description: Backend automation without code using handler chains
+---
+
+# Pipelines
+
+**Docs**: https://docs.bffless.app/features/pipelines/
+
+Pipelines provide backend functionality for static sites without writing server code. Chain handlers together to process forms, store data, send emails, call AI models, accept payments, and more.
+
+## Handler Types
+
+| Handler | Type | Purpose |
+|---------|------|---------|
+| **Form** | `form_handler` | Parse form submissions (multipart, JSON, URL-encoded) |
+| **Data Create** | `data_create` | Create DB records in a pipeline schema |
+| **Data Query** | `data_query` | Read/list DB records with filters, sorting, pagination |
+| **Data Update** | `data_update` | Update existing DB records |
+| **Data Delete** | `data_delete` | Delete DB records |
+| **Aggregate** | `db_aggregate` | Count/Sum/Avg/Min/Max on data, with optional groupBy for grouped results |
+| **Email** | `email_handler` | Send emails via configured provider |
+| **Response** | `response_handler` | Return custom JSON, status codes, or redirect |
+| **Function** | `function_handler` | Custom JavaScript for transformation/logic |
+| **AI** | `ai_handler` | Call OpenAI/Anthropic/Google AI models (chat or completion) |
+| **HTTP Request** | `http_request` | Make outbound HTTP requests to external APIs |
+| **File Upload** | `file_upload_handler` | Upload files from forms or URLs to storage |
+| **File Serve** | `file_serve_handler` | Serve files from storage with Range request support |
+| **Image Convert** | `image_convert_handler` | Convert images between PNG/JPEG/WebP using sharp |
+| **Signed URL** | `signed_url` | Generate time-limited presigned URLs for storage files |
+| **Replicate** | `replicate` | Call Replicate ML models (image gen, embeddings, etc.) |
+| **Embed Store** | `embed_store` | Store embedding vectors for semantic search |
+| **Vector Search** | `vector_search` | Query embeddings by cosine similarity |
+| **Stripe Checkout** | `stripe_checkout` | Create Stripe Checkout sessions for payments/subscriptions |
+| **Stripe Webhook** | `stripe_webhook` | Validate Stripe webhook signatures and parse events |
+
+## DB Records
+
+Schema-based data storage built into BFFless:
+
+1. Define schema in project settings (fields, types, validation)
+2. Use Data CRUD handlers to interact with records
+3. Query with filters, sorting, pagination
+
+## AI Handler
+
+Call AI models directly from pipelines. Supports chat (multi-turn) and completion (single-turn) modes.
+
+Key config:
+- `provider`: `openai`, `anthropic`, or `google`
+- `mode`: `chat` or `completion`
+- `messageField`: field name containing the user message (from input)
+- `systemPrompt`: system instructions for the AI
+- `persistMessages`: store conversation history in a pipeline schema
+- `persistMessagesSchemaId`: which schema to store messages in
+
+## HTTP Request Handler
+
+Make outbound API calls to external services from within a pipeline.
+
+Key config:
+- `url`: target URL (supports expressions like `${steps.prev.apiUrl}`)
+- `method`: GET, POST, PATCH, DELETE
+- `body`: request body (expressions supported)
+- `headers`: custom headers to add
+- `forwardAuth`: forward the original request's auth header
+
+## File Handlers
+
+**Upload** (`file_upload_handler`): Handles multipart file uploads or downloads from URLs. Supports allowed MIME type filtering, max file size, optional image conversion, and date-bucketed storage.
+
+**Serve** (`file_serve_handler`): Streams files from storage with HTTP Range support for video/audio playback. Config: `subDir`, `cacheMaxAge`.
+
+**Image Convert** (`image_convert_handler`): Converts between PNG, JPEG, WebP. Config: `inputPath`, `outputFormat`, `quality`.
+
+**Signed URL** (`signed_url`): Generates time-limited presigned URLs for private storage files. Config: `path`, `expiresIn` (seconds, default 3600).
+
+## Stripe Handlers
+
+**Checkout** (`stripe_checkout`): Creates Stripe Checkout sessions. Config: `priceId`, `mode` (payment/subscription), `successUrl`, `cancelUrl`, `customerEmail`, `environment` (live/test).
+
+**Webhook** (`stripe_webhook`): Validates webhook signatures and parses events. Config: `allowedEventTypes` (optional filter), `environment`.
+
+## Vector/Embedding Handlers
+
+**Embed Store** (`embed_store`): Stores embedding vectors in the database. Supports single embeddings or chunked documents. Config: `schemaId`, `recordId`, `embedding` or `chunks`.
+
+**Vector Search** (`vector_search`): Queries embeddings by cosine similarity. Config: `schemaId`, `queryVector`, `limit`, `threshold`.
+
+**Replicate** (`replicate`): Calls Replicate ML models for image generation, embeddings, etc. Auto-uploads large files to Replicate's Files API. Config: `model`, `version`, `input`.
+
+## Expression Syntax
+
+Access data throughout the pipeline using expressions:
+
+- `input.*` - Parsed request body
+- `query.*` - URL query parameters
+- `params.*` - URL path parameters
+- `headers.*` - Request headers
+- `steps.<name>.*` - Output from previous handler
+- `user.*` - Authenticated user info (if applicable)
+
+Example: `${input.email}` or `${steps.createUser.id}`
+
+## Validators
+
+Pipelines support validators that run before any steps execute:
+
+- `auth_required` - Require authenticated user
+- `rate_limit` - Rate limit requests (by IP or user)
+
+Both support conditions to selectively apply (e.g., only rate limit POST requests).
+
+## Common Workflows
+
+**Contact form:**
+1. Form handler → parse submission
+2. Data CRUD → store in "submissions" schema
+3. Email → notify admin
+4. Response → thank you message
+
+**AI chat:**
+1. Form handler → parse user message
+2. AI handler → call model with conversation context
+3. Response → return AI response
+
+**File upload with processing:**
+1. File Upload → store file
+2. Image Convert → resize/convert
+3. Data Create → store metadata
+4. Response → return file URL
+
+**Stripe payment:**
+1. Form handler → parse product selection
+2. Stripe Checkout → create session
+3. Response → redirect to Stripe
+
+**Semantic search:**
+1. Form handler → parse query
+2. AI/Replicate → generate query embedding
+3. Vector Search → find similar records
+4. Response → return results
+
+## Configuration Tips
+
+1. Name handlers descriptively for readable expressions
+2. Use Response handler last to control what client sees
+3. Test with simple inputs before adding validation
+4. Check pipeline logs for debugging failed executions
+5. Use `postSteps` for async work after the response is sent (e.g., sending emails)
+
+## Troubleshooting
+
+**Pipeline not triggering?**
+- Verify endpoint path matches request URL
+- Check HTTP method (GET, POST, etc.) is correct
+- Ensure pipeline is enabled and rule set is assigned to alias
+
+**Expression returning undefined?**
+- Check handler name matches exactly (case-sensitive)
+- Verify previous handler completed successfully
+- Use pipeline logs to see actual values at each step

package/plugins/bffless/skills/proxy-rules/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: proxy-rules
+description: Forward requests to backend APIs without CORS
+---
+
+# Proxy Rules
+
+**Docs**: https://docs.bffless.app/features/proxy-rules/
+
+Proxy rules forward requests from your static site to backend APIs, eliminating CORS issues and hiding API endpoints from clients.
+
+## Configuration Levels
+
+**Project defaults**: Apply to all aliases unless overridden
+
+**Alias overrides**: Specific aliases can have their own proxy rule sets assigned
+
+## Rule Sets
+
+Proxy rules are organized into **rule sets** — named, reusable groups of rules.
+
+An alias can have **multiple rule sets** attached. When multiple rule sets are assigned, their rules are merged in priority order (first set wins if two sets define the same path+method).
+
+This allows logical grouping, e.g.:
+- `api-proxy` — routes to your backend API
+- `pipelines` — pipeline-based handlers for chat, forms, etc.
+- `auth-proxy` — cookie-to-bearer token transformation
+
+### Assigning Rule Sets to Aliases
+
+Use `update_alias` with `proxyRuleSetIds` (array) to attach one or more rule sets:
+
+```
+update_alias(
+  repository: "owner/repo",
+  alias: "production",
+  proxyRuleSetIds: ["rule-set-id-1", "rule-set-id-2"]
+)
+```
+
+The legacy `proxyRuleSetId` (singular) still works for backwards compatibility but only supports one rule set.
+
+**Important**: After creating proxy rules, you must assign the rule set(s) to an alias for rules to take effect. Rules won't be active until linked to an alias.
+
+## Rule Structure
+
+Each rule specifies:
+- **Path pattern**: Which requests to intercept
+- **Target**: Backend URL to forward to
+- **Strip prefix**: Whether to remove the matched prefix
+
+## Pattern Types
+
+**Prefix match** (most common):
+```
+/api/* → https://api.example.com
+```
+Request to `/api/users` forwards to `https://api.example.com/users`
+
+**Exact match**:
+```
+/health → https://backend.example.com/status
+```
+Only exact path matches, no wildcards
+
+**Suffix match**:
+```
+*.json → https://data.example.com
+```
+Matches any path ending in `.json`
+
+## Strip Prefix Behavior
+
+With strip prefix ON (default):
+```
+/api/* → https://backend.com
+/api/users → https://backend.com/users
+```
+
+With strip prefix OFF:
+```
+/api/* → https://backend.com
+/api/users → https://backend.com/api/users
+```
+
+## Common Patterns
+
+**API proxy**: `/api/*` → your backend server
+
+**Third-party API**: `/stripe/*` → `https://api.stripe.com` (hides API from client)
+
+**Microservices**: Different prefixes route to different services
+
+## Security Notes
+
+- All proxy targets must use HTTPS
+- BFFless validates targets to prevent SSRF attacks
+- Headers like `Host` are rewritten to match target
+- Client IP forwarded via `X-Forwarded-For`
+
+## Troubleshooting
+
+**Requests not proxying?**
+- Check path pattern matches request URL exactly
+- Verify rule set is assigned to the alias via `update_alias`
+- Confirm target URL is HTTPS and reachable
+
+**Getting CORS errors still?**
+- Ensure the proxy rule set is assigned to the alias being accessed
+- Check browser DevTools for actual request URL (may not be hitting proxy)

package/plugins/bffless/skills/repository/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: repository
+description: Browse deployments, manage aliases, view branches
+---
+
+# Repository
+
+**Docs**: https://docs.bffless.app/features/repository-overview/
+
+The Repository is your central hub for browsing deployments, managing aliases, and navigating your project's content.
+
+## Content Browser
+
+The browser has four panels:
+
+1. **Files Panel**: Navigate directory structure, search files
+2. **Preview Panel**: Live preview of selected file
+3. **History Panel**: Deployment timeline, compare versions
+4. **References Panel**: See which aliases point to this deployment
+
+## Deployments
+
+Each deployment is an immutable snapshot of your build output. Deployments are identified by:
+
+- **Deployment ID**: Unique hash
+- **Git info**: Branch, commit SHA, commit message (if available)
+- **Timestamp**: When deployed
+- **Size**: Total file size
+
+## Aliases
+
+Aliases are named pointers to deployments. Two types:
+
+**Manual aliases**: You control which deployment they point to
+- `production`, `staging`, `v1.2.0`
+- Update manually or via API
+
+**Auto-preview aliases**: Automatically created for branches/PRs
+- `preview-feature-branch`, `pr-123`
+- Updated on each push, deleted when branch is deleted
+
+## Common Workflows
+
+**Deploy new version:**
+1. Upload via CLI/API/GitHub Action
+2. New deployment appears in Repository
+3. Update alias to point to new deployment
+
+**Rollback:**
+1. Find previous deployment in History
+2. Update production alias to point to it
+3. Instant rollback, no rebuild needed
+
+**Preview PRs:**
+1. Configure auto-preview in project settings
+2. Each PR gets unique preview URL
+3. Preview updates on each push
+
+## Navigation Tips
+
+- Use keyboard shortcuts: `j/k` to navigate files, `Enter` to preview
+- Search supports glob patterns: `*.html`, `components/**`
+- Click deployment hash to copy full URL
+- Right-click alias for quick actions menu