@bffless/skills 1.7.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "bffless-plugins",
+  "owner": {
+    "name": "BFFless"
+  },
+  "metadata": {
+    "description": "BFFless platform skills",
+    "version": "1.7.0"
+  },
+  "plugins": [
+    {
+      "name": "bffless",
+      "source": "./plugins/bffless",
+      "description": "BFFless platform skills — deployments, pipelines, proxy rules, chat, traffic splitting, and more",
+      "category": "platform"
+    }
+  ]
+}

package/LICENSE.md

@@ -0,0 +1,19 @@
+# O'Saasy License
+
+Copyright (c) 2026 BFFless, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, and distribute the Software, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. The Software is provided "as is", without warranty of any kind, express or
+   implied, including but not limited to the warranties of merchantability,
+   fitness for a particular purpose and noninfringement.
+
+3. In no event shall the authors or copyright holders be liable for any claim,
+   damages or other liability, whether in an action of contract, tort or
+   otherwise, arising from, out of or in connection with the Software or the
+   use or other dealings in the Software.

package/README.md

@@ -0,0 +1,117 @@
+# @bffless/skills
+
+Agent skills for [BFFless](https://bffless.app) — a self-hosted static asset hosting platform with AI-powered pipelines.
+
+These skills give your AI coding agent domain knowledge about BFFless features so it can help you build, deploy, and configure your projects.
+
+Originally built as a Claude Code plugin, the skills are plain markdown and also work with the open-source [`skills`](https://www.npmjs.com/package/skills) CLI — so you can install them into any agent that reads skill files from your project.
+
+## Skills Included
+
+| Skill                 | Description                                              |
+| --------------------- | -------------------------------------------------------- |
+| **authentication**    | Cross-domain auth, login relay, cookie sessions          |
+| **authorization**     | Global and project roles, API keys, permission model     |
+| **bffless**           | Platform overview, key concepts, and feature summary     |
+| **cache-and-storage** | Cache rules, storage backends, API keys for CI/CD        |
+| **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            |
+| **use-bff-state**     | React hook for server-side state with Data Tables        |
+
+## Install
+
+### Claude Code (plugin marketplace)
+
+```bash
+# Add the marketplace
+/plugin marketplace add bffless/skills
+
+# Install the plugin
+/plugin install bffless
+```
+
+Or via CLI:
+
+```bash
+claude plugin install bffless --scope user
+```
+
+### Any agent (via `npx skills`)
+
+The same skills repo works with the open-source [`skills`](https://www.npmjs.com/package/skills) CLI:
+
+```bash
+# List available skills
+npx skills add bffless/skills --list
+
+# Install all skills into your project
+npx skills add bffless/skills
+
+# Install a specific skill
+npx skills add bffless/skills --skill chat
+```
+
+This clones the repo and copies the selected skill files into your project so any compatible agent can read them.
+
+### Local Development
+
+To use a local copy with Claude Code (e.g. when contributing):
+
+```bash
+git clone https://github.com/bffless/skills.git
+claude --plugin-dir ./skills
+```
+
+## Usage
+
+Once installed, your agent 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"
+
+In Claude Code, skills are invoked by name with the `bffless` namespace:
+
+```
+/bffless:chat
+/bffless:proxy-rules
+/bffless:pipelines
+```
+
+## Developer Skills vs BFFless Pipeline Skills
+
+This package contains **developer-facing agent skills** — they teach your coding agent about the BFFless platform so it can assist you while you build.
+
+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.
+
+|              | Developer Skills (this package)         | Pipeline Skills (your project)          |
+| ------------ | --------------------------------------- | --------------------------------------- |
+| **Purpose**  | Help your agent help _you_ build on BFFless | Give _your chatbot_ domain knowledge |
+| **Location** | Installed via Claude Code plugin or `npx skills` | `.bffless/skills/` in your project repo |
+| **Used by**  | Your coding agent (your dev tool)       | BFFless AI chat handler (your users)    |
+| **Deployed** | npm / `skills` CLI                      | `bffless/upload-artifact` GitHub Action |
+
+## Documentation
+
+- [BFFless Docs](https://docs.bffless.app)
+- [Getting Started](https://docs.bffless.app/getting-started/quickstart)
+- [Skills](https://docs.bffless.app/features/claude-code-plugin)
+- [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 `plugins/bffless/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
+
+[O'Saasy](./LICENSE.md)

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@bffless/skills",
+  "version": "1.7.0",
+  "description": "BFFless platform skills — usable with Claude Code or any agent via the `skills` CLI",
+  "keywords": [
+    "skills",
+    "agent-skills",
+    "claude-code-plugin",
+    "bffless",
+    "ai",
+    "static-hosting"
+  ],
+  "author": "BFFless",
+  "license": "O'Saasy",
+  "homepage": "https://docs.bffless.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bffless/skills"
+  },
+  "files": [
+    ".claude-plugin/marketplace.json",
+    "plugins/"
+  ]
+}

package/plugins/bffless/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "bffless",
+  "version": "1.7.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/skills",
+  "license": "O'Saasy",
+  "keywords": [
+    "bffless",
+    "static-hosting",
+    "deployments",
+    "pipelines",
+    "chat"
+  ],
+  "skills": [
+    "./skills/"
+  ]
+}

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

@@ -0,0 +1,204 @@
+---
+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/plugins/bffless/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/plugins/bffless/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.