@bffless/claude-skills 1.5.0 → 1.5.1

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "BFFless platform skills for Claude Code — deployments, pipelines, proxy rules, chat, traffic splitting, and more",
   "skills": ["./skills/"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bffless/claude-skills",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Claude Code plugin with BFFless platform skills",
   "keywords": [
     "claude-code-plugin",

package/skills/authentication/SKILL.md

@@ -1,204 +0,0 @@
----
-name: authentication
-description: Cross-domain authentication using the admin login relay pattern, built-in /_bffless/auth endpoints, and cookie-based sessions
----
-
-# Authentication
-
-BFFless uses a cross-domain authentication relay pattern. Users authenticate at the workspace's admin domain (`admin.<workspace>`) and are relayed back to the content domain with auth cookies. Auth endpoints on the content domain are accessed via the **built-in `/_bffless/auth/*` endpoints** — no proxy rules required.
-
-## How Authentication Works
-
-### Workspace Subdomains
-
-For workspace subdomains (e.g., `myalias.sandbox.workspace.bffless.app`), SuperTokens session cookies (`sAccessToken`) work directly because they share the parent domain.
-
-When a user visits a private deployment and isn't authenticated:
-
-1. Backend redirects to `https://admin.<workspace>/login?redirect=<original-path>&tryRefresh=true`
-2. The login page attempts a session refresh first (the `tryRefresh` param)
-3. If refresh fails, the user logs in normally
-4. After login, the user is redirected back to the original path
-5. The `sAccessToken` cookie is valid across all subdomains of the workspace
-
-### Custom Domains (customDomainRelay)
-
-For custom domains (e.g., `www.bffless.com`), SuperTokens cookies don't work because they're on a completely different domain. BFFless uses a **domain relay** flow:
-
-1. User visits a private page on `www.bffless.com/portal/`
-2. Frontend detects the user is not authenticated (via `/_bffless/auth/session`)
-3. Frontend redirects to the admin login with relay params:
-   ```
-   https://admin.console.bffless.app/login?customDomainRelay=true&targetDomain=www.bffless.com&redirect=%2Fportal%2F
-   ```
-4. User logs in on the admin domain (or is already logged in via SuperTokens session)
-5. After login, the frontend calls `POST /api/auth/domain-token` with:
-   ```json
-   { "targetDomain": "www.bffless.com", "redirectPath": "/portal/" }
-   ```
-6. Backend validates that `targetDomain` is a registered domain for this workspace, then creates a short-lived JWT (the "domain token")
-7. Backend returns a `redirectUrl` pointing to the callback on the custom domain: `https://www.bffless.com/_bffless/auth/callback?token=...&redirect=/portal/`
-8. The callback endpoint validates the token, sets `bffless_access` and `bffless_refresh` HttpOnly cookies, and redirects to the original path
-
-### Important: Use `/_bffless/auth/*`, NOT `/api/auth/*`
-
-The `/_bffless/auth/*` endpoints are **built into BFFless nginx** and handled by a dedicated controller. They are separate from the SuperTokens `/api/auth/*` endpoints. Do NOT use `/api/auth/*` on custom domains — those are SuperTokens endpoints that use different cookies (`sAccessToken`) which are not set by the domain relay flow.
-
-The domain relay callback sets `bffless_access` and `bffless_refresh` cookies, which are only recognized by the `/_bffless/auth/*` endpoints. Using `/api/auth/session` instead of `/_bffless/auth/session` will cause a redirect loop because the SuperTokens session check won't find the `bffless_access` cookie.
-
-## Auth Endpoints (Built-in)
-
-All auth endpoints are available at `/_bffless/auth/*` on any domain served by BFFless — no proxy rules needed.
-
-| Endpoint                    | Method | Purpose                                                  |
-| --------------------------- | ------ | -------------------------------------------------------- |
-| `/_bffless/auth/session`    | GET    | Check current session (returns user info or 401)         |
-| `/_bffless/auth/refresh`    | POST   | Refresh an expired access token using the refresh cookie |
-| `/_bffless/auth/callback`   | GET    | Exchange a domain relay token for auth cookies           |
-| `/_bffless/auth/logout`     | POST   | Clear auth cookies                                       |
-
-### Session Check Priority
-
-The `/_bffless/auth/session` endpoint checks auth in this order:
-
-1. **`bffless_access` cookie** — custom domain JWT issued by the callback flow
-2. **`sAccessToken` cookie** — SuperTokens session (fallback for workspace subdomains)
-
-If the access token is expired, it returns `401` with `"try refresh token"` to signal the client should call `/_bffless/auth/refresh`.
-
-## Frontend Integration
-
-### Checking Session (with automatic token refresh)
-
-Use a shared promise pattern to avoid duplicate session checks across components:
-
-```typescript
-async function checkSession() {
-  // Reuse shared session promise so multiple components don't duplicate requests
-  if (!(window as any).__bfflessSession) {
-    (window as any).__bfflessSession = (async () => {
-      const res = await fetch('/_bffless/auth/session', { credentials: 'include' });
-      if (res.ok) return res.json();
-
-      if (res.status === 401) {
-        // Token expired — try refreshing
-        const refreshRes = await fetch('/_bffless/auth/refresh', {
-          method: 'POST',
-          credentials: 'include',
-        });
-        if (refreshRes.ok) {
-          // Retry session check with new token
-          const retryRes = await fetch('/_bffless/auth/session', { credentials: 'include' });
-          if (retryRes.ok) return retryRes.json();
-        }
-      }
-      return null;
-    })().catch(() => null);
-  }
-
-  return (window as any).__bfflessSession;
-}
-
-// Returns: { authenticated: true, user: { id, email, role } } or null
-```
-
-The flow is: session check → if 401, refresh token → retry session check. This handles the common case where the access token has expired but the refresh token is still valid.
-
-### Redirecting to Login
-
-When unauthenticated, redirect the user to the admin login with relay params. Use the **promoted admin domain** (e.g., `admin.console.bffless.app`), not the full workspace subdomain:
-
-```typescript
-function getLoginUrl(adminLoginUrl: string, redirectPath: string): string {
-  const targetDomain = window.location.hostname;
-  const params = new URLSearchParams({
-    customDomainRelay: 'true',
-    targetDomain,
-    redirect: redirectPath,
-  });
-  return `${adminLoginUrl}?${params.toString()}`;
-}
-
-// Example: redirect to admin login, then relay back to /portal/
-const session = await checkSession();
-if (!session) {
-  window.location.href = getLoginUrl(
-    'https://admin.console.bffless.app/login',
-    '/portal/',
-  );
-}
-```
-
-### Logout
-
-```typescript
-await fetch('/_bffless/auth/logout', { method: 'POST', credentials: 'include' });
-```
-
-### Updating UI Based on Auth State (Header example)
-
-```typescript
-// Check auth state and update Login/Portal links
-window.__bfflessSession = window.__bfflessSession || checkBfflessSession().catch(() => null);
-
-window.__bfflessSession.then((data) => {
-  if (data?.authenticated) {
-    // User is logged in — update nav links
-    document.querySelectorAll('[data-auth-link]').forEach((el) => {
-      el.textContent = 'Portal';
-    });
-  }
-});
-```
-
-## Auth Flow Diagram
-
-```
-Custom Domain Flow:
-┌──────────────────┐     JS redirect        ┌──────────────────────────┐
-│  www.bffless.com │ ──────────────────→    │  admin.<workspace>/login │
-│  (private page)  │  customDomainRelay=    │  ?customDomainRelay=true │
-│                  │  true&targetDomain=    │  &targetDomain=www...    │
-└──────────────────┘  www.bffless.com       └────────────┬─────────────┘
-        ▲                                                │
-        │                                     User logs in (SuperTokens)
-        │                                                │
-        │                                                ▼
-        │                                   POST /api/auth/domain-token
-        │                                   → returns { token, redirectUrl }
-        │                                                │
-        │              302 redirect                      │
-        │  ←─────────────────────────────────────────────┘
-        │  to: www.bffless.com/_bffless/auth/callback?token=...
-        │
-        ▼
-┌──────────────────┐
-│  /_bffless/auth  │  Validates token, sets bffless_access
-│  /callback       │  + bffless_refresh cookies
-│  (built-in)      │  → 302 redirect to /portal/
-└──────────────────┘
-```
-
-## Troubleshooting
-
-**User gets stuck in a redirect loop?**
-
-- **Most common cause:** Using `/api/auth/session` instead of `/_bffless/auth/session`. The domain relay callback sets `bffless_access` cookies which are only recognized by `/_bffless/auth/*` endpoints. The `/api/auth/*` endpoints check SuperTokens cookies (`sAccessToken`) which are NOT set by the domain relay flow.
-- Verify the custom domain is registered in `domain_mappings` with `isActive = true`
-- Ensure cookies are being set (requires HTTPS for `Secure` flag)
-
-**"Domain not registered" error on domain-token?**
-
-- The `targetDomain` must match a `domain_mappings` entry or be a subdomain of `PRIMARY_DOMAIN`
-- Check for www vs non-www mismatch
-
-**Session check returns 401 but user just logged in?**
-
-- On custom domains: verify the `/_bffless/auth/callback` was reached and cookies were set
-- On workspace subdomains: verify `COOKIE_DOMAIN` is configured for cross-subdomain cookie sharing
-- Check that the `bffless_access` or `sAccessToken` cookie is present in the request
-
-**Admin login URL — use promoted domain, not workspace subdomain:**
-
-- If the workspace has a promoted domain (e.g., `console.bffless.app`), use `admin.console.bffless.app`, NOT `admin.console.workspace.bffless.app`
-- The workspace subdomain format still works but the promoted domain is cleaner

package/skills/authorization/SKILL.md

@@ -1,59 +0,0 @@
----
-name: authorization
-description: Two-level permission system with global and project roles
----
-
-# Authorization
-
-**Docs**: https://docs.bffless.app/features/authorization/
-
-BFFless uses a two-level permission system: global roles for workspace-wide access and project roles for fine-grained control.
-
-## Global Roles
-
-| Role | Capabilities |
-|------|-------------|
-| **Admin** | Full workspace access, manage users, billing, settings |
-| **User** | Create projects, manage own content |
-| **Member** | View-only access, participate in assigned projects |
-
-## Project Roles
-
-| Role | Capabilities |
-|------|-------------|
-| **Owner** | Full control, delete project, transfer ownership |
-| **Admin** | Manage settings, users, deployments |
-| **Contributor** | Deploy, create aliases, modify content |
-| **Viewer** | Read-only access to project and deployments |
-
-## Permission Sources
-
-Users can receive project access from multiple sources:
-
-1. **Direct assignment**: Explicitly added to project
-2. **Group membership**: Inherited from user group
-3. **Effective role**: Highest permission wins when multiple sources exist
-
-## API Keys
-
-Two types of API keys for automation:
-
-- **Global keys**: Workspace-wide access, use the creator's permissions
-- **Project keys**: Scoped to single project, specify exact role
-
-Best practice: Use project-scoped keys with minimum required permissions.
-
-## Common Patterns
-
-**External contractors**: Add as Member globally, Contributor on specific projects
-
-**CI/CD pipelines**: Create project API key with Contributor role
-
-**Client preview access**: Use share links instead of user accounts
-
-## Troubleshooting
-
-**"Permission denied" errors?**
-- Check effective role (may be inherited from group)
-- Verify API key scope matches the project
-- Global Members need explicit project assignment

package/skills/bffless/SKILL.md

@@ -1,158 +0,0 @@
----
-name: bffless
-description: Knowledge about BFFless platform, features, and setup
----
-
-# BFFless Platform Guide
-
-BFFless is a self-hosted static asset hosting platform designed for modern frontend deployments. It provides a Backend-for-Frontend (BFF) layer without requiring you to write backend code.
-
-## What is BFFless?
-
-BFFless is a platform that:
-
-- **Hosts static assets** from your CI/CD pipeline (React, Vue, Angular, etc.)
-- **Provides AI-powered pipelines** for backend automation without writing code
-- **Manages deployments** with aliases like `production`, `staging`, `preview`
-- **Handles custom domains** with automatic SSL via Let's Encrypt
-- **Enables traffic splitting** for A/B testing and canary deployments
-- **Offers proxy rules** to forward requests to backend APIs
-
-### Key Concepts
-
-| Concept        | Description                                                     |
-| -------------- | --------------------------------------------------------------- |
-| **Deployment** | A snapshot of your build artifacts at a specific commit SHA     |
-| **Alias**      | A named pointer to a deployment (e.g., `production` → `abc123`) |
-| **Proxy Rule** | Routes requests to external APIs or AI pipelines                |
-| **Pipeline**   | Chain of handlers that process requests (AI, transform, proxy)  |
-| **Skill**      | Markdown files that give AI agents specialized knowledge        |
-
-## Setting Up Proxy Rules
-
-Proxy rules let you route requests through BFFless to backend APIs or AI pipelines.
-
-### Creating a Proxy Rule
-
-1. Go to **Project Settings** → **Proxy Rules**
-2. Click **Add Rule**
-3. Configure the rule:
-
-```
-Path Pattern: /api/*
-Target URL: https://your-backend.com
-Strip Prefix: true (removes /api from forwarded requests)
-```
-
-### Rule Types
-
-| Type                 | Use Case                                 |
-| -------------------- | ---------------------------------------- |
-| **External Proxy**   | Forward to external APIs (REST, GraphQL) |
-| **Pipeline**         | Process with AI handlers                 |
-| **Internal Rewrite** | Serve different static files             |
-
-### Common Patterns
-
-**API Gateway:**
-
-```
-/api/* → https://api.example.com/*
-```
-
-**AI Chat Endpoint:**
-
-```
-/api/chat → Pipeline with AI handler
-```
-
-**Microservices:**
-
-```
-/api/users/* → https://users-service.internal
-/api/orders/* → https://orders-service.internal
-```
-
-## Traffic Splitting
-
-Traffic splitting distributes requests across multiple deployment aliases for A/B testing or gradual rollouts.
-
-### How It Works
-
-1. Configure weights per alias (e.g., 90% production, 10% canary)
-2. First-time visitors get randomly assigned based on weights
-3. A cookie (`__bffless_variant`) maintains sticky sessions
-4. Users see consistent experience on return visits
-
-### Setting Up Traffic Splitting
-
-1. Go to **Domains** → Select your domain
-2. Click **Traffic Splitting**
-3. Add aliases with weights:
-
-| Alias      | Weight |
-| ---------- | ------ |
-| production | 90%    |
-| canary     | 10%    |
-
-4. Save changes
-
-### Use Cases
-
-- **A/B Testing**: Compare two versions of your app
-- **Canary Deployments**: Gradually roll out new features
-- **Blue/Green**: Instant switch between deployments
-- **Feature Flags**: Route specific traffic to experimental builds
-
-### Best Practices
-
-- Start with small percentages for new deployments (5-10%)
-- Monitor error rates before increasing traffic
-- Use the `X-Variant` header to track which variant served the request
-- Cookie duration is configurable (default: 24 hours)
-
-## Pipelines and AI Handlers
-
-Pipelines let you create backend logic without writing code.
-
-### Pipeline Structure
-
-A pipeline is a chain of steps:
-
-```
-Request → Step 1 → Step 2 → Step 3 → Response
-```
-
-### AI Handler
-
-The AI handler uses LLMs to process requests:
-
-- Configure system prompts
-- Set model and temperature
-- Enable skills for specialized knowledge
-- Stream responses for chat interfaces
-
-### Example: Chat API
-
-1. Create a pipeline with an AI handler
-2. Configure:
-   - Model: `gpt-4` or `claude-3`
-   - System Prompt: Your assistant instructions
-   - Skills: Enable relevant skills
-3. Create a proxy rule pointing to the pipeline
-4. Your frontend calls `/api/chat` and gets AI responses
-
-## GitHub Action Integration
-
-Upload builds automatically from CI/CD:
-
-```yaml
-- uses: bffless/upload-artifact@v1
-  with:
-    path: dist
-    api-url: ${{ vars.BFFLESS_URL }}
-    api-key: ${{ secrets.BFFLESS_KEY }}
-    alias: production
-```
-
-This uploads your build and updates the `production` alias to point to it.

package/skills/chat/SKILL.md

@@ -1,196 +0,0 @@
----
-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/skills/pipelines/SKILL.md

@@ -1,162 +0,0 @@
----
-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/skills/proxy-rules/SKILL.md

@@ -1,110 +0,0 @@
----
-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/skills/repository/SKILL.md

@@ -1,64 +0,0 @@
----
-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

package/skills/share-links/SKILL.md

@@ -1,53 +0,0 @@
----
-name: share-links
-description: Token-based sharing for private deployments
----
-
-# Share Links
-
-**Docs**: https://docs.bffless.app/features/share-links/
-
-Share links allow sharing private deployments without requiring authentication. Each link contains a unique token that grants temporary access.
-
-## Creating Share Links
-
-1. Navigate to your deployment in the Repository
-2. Click the **Share** button in the toolbar
-3. Configure options:
-   - **Expiration**: Set duration or leave unlimited
-   - **Usage limit**: Max number of visits (optional)
-   - **Label**: Descriptive name for tracking
-4. Copy the generated URL
-
-## Link Management
-
-- **View usage**: See visit count and last accessed time
-- **Disable**: Temporarily suspend access without deleting
-- **Regenerate**: Create new token, invalidating the old URL
-- **Delete**: Permanently remove access
-
-## Use Cases
-
-- **Portfolio sharing**: Send private work to potential clients
-- **Client reviews**: Share staging sites for feedback
-- **Beta testing**: Distribute preview builds to testers
-- **Time-limited access**: Demos that expire after a meeting
-
-## Best Practices
-
-1. Use descriptive labels to track who has which link
-2. Set expiration dates for sensitive content
-3. Combine with traffic splitting to show different content per link
-4. Regenerate tokens if a link is compromised
-5. Monitor usage to detect unexpected access patterns
-
-## Troubleshooting
-
-**Link not working?**
-- Check if the link is disabled or expired
-- Verify usage limit hasn't been reached
-- Ensure the deployment still exists
-
-**Need to revoke access?**
-- Disable the link immediately, or delete it entirely
-- Regenerate creates a new URL while keeping tracking history

package/skills/traffic-splitting/SKILL.md

@@ -1,63 +0,0 @@
----
-name: traffic-splitting
-description: Distribute traffic across aliases with weights and rules
----
-
-# Traffic Splitting
-
-**Docs**: https://docs.bffless.app/features/traffic-splitting/
-
-Traffic splitting distributes requests across multiple deployment aliases. Use it for A/B testing, canary deployments, and personalized experiences.
-
-## Configuration
-
-### Weights
-
-Assign percentage weights to aliases. Weights must sum to 100.
-
-```
-production: 90%
-canary: 10%
-```
-
-### Sticky Sessions
-
-When enabled, visitors consistently see the same variant. Controlled via cookie. Disable for true random distribution per request.
-
-### Traffic Rules
-
-Rules override weights based on conditions. Evaluated in order, first match wins.
-
-**Rule conditions:**
-- **Headers**: Match request headers (e.g., `X-Beta-User: true`)
-- **Query params**: Match URL parameters (e.g., `?variant=new`)
-- **Cookies**: Match cookie values
-- **Share link**: Route specific share links to specific aliases
-
-## Use Cases
-
-**A/B Testing**: Split traffic 50/50 between variants, measure conversion
-
-**Canary Deployment**: Send 5% to new version, monitor for errors, gradually increase
-
-**Beta Features**: Route users with beta header to feature branch
-
-**Personalized Demos**: Use share links to show customized content per client
-
-## Configuration Tips
-
-1. Start canary deployments at 5-10%, increase gradually
-2. Enable sticky sessions for consistent user experience
-3. Use rules for deterministic routing (internal testing, specific clients)
-4. Combine with share links for per-recipient personalization
-
-## Troubleshooting
-
-**Unexpected routing?**
-- Rules are evaluated before weights; check rule order
-- Clear cookies if sticky session is routing to old variant
-- Verify alias names match exactly (case-sensitive)
-
-**Traffic percentages seem off?**
-- Small sample sizes show high variance; need 100+ requests for accuracy
-- Sticky sessions can skew percentages if users have different visit frequencies

package/skills/upload-artifact/SKILL.md

@@ -1,195 +0,0 @@
----
-name: upload-artifact
-description: GitHub Action for uploading build artifacts to BFFless
----
-
-# BFFless Upload Artifact Action
-
-The `bffless/upload-artifact` GitHub Action uploads build artifacts from your CI/CD pipeline to a BFFless instance. It's available on the [GitHub Marketplace](https://github.com/bffless/upload-artifact).
-
-For full documentation, see the [README on GitHub](https://github.com/bffless/upload-artifact).
-
-## Quick Start
-
-Only 3 inputs are required:
-
-```yaml
-- uses: bffless/upload-artifact@v1
-  with:
-    path: dist
-    api-url: ${{ vars.ASSET_HOST_URL }}
-    api-key: ${{ secrets.ASSET_HOST_KEY }}
-```
-
-## Common Workflows
-
-### PR Preview with Comment
-
-```yaml
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: write # Required for PR comments
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0 # Required for commit timestamp
-
-      - name: Build
-        run: npm run build
-
-      - uses: bffless/upload-artifact@v1
-        with:
-          path: dist
-          api-url: ${{ vars.ASSET_HOST_URL }}
-          api-key: ${{ secrets.ASSET_HOST_KEY }}
-          alias: preview
-          description: 'PR #${{ github.event.pull_request.number }} preview'
-          pr-comment: true
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-```
-
-### Production Deploy
-
-```yaml
-- uses: bffless/upload-artifact@v1
-  id: deploy
-  with:
-    path: dist
-    api-url: ${{ vars.ASSET_HOST_URL }}
-    api-key: ${{ secrets.ASSET_HOST_KEY }}
-    alias: production
-    tags: ${{ needs.release.outputs.version }}
-    description: 'Release ${{ needs.release.outputs.version }}'
-
-- run: echo "Deployed to ${{ steps.deploy.outputs.sha-url }}"
-```
-
-### Multiple Artifacts (Same Workflow)
-
-You can upload multiple artifacts in the same workflow:
-
-```yaml
-- name: Upload frontend
-  uses: bffless/upload-artifact@v1
-  with:
-    path: apps/frontend/dist
-    api-url: ${{ vars.ASSET_HOST_URL }}
-    api-key: ${{ secrets.ASSET_HOST_KEY }}
-    alias: production
-    base-path: /dist
-
-- name: Upload skills
-  uses: bffless/upload-artifact@v1
-  with:
-    path: .bffless
-    api-url: ${{ vars.ASSET_HOST_URL }}
-    api-key: ${{ secrets.ASSET_HOST_KEY }}
-    alias: production
-```
-
-## All Inputs
-
-| Input | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `path` | **yes** | -- | Build directory to upload |
-| `api-url` | **yes** | -- | BFFless platform URL |
-| `api-key` | **yes** | -- | API key for authentication |
-| `repository` | no | `github.repository` | Repository in `owner/repo` format |
-| `commit-sha` | no | auto | Git commit SHA |
-| `branch` | no | auto | Branch name |
-| `is-public` | no | `'true'` | Public visibility |
-| `alias` | no | -- | Deployment alias (e.g., `production`) |
-| `base-path` | no | `/<path>` | Path prefix in zip |
-| `committed-at` | no | auto | ISO 8601 commit timestamp |
-| `description` | no | -- | Human-readable description |
-| `proxy-rule-set-name` | no | -- | Proxy rule set name |
-| `proxy-rule-set-id` | no | -- | Proxy rule set ID |
-| `tags` | no | -- | Comma-separated tags |
-| `summary` | no | `'true'` | Write GitHub Step Summary |
-| `summary-title` | no | `'Deployment Summary'` | Summary heading |
-| `working-directory` | no | `'.'` | Working directory |
-| `pr-comment` | no | `'false'` | Post comment on PR |
-| `comment-header` | no | `'🚀 BFFLESS Deployment'` | PR comment header |
-| `github-token` | no | `GITHUB_TOKEN` | Token for PR comments |
-
-## Outputs
-
-| Output | Description |
-|--------|-------------|
-| `deployment-url` | Primary URL (SHA-based) |
-| `sha-url` | Immutable SHA-based URL |
-| `alias-url` | Alias-based URL |
-| `preview-url` | Preview URL (if basePath provided) |
-| `branch-url` | Branch-based URL |
-| `deployment-id` | API deployment ID |
-| `file-count` | Number of files uploaded |
-| `total-size` | Total bytes |
-| `response` | Raw JSON response |
-
-## How It Works
-
-1. **Validates** the build directory exists
-2. **Zips** the directory preserving structure
-3. **Uploads** via multipart POST to `/api/deployments/zip`
-4. **Sets outputs** from API response
-5. **Writes Step Summary** with deployment table
-6. **Posts PR comment** (if enabled)
-7. **Cleans up** temporary files
-
-## Auto-Detection
-
-The action automatically detects:
-
-- **Repository**: from `github.repository`
-- **Commit SHA**: PR head SHA or push SHA
-- **Branch**: PR head ref or push ref
-- **Committed At**: via `git log` (requires `fetch-depth: 0`)
-- **Base Path**: derived from `path` input as `/<path>`
-
-## PR Comments
-
-When `pr-comment: true`, the action posts a formatted comment:
-
-> ## 🚀 BFFLESS Deployment
->
-> **Alias:** `preview`
->
-> | Property    | Value                              |
-> | ----------- | ---------------------------------- |
-> | **Preview** | [example.com](https://example.com) |
-> | **Commit**  | `abc1234`                          |
-> | **Files**   | 42                                 |
-> | **Size**    | 1.2 MB                             |
-
-Comments are automatically updated on subsequent pushes (no duplicates).
-
-## Troubleshooting
-
-### Missing commit timestamp
-
-```yaml
-- uses: actions/checkout@v4
-  with:
-    fetch-depth: 0 # Full history needed for git log
-```
-
-### PR comment permission denied
-
-```yaml
-permissions:
-  pull-requests: write # Required for comments
-```
-
-### Custom base path
-
-If your app expects to be served from a subdirectory:
-
-```yaml
-- uses: bffless/upload-artifact@v1
-  with:
-    path: build
-    base-path: /docs/build # Served at /docs/build/*
-```