@bffless/claude-skills 1.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "bffless",
+  "owner": {
+    "name": "BFFless"
+  },
+  "metadata": {
+    "description": "BFFless platform skills for Claude Code",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "bffless",
+      "source": {
+        "source": "npm",
+        "package": "@bffless/claude-skills",
+        "version": "^1.0.0"
+      },
+      "description": "BFFless platform skills — deployments, pipelines, proxy rules, chat, traffic splitting, and more",
+      "category": "platform"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "bffless",
+  "version": "1.0.0",
+  "description": "BFFless platform skills for Claude Code — deployments, pipelines, proxy rules, chat, traffic splitting, and more",
+  "author": {
+    "name": "BFFless"
+  },
+  "homepage": "https://docs.bffless.app",
+  "repository": "https://github.com/bffless/claude-skills",
+  "license": "MIT",
+  "keywords": ["bffless", "static-hosting", "deployments", "pipelines", "chat"],
+  "skills": ["./skills/"]
+}

package/README.md

@@ -0,0 +1,94 @@
+# @bffless/claude-skills
+
+Claude Code plugin with platform skills for [BFFless](https://bffless.app) — a self-hosted static asset hosting platform with AI-powered pipelines.
+
+These skills give Claude Code domain knowledge about BFFless features so it can help you build, deploy, and configure your projects.
+
+## Skills Included
+
+| Skill                 | Description                                              |
+| --------------------- | -------------------------------------------------------- |
+| **authorization**     | Global and project roles, API keys, permission model     |
+| **bffless**           | Platform overview, key concepts, and feature summary     |
+| **chat**              | AI chat widget/full-page, skills, streaming, persistence |
+| **pipelines**         | Backend automation with handler chains and DB Records    |
+| **proxy-rules**       | Forward requests to backend APIs, eliminate CORS         |
+| **repository**        | Deployments, aliases, content browser, rollback          |
+| **share-links**       | Token-based sharing for private deployments              |
+| **traffic-splitting** | A/B testing, canary deployments, weighted routing        |
+| **upload-artifact**   | GitHub Action for uploading builds to BFFless            |
+
+## Install
+
+### Via Claude Code Plugin Marketplace
+
+```bash
+# Add the marketplace
+/plugin marketplace add bffless/claude-skills
+
+# Install the plugin
+/plugin install bffless
+```
+
+### Via CLI
+
+```bash
+claude plugin install bffless --scope user
+```
+
+### Local Development
+
+If you're contributing or want to use a local copy:
+
+```bash
+git clone https://github.com/bffless/claude-skills.git
+claude --plugin-dir ./claude-skills
+```
+
+## Usage
+
+Once installed, Claude Code automatically uses these skills when you ask about BFFless features. For example:
+
+- "Set up a proxy rule to forward /api requests to my backend"
+- "Add AI chat to my site with streaming"
+- "Configure traffic splitting for a canary deployment"
+- "Set up the upload-artifact GitHub Action for my repo"
+
+Skills are invoked by name with the `bffless` namespace:
+
+```
+/bffless:chat
+/bffless:proxy-rules
+/bffless:pipelines
+```
+
+## BFFless Pipeline Skills vs Claude Code Skills
+
+This package contains **Claude Code plugin skills** — they teach Claude about the BFFless platform so it can assist you as a developer.
+
+These are different from **BFFless pipeline skills**, which are markdown files you create in your own project's `.bffless/skills/` directory. Pipeline skills are deployed with your site and loaded by the AI chat handler at runtime to give your chatbot domain-specific knowledge.
+
+|              | Claude Code Skills (this package)       | Pipeline Skills (your project)          |
+| ------------ | --------------------------------------- | --------------------------------------- |
+| **Purpose**  | Help Claude help _you_ build on BFFless | Give _your chatbot_ domain knowledge    |
+| **Location** | Installed as Claude Code plugin         | `.bffless/skills/` in your project repo |
+| **Used by**  | Claude Code (your dev tool)             | BFFless AI chat handler (your users)    |
+| **Deployed** | npm install                             | `bffless/upload-artifact` GitHub Action |
+
+## Documentation
+
+- [BFFless Docs](https://docs.bffless.app)
+- [Getting Started](https://docs.bffless.app/getting-started/quickstart)
+- [Chat Feature](https://docs.bffless.app/features/chat/)
+- [Pipelines](https://docs.bffless.app/features/pipelines/)
+
+## Contributing
+
+1. Fork this repo
+2. Add or update skills in `skills/<skill-name>/SKILL.md`
+3. Each skill needs YAML frontmatter with `name` and `description`
+4. Open a PR — CI validates all skills automatically
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@bffless/claude-skills",
+  "version": "1.1.0",
+  "description": "Claude Code plugin with BFFless platform skills",
+  "keywords": [
+    "claude-code-plugin",
+    "bffless",
+    "skills",
+    "ai",
+    "static-hosting"
+  ],
+  "author": "BFFless",
+  "license": "MIT",
+  "homepage": "https://docs.bffless.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bffless/claude-skills"
+  },
+  "files": [
+    ".claude-plugin/",
+    "skills/"
+  ]
+}

package/skills/authorization/SKILL.md

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

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

@@ -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/skills/pipelines/SKILL.md

@@ -0,0 +1,81 @@
+---
+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, and more.
+
+## Handler Types
+
+| Handler | Purpose |
+|---------|---------|
+| **Form** | Parse form submissions (multipart, JSON, URL-encoded) |
+| **Data CRUD** | Create, read, update, delete DB Records |
+| **Email** | Send emails via configured provider |
+| **Response** | Return custom JSON or redirect |
+| **Function** | Custom JavaScript for complex logic |
+| **Aggregate** | Combine data from multiple sources |
+
+## DB Records
+
+Schema-based data storage built into BFFless:
+
+1. Define schema in project settings (fields, types, validation)
+2. Use Data CRUD handler to interact with records
+3. Query with filters, sorting, pagination
+
+## 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}`
+
+## 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
+
+**Waitlist signup:**
+1. Form handler → parse email
+2. Data CRUD → check if exists, then create
+3. Email → send confirmation to user
+4. Response → success or "already registered"
+
+**Webhook receiver:**
+1. Form handler → parse JSON payload
+2. Function → validate signature, transform data
+3. Data CRUD → store event
+4. Response → 200 OK
+
+## 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
+
+## Troubleshooting
+
+**Pipeline not triggering?**
+- Verify endpoint path matches request URL
+- Check HTTP method (GET, POST, etc.) is correct
+- Ensure pipeline is enabled and deployed
+
+**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

@@ -0,0 +1,83 @@
+---
+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 different proxy configurations
+
+## 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 alias isn't overriding project defaults
+- Confirm target URL is HTTPS and reachable
+
+**Getting CORS errors still?**
+- Ensure the proxy rule is active on the alias being accessed
+- Check browser DevTools for actual request URL (may not be hitting proxy)

package/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

package/skills/share-links/SKILL.md

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

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

@@ -0,0 +1,195 @@
+---
+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/*
+```