Update to InsForge

{
  "description": "Use this skill when writing app code with InsForge or @insforge/sdk: database CRUD, auth, storage uploads/storage RLS, functions, OpenRouter AI, realtime, emails, Stripe or Razorpay payments, or pointing S3-compatible tooling (aws CLI, AWS SDKs, rclone, Terraform, boto3) at InsForge Storage. Trigger on requests like add auth, fetch data, upload files, make a bucket public, add checkout, sell subscriptions, or send email. For infrastructure, SQL migrations, CLI commands, or payment provider setup, use insforge-cli instead.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 230
    },
    {
      "relative_path": "ai/audio.md",
      "size_in_bytes": 3751
    },
    {
      "relative_path": "ai/chat-completions.md",
      "size_in_bytes": 4569
    },
    {
      "relative_path": "ai/embeddings-and-rag.md",
      "size_in_bytes": 5112
    },
    {
      "relative_path": "ai/image-generation.md",
      "size_in_bytes": 4044
    },
    {
      "relative_path": "ai/models-list.md",
      "size_in_bytes": 2859
    },
    {
      "relative_path": "ai/overview.md",
      "size_in_bytes": 3882
    },
    {
      "relative_path": "ai/video-generation.md",
      "size_in_bytes": 3326
    },
    {
      "relative_path": "auth/sdk-integration.md",
      "size_in_bytes": 19148
    },
    {
      "relative_path": "auth/ssr-integration.md",
      "size_in_bytes": 12410
    },
    {
      "relative_path": "database/sdk-integration.md",
      "size_in_bytes": 10578
    },
    {
      "relative_path": "email/sdk-integration.md",
      "size_in_bytes": 6489
    },
    {
      "relative_path": "functions/sdk-integration.md",
      "size_in_bytes": 2286
    },
    {
      "relative_path": "payments/razorpay.md",
      "size_in_bytes": 11721
    },
    {
      "relative_path": "payments/stripe.md",
      "size_in_bytes": 11826
    },
    {
      "relative_path": "realtime/sdk-integration.md",
      "size_in_bytes": 9563
    },
    {
      "relative_path": "storage/postgres-rls.md",
      "size_in_bytes": 13578
    },
    {
      "relative_path": "storage/s3-gateway.md",
      "size_in_bytes": 9877
    },
    {
      "relative_path": "storage/sdk-integration.md",
      "size_in_bytes": 4250
    }
  ],
  "name": "insforge",
  "skill_md_contents": "---\nname: insforge\ndescription: >-\n  Use this skill when writing app code with InsForge or @insforge/sdk: database CRUD, auth, storage uploads/storage RLS, functions, OpenRouter AI, realtime, emails, Stripe or Razorpay payments, or pointing S3-compatible tooling (aws CLI, AWS SDKs, rclone, Terraform, boto3) at InsForge Storage. Trigger on requests like add auth, fetch data, upload files, make a bucket public, add checkout, sell subscriptions, or send email. For infrastructure, SQL migrations, CLI commands, or payment provider setup, use insforge-cli instead.\nlicense: Apache-2.0\n---\n\n# InsForge App Integration Skill\n\nThis skill covers **client-side SDK integration** using `@insforge/sdk`. For backend infrastructure operations (creating tables, inspecting schema, deploying functions, secrets, managing storage buckets, configuring payment provider keys/catalog, website deployments, cron job and schedules, logs, etc.), use the **insforge-cli** skill.\n\n## Quick Setup\n\n### 1. Install the SDK\n\n```bash\nnpm install @insforge/sdk@latest\n```\n\n### 2. Set up environment variables\n\nBefore using the SDK, create a `.env` file (or `.env.local` for Next.js) in your project root with your InsForge URL and anon key.\n\n#### How to get your URL and anon key\n\n1. **Ensure the project is linked.** Check for `.insforge/project.json` in the project root.\n   - Generate it with `npx @insforge/cli link` for an existing project or `npx @insforge/cli create` for a new project.\n\n2. **Get the anon key** via the CLI:\n\n   ```bash\n   npx @insforge/cli secrets get ANON_KEY\n   ```\n\n3. **Get the URL** from the `oss_host` field in `.insforge/project.json` (e.g., `https://myapp.us-east.insforge.app`).\n\n4. **Write both values** to the `.env` file using the correct framework prefix (see table below).\n\n> **Important:** Use the anon key for user-scoped SDK clients, including SSR. For privileged server-only app code that needs admin/service access, use `createAdminClient({ apiKey })`; the API key is a full-access admin key, equivalent to a service role key on other platforms.\n\nUse the correct environment variable prefix and access pattern for your framework:\n\n| Framework                     | `.env` file  | Variables                                                   | Access Pattern                              |\n| ----------------------------- | ------------ | ----------------------------------------------------------- | ------------------------------------------- |\n| **Next.js**                   | `.env.local` | `NEXT_PUBLIC_INSFORGE_URL`, `NEXT_PUBLIC_INSFORGE_ANON_KEY` | `process.env.NEXT_PUBLIC_*`                 |\n| **Vite** (React, Vue, Svelte) | `.env`       | `VITE_INSFORGE_URL`, `VITE_INSFORGE_ANON_KEY`               | `import.meta.env.VITE_*`                    |\n| **Astro**                     | `.env`       | `PUBLIC_INSFORGE_URL`, `PUBLIC_INSFORGE_ANON_KEY`           | `import.meta.env.PUBLIC_*`                  |\n| **SvelteKit**                 | `.env`       | `PUBLIC_INSFORGE_URL`, `PUBLIC_INSFORGE_ANON_KEY`           | `import { env } from '$env/dynamic/public'` |\n| **Create React App**          | `.env`       | `REACT_APP_INSFORGE_URL`, `REACT_APP_INSFORGE_ANON_KEY`     | `process.env.REACT_APP_*`                   |\n| **Node.js / Server**          | `.env`       | `INSFORGE_URL`, `INSFORGE_ANON_KEY`                         | `process.env.*`                             |\n\nExample `.env.local` for Next.js:\n\n```bash\nNEXT_PUBLIC_INSFORGE_URL=https://your-appkey.us-east.insforge.app\nNEXT_PUBLIC_INSFORGE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...\n```\n\n> **Important:** Keep `.env` files local. Add `.env`, `.env.local`, and `.env*.local` to your `.gitignore` and keep `.env.example` for documenting required variables.\n\n### 3. Initialize the client\n\nNext.js:\n\n```javascript\nimport { createClient } from '@insforge/sdk'\n\nconst insforge = createClient({\n  baseUrl: process.env.NEXT_PUBLIC_INSFORGE_URL,\n  anonKey: process.env.NEXT_PUBLIC_INSFORGE_ANON_KEY\n})\n```\n\nVite:\n\n```javascript\nimport { createClient } from '@insforge/sdk'\n\nconst insforge = createClient({\n  baseUrl: import.meta.env.VITE_INSFORGE_URL,\n  anonKey: import.meta.env.VITE_INSFORGE_ANON_KEY\n})\n```\n\nAstro:\n\n```javascript\nimport { createClient } from '@insforge/sdk'\n\nconst insforge = createClient({\n  baseUrl: import.meta.env.PUBLIC_INSFORGE_URL,\n  anonKey: import.meta.env.PUBLIC_INSFORGE_ANON_KEY\n})\n```\n\nFor trusted server-only code that needs project-admin access:\n\n```javascript\nimport { createAdminClient } from \"@insforge/sdk\";\n\nconst admin = createAdminClient({\n  baseUrl: process.env.INSFORGE_URL,\n  apiKey: process.env.INSFORGE_API_KEY,\n});\n```\n\n## Module Reference\n\n| Module        | Integration Guide                                            |\n| ------------- | ------------------------------------------------------------ |\n| **Database**  | [database/sdk-integration.md](database/sdk-integration.md)   |\n| **Auth**      | [auth/sdk-integration.md](auth/sdk-integration.md)           |\n| **Storage**   | [storage/sdk-integration.md](storage/sdk-integration.md)     |\n| **Functions** | [functions/sdk-integration.md](functions/sdk-integration.md) |\n| **AI**        | [ai/overview.md](ai/overview.md)                             |\n| **Real-time** | [realtime/sdk-integration.md](realtime/sdk-integration.md)   |\n| **Email**     | [email/sdk-integration.md](email/sdk-integration.md)         |\n| **Payments: Stripe** | [payments/stripe.md](payments/stripe.md)             |\n| **Payments: Razorpay** | [payments/razorpay.md](payments/razorpay.md)       |\n\n### What Each Module Covers\n\n| Module        | Content                                                                                                       |\n| ------------- | ------------------------------------------------------------------------------------------------------------- |\n| **Database**  | CRUD operations, filters, pagination, RPC calls                                                               |\n| **Auth**      | Sign up/in, OAuth, sessions, profiles, password reset                                                         |\n| **Storage**   | Upload, download, delete files; S3-compatible gateway for CI / backup tooling; write RLS policies for buckets |\n| **Functions** | Invoke edge functions                                                                                         |\n| **AI**        | OpenRouter AI calls for chat, images, video, audio, embeddings, and model discovery                           |\n| **Email**     | Send custom transactional HTML emails (welcome, newsletter, notifications)                                    |\n| **Payments: Stripe** | Stripe Checkout Sessions, subscriptions, and Billing Portal redirects                                  |\n| **Payments: Razorpay** | Razorpay Orders, Subscriptions, Checkout.js, and subscription management                               |\n| **Real-time** | Connect, subscribe, publish events, and track presence snapshots plus join/leave deltas                       |\n\n### Guides\n\n| Guide                                                                                                          | When to Use                                                                                                                                                                                                                                                                                                                                                                                            |\n| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| [../insforge-cli/references/database/access-control.md](../insforge-cli/references/database/access-control.md) | Backend setup for application-table access control — covers RLS, infinite recursion prevention, `SECURITY DEFINER` patterns, performance tips, and common InsForge patterns                                                                                                                                                                                                                            |\n| [storage/s3-gateway.md](storage/s3-gateway.md)                                                                 | Fallback path when the consumer is existing S3 tooling (aws CLI, AWS SDKs, rclone, Terraform, boto3) and adopting `@insforge/sdk` is impractical — covers endpoint/region setup, access-key management, path-style addressing, and supported vs. not-supported S3 operations. **Requires InsForge 2.0.9+.** **Prefer the SDK** ([storage/sdk-integration.md](storage/sdk-integration.md)) for app code |\n| [storage/postgres-rls.md](storage/postgres-rls.md)                                                             | Writing RLS policies for `storage.objects` — owner-only, public-read, path-scoped, team-shared, and the `NULL uploaded_by` caveat for mixed REST + S3 buckets                                                                                                                                                                                                                                          |\n| [../insforge-cli/references/database/vector.md](../insforge-cli/references/database/vector.md)                 | Backend setup for semantic search, recommendations, or RAG — covers the `vector` extension, schema/dimensions, distance operators, HNSW/IVFFlat indexes, and RPC similarity search                                                                                                                                                                                                                     |\n| [ai/chat-completions.md](ai/chat-completions.md)                                                               | Text generation, structured answers, and streaming chat through OpenRouter                                                                                                                                                                                                                                                                                                                             |\n| [ai/image-generation.md](ai/image-generation.md)                                                               | Image generation/editing through OpenRouter, then durable storage in InsForge Storage                                                                                                                                                                                                                                                                                                                  |\n| [ai/video-generation.md](ai/video-generation.md)                                                               | Async OpenRouter video jobs, status polling, and storing generated media                                                                                                                                                                                                                                                                                                                               |\n| [ai/audio.md](ai/audio.md)                                                                                     | Speech-to-text, text-to-speech, and storing audio assets/transcripts with InsForge                                                                                                                                                                                                                                                                                                                     |\n| [ai/embeddings-and-rag.md](ai/embeddings-and-rag.md)                                                           | Generating embeddings through OpenRouter, storing them in pgvector, and wiring up a basic RAG pipeline                                                                                                                                                                                                                                                                                                 |\n| [ai/models-list.md](ai/models-list.md)                                                                         | Discovering OpenRouter model IDs, modalities, parameters, pricing, and embedding dimensions                                                                                                                                                                                                                                                                                                            |\n| [payments](../insforge-cli/references/payments/overview.md)                                                    | Configuring Stripe/Razorpay keys, syncing provider catalog, setting up webhooks, and writing payment RLS before app integration                                                                                                                                                                                                                                                                        |\n\n### Building Payments for a New App\n\nFirst choose the provider. There is no generic app payments guide:\n\n- For Stripe Checkout, subscriptions, and Billing Portal, load [payments/stripe.md](payments/stripe.md).\n- For Razorpay Orders, Subscriptions, Checkout.js, and cancel/pause/resume flows, load [payments/razorpay.md](payments/razorpay.md).\n\nBefore writing app code, check provider setup with the **insforge-cli** payments references:\n\n```bash\nnpx @insforge/cli payments stripe status\nnpx @insforge/cli payments razorpay status\n```\n\nIf the chosen provider is unconfigured, ask the developer/admin to configure that provider first.\n\n### Real-time Backend Setup\n\nThe real-time SDK is for frontend event handling and messaging. Configure channel patterns, database triggers, and channel/message RLS with the **insforge-cli** skill; see [realtime](../insforge-cli/references/realtime.md).\n\n### Backend Configuration\n\nSupported project config knobs are managed via the CLI — use\n`npx @insforge/cli config export/plan/apply` for auth redirect URLs,\nverification flags, password policy, auth SMTP settings, storage upload size,\nrealtime/schedule retention, and cloud deployment subdomain. OAuth providers,\nexternal app setup, storage buckets, functions, secrets, and deployment env vars\nstill use their dedicated dashboard or CLI flows. See the **insforge-cli**\nskill's Configuration section.\n\n### Risky backend changes? Use a branch first\n\nWhen a code change in this skill depends on a **schema migration**, **new RLS policy**, **OAuth provider config change**, or any other backend change that affects prod behavior, create a backend branch first. Branches share `JWT_SECRET` (existing user JWTs keep working) but get a fresh database + EC2 + `API_KEY` / `ANON_KEY`, so you can test the SDK + backend change end-to-end in isolation.\n\nThe full branching workflow lives in the **insforge-cli** skill — see [branch](../insforge-cli/references/branch/overview.md) for the decision guide and lifecycle commands. Typical loop:\n\n```bash\nnpx @insforge/cli branch create feat-x --mode schema-only\n# ... apply migrations / change auth config / update RLS on the branch ...\n# ... test the SDK against the branch backend ...\nnpx @insforge/cli branch merge feat-x --dry-run     # review SQL\nnpx @insforge/cli branch merge feat-x               # apply to parent\n```\n\n> ⚠ **After `branch create` or `branch switch`**, update the app's InsForge URL and anon-key env values, then **restart your dev server** (or re-source `.env`) so the SDK talks to the selected branch backend.\n\n## SDK Quick Reference\n\nAll SDK methods return `{ data, error }`.\n\n| Module               | Methods                                                                                              |\n| -------------------- | ---------------------------------------------------------------------------------------------------- |\n| `insforge.database`  | `.from().select()`, `.insert()`, `.update()`, `.delete()`, `.rpc()`                                  |\n| `insforge.auth`      | `.signUp()`, `.signInWithPassword()`, `.signInWithOAuth()`, `.signOut()`, `.getCurrentUser()`        |\n| `insforge.storage`   | `.from().upload()`, `.uploadAuto()`, `.download()`, `.remove()`                                      |\n| `insforge.functions` | `.invoke()`                                                                                          |\n| `insforge.ai`        | Deprecated fallback only: `.chat.completions.create()`, `.images.generate()`, `.embeddings.create()` |\n| `insforge.realtime`  | `.connect()`, `.subscribe()`, `.publish()`, `.on()`, `.disconnect()`                                 |\n| `insforge.emails`    | `.send({ to, subject, html, cc?, bcc?, from?, replyTo? })`                                           |\n| `insforge.payments.stripe` | `.createCheckoutSession()`, `.createCustomerPortalSession()` |\n| `insforge.payments.razorpay` | `.createOrder()`, `.verifyOrder()`, `.createSubscription()`, `.verifySubscription()`, `.cancelSubscription()`, `.pauseSubscription()`, `.resumeSubscription()` |\n\n## Important Notes\n\n- **Database inserts require array format**: `insert([{...}])`\n- **Next.js / SSR auth**: Use `@insforge/sdk/ssr` helpers (`createBrowserClient`, `createServerClient`, `createAuthActions`, `createRefreshAuthRouter`) and import `updateSession` from `@insforge/sdk/ssr/middleware` in Proxy/Middleware. Keep the refresh token httpOnly, run auth mutations through `createAuthActions()` on the server, return only safe app data from Server Actions, and let the browser read the short-lived access token for Storage/Realtime. See [auth/ssr-integration.md](auth/ssr-integration.md)\n- **Storage**: Save both `url` AND `key` to database for download/delete operations\n- **Functions invoke URL**: `/functions/{slug}`\n- **Email delivery**: Auth emails (signup verification, password reset, magic links, invites) ship on **every plan**. Custom email via `insforge.emails.send()` ships on **every paid plan**. Use the platform-managed delivery path; custom sender domain is dashboard config. See [email/sdk-integration.md](email/sdk-integration.md).\n- **Payments**: Configure provider keys/catalog with `npx @insforge/cli payments <provider> ...` first; frontend code uses provider-scoped SDK modules.\n- **Payment RLS**: Before payment UI, add app-specific RLS on provider runtime tables. Stripe uses `payments.stripe_checkout_sessions` and `payments.stripe_customer_portal_sessions`; Razorpay uses `payments.razorpay_orders` and `payments.razorpay_subscriptions`. Durable fulfillment triggers go on `payments.webhook_events`, not success URLs, Checkout callbacks, or `payments.transactions`.\n- **Use Tailwind CSS v3.4**\n- **Always local build before deploy**: Prevents wasted build resources and faster debugging\n- **SDK package**: Use `@insforge/sdk` directly for all features including authentication.\n- **Deployment**: Include a `vercel.json` in the project root for SPA routing (React, React Router apps). The `download-template` tool includes this automatically.\n- **Branching for risky backend changes**: If your SDK code depends on a new schema, RLS policy, or auth config change, create a branch via `npx @insforge/cli branch create` first — see the **insforge-cli** skill's [branch](../insforge-cli/references/branch/overview.md) reference. After `branch create` / `branch switch`, update the app's InsForge URL and anon-key env values, then **restart the dev server**.\n"
}