docs: add SDK documentation and SKILL.md

CHANGELOG.md

@@ -2,22 +2,20 @@
 
 ## [0.1.1](https://github.com/supabase/server/compare/server-v0.1.0...server-v0.1.1) (2026-03-26)
 
-
 ### Features
 
-* add `supabaseOptions` and refactor client creation to options objects ([#19](https://github.com/supabase/server/issues/19)) ([5a10099](https://github.com/supabase/server/commit/5a100995a1b6254f92768c82c74b1c754c29b3b2))
-* implement server-side DX primitives, wrappers, and adapters ([#6](https://github.com/supabase/server/issues/6)) ([d206e5c](https://github.com/supabase/server/commit/d206e5cdb102bf96e0c501b72e7f161cbf9fba0c))
-* passing down Database generic type to `createClient` ([#16](https://github.com/supabase/server/issues/16)) ([4053f6d](https://github.com/supabase/server/commit/4053f6d8db89201a239190a025b08cf19083acb4))
-* set initial release version ([8352bda](https://github.com/supabase/server/commit/8352bda35c5967a6692f0a21744d30793e10709a))
-* standardize error response ([#18](https://github.com/supabase/server/issues/18)) ([a7ddb74](https://github.com/supabase/server/commit/a7ddb74bfbbe4565d461be7df7f01e64854f6c06))
-
+- add `supabaseOptions` and refactor client creation to options objects ([#19](https://github.com/supabase/server/issues/19)) ([5a10099](https://github.com/supabase/server/commit/5a100995a1b6254f92768c82c74b1c754c29b3b2))
+- implement server-side DX primitives, wrappers, and adapters ([#6](https://github.com/supabase/server/issues/6)) ([d206e5c](https://github.com/supabase/server/commit/d206e5cdb102bf96e0c501b72e7f161cbf9fba0c))
+- passing down Database generic type to `createClient` ([#16](https://github.com/supabase/server/issues/16)) ([4053f6d](https://github.com/supabase/server/commit/4053f6d8db89201a239190a025b08cf19083acb4))
+- set initial release version ([8352bda](https://github.com/supabase/server/commit/8352bda35c5967a6692f0a21744d30793e10709a))
+- standardize error response ([#18](https://github.com/supabase/server/issues/18)) ([a7ddb74](https://github.com/supabase/server/commit/a7ddb74bfbbe4565d461be7df7f01e64854f6c06))
 
 ### Bug Fixes
 
-* key name resolution for client creation ([#9](https://github.com/supabase/server/issues/9)) ([e17bd4e](https://github.com/supabase/server/commit/e17bd4ecb1c46d0dc1468f363c884090d78ae86a))
-* remove provenance until repo is public ([2ebbc71](https://github.com/supabase/server/commit/2ebbc71e214c4bbae62c6af203a039801b5e3d4d))
-* removing `core` lib exports from root index ([#17](https://github.com/supabase/server/issues/17)) ([5e53e3c](https://github.com/supabase/server/commit/5e53e3c14fcc7c198f1c0bbec9089b4aedd91473))
-* support bare array format for SUPABASE_JWKS ([#8](https://github.com/supabase/server/issues/8)) ([6bd2e4d](https://github.com/supabase/server/commit/6bd2e4dfc1b60ce4cc8a1b59435b87797e1cb017))
+- key name resolution for client creation ([#9](https://github.com/supabase/server/issues/9)) ([e17bd4e](https://github.com/supabase/server/commit/e17bd4ecb1c46d0dc1468f363c884090d78ae86a))
+- remove provenance until repo is public ([2ebbc71](https://github.com/supabase/server/commit/2ebbc71e214c4bbae62c6af203a039801b5e3d4d))
+- removing `core` lib exports from root index ([#17](https://github.com/supabase/server/issues/17)) ([5e53e3c](https://github.com/supabase/server/commit/5e53e3c14fcc7c198f1c0bbec9089b4aedd91473))
+- support bare array format for SUPABASE_JWKS ([#8](https://github.com/supabase/server/issues/8)) ([6bd2e4d](https://github.com/supabase/server/commit/6bd2e4dfc1b60ce4cc8a1b59435b87797e1cb017))
 
 ## 0.1.0 (2026-03-24)
 

README.md

@@ -22,11 +22,22 @@ One import. One line of config. Auth is validated, clients are scoped, CORS is h
 ## Installation
 
 ```bash
-# Deno
-import { withSupabase } from "npm:@supabase/server";
-
 # npm
+npm install @supabase/server
+
+# pnpm
 pnpm add @supabase/server
+
+# Deno / Supabase Edge Functions (no install — import directly)
+import { withSupabase } from "npm:@supabase/server";
+```
+
+### AI coding skills
+
+Install the skill so your AI coding agent (Claude Code, Cursor, etc.) knows how to use this package:
+
+```bash
+npx skills add supabase/server
 ```
 
 ## Quick Start
@@ -84,6 +95,34 @@ export default {
 }
 ```
 
+### Server-to-server
+
+```ts
+// Only accept the "automations" named secret key
+export default {
+  fetch: withSupabase({ allow: 'secret:automations' }, async (req, ctx) => {
+    const body = await req.json()
+    const { data } = await ctx.supabaseAdmin
+      .from('scheduled_tasks')
+      .insert({ name: body.taskName })
+    return Response.json({ success: true, data })
+  }),
+}
+```
+
+The caller sends the secret key in the `apikey` header:
+
+```ts
+await fetch('https://<project>.supabase.co/functions/v1/my-function', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    apikey: 'sb_secret_...', // the "automations" secret key
+  },
+  body: JSON.stringify({ taskName: 'cleanup' }),
+})
+```
+
 ## Auth Modes
 
 | Mode               | Credential            | Use case                                            |
@@ -95,7 +134,14 @@ export default {
 
 Array syntax (`allow: ["user", "secret"]`) accepts multiple auth methods — first match wins.
 
-Named key validation: `allow: "public:web_app"` validates against a specific named key in `SUPABASE_PUBLISHABLE_KEYS`.
+Named key validation: `allow: "public:web_app"` or `allow: "secret:automations"` validates against a specific named key in `SUPABASE_PUBLISHABLE_KEYS` or `SUPABASE_SECRET_KEYS`.
+
+> **Supabase Edge Functions:** By default, the platform requires a valid JWT on every request. If your function uses `allow: 'public'`, `allow: 'secret'`, or `allow: 'always'`, disable the platform-level JWT check in `supabase/config.toml`:
+>
+> ```toml
+> [functions.my-function]
+> verify_jwt = false
+> ```
 
 ## Context
 
@@ -281,17 +327,38 @@ Also supported (for local dev, self-hosted, or other runtimes):
 
 When both singular and plural forms are set, plural takes priority.
 
-For other environments, pass overrides via the `env` config option or `resolveEnv()`.
+For other environments, pass overrides via the `env` config option or `resolveEnv()`. See [`docs/environment-variables.md`](docs/environment-variables.md) for details.
+
+## Runtimes
+
+- **Supabase Edge Functions** — environment variables are auto-injected. Zero config.
+- **Deno / Bun** — works out of the box with the `export default { fetch }` pattern.
+- **Node.js** — use the [Hono adapter](#hono) or [core primitives](#primitives) with your framework of choice.
+- **Cloudflare Workers** — enable `nodejs_compat` in `wrangler.toml` or pass env overrides via the `env` config option.
+- **Next.js / Nuxt / SvelteKit / Remix** — use core primitives to build a cookie-based auth adapter. See [`docs/ssr-frameworks.md`](docs/ssr-frameworks.md).
 
 ## Exports
 
 | Export                           | What's in it                                                                                                      |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
 | `@supabase/server`               | `withSupabase`, `createSupabaseContext`                                                                           |
 | `@supabase/server/core`          | `verifyAuth`, `verifyCredentials`, `extractCredentials`, `createContextClient`, `createAdminClient`, `resolveEnv` |
-| `@supabase/server/wrappers`      | `verifyWebhookSignature`                                                                                          |
 | `@supabase/server/adapters/hono` | `withSupabase` (Hono middleware)                                                                                  |
 
+## Documentation
+
+| Question                                                 | Doc file                                                         |
+| -------------------------------------------------------- | ---------------------------------------------------------------- |
+| How do I create a basic endpoint?                        | [`docs/getting-started.md`](docs/getting-started.md)             |
+| What auth modes are available? Array syntax? Named keys? | [`docs/auth-modes.md`](docs/auth-modes.md)                       |
+| How do I use this with Hono?                             | [`docs/hono-adapter.md`](docs/hono-adapter.md)                   |
+| How do I use low-level primitives for custom flows?      | [`docs/core-primitives.md`](docs/core-primitives.md)             |
+| How do environment variables work across runtimes?       | [`docs/environment-variables.md`](docs/environment-variables.md) |
+| How do I handle errors? What codes exist?                | [`docs/error-handling.md`](docs/error-handling.md)               |
+| How do I get typed database queries?                     | [`docs/typescript-generics.md`](docs/typescript-generics.md)     |
+| How do I use this in Next.js, Nuxt, SvelteKit, or Remix? | [`docs/ssr-frameworks.md`](docs/ssr-frameworks.md)               |
+| What's the complete API surface?                         | [`docs/api-reference.md`](docs/api-reference.md)                 |
+
 ## Development
 
 ```bash