From 6e0be028c9d4e1c8c3f465f7c15ecc2d777b9887 Mon Sep 17 00:00:00 2001
From: ahmad-ajmal <ahmadajmal1514@gmail.com>
Date: Mon, 5 Oct 2026 11:49:33 +0100
Subject: [PATCH 1/2] supabase integration

---
 app/action/action_set.py                      |   67 +-
 app/agent_base.py                             |    5 +
 app/config.py                                 |    9 +
 .../integrations/integration_management.py    |    5 +-
 .../pages/Settings/IntegrationsSettings.tsx   |    9 +-
 craftos_integrations/README.md                |    5 +-
 craftos_integrations/core/system.py           |   24 +
 craftos_integrations/providers/__init__.py    |    2 +
 .../providers/supabase/GUIDANCE.md            |  136 ++
 .../providers/supabase/INTEGRATION.md         |  167 ++
 .../providers/supabase/__init__.py            |    3 +
 .../providers/supabase/client.py              | 1949 +++++++++++++++++
 .../providers/supabase/operations.py          | 1344 ++++++++++++
 .../providers/supabase/provider.py            |  420 ++++
 scripts/smoke_supabase.py                     |  383 ++++
 tests/integrations/test_provider_listeners.py |    4 +-
 .../integrations/test_supabase_conformance.py |  716 ++++++
 tests/integrations/test_system.py             |   56 +
 tests/test_action_set_catalog.py              |   60 +
 19 files changed, 5348 insertions(+), 16 deletions(-)
 create mode 100644 craftos_integrations/providers/supabase/GUIDANCE.md
 create mode 100644 craftos_integrations/providers/supabase/INTEGRATION.md
 create mode 100644 craftos_integrations/providers/supabase/__init__.py
 create mode 100644 craftos_integrations/providers/supabase/client.py
 create mode 100644 craftos_integrations/providers/supabase/operations.py
 create mode 100644 craftos_integrations/providers/supabase/provider.py
 create mode 100644 scripts/smoke_supabase.py
 create mode 100644 tests/integrations/test_supabase_conformance.py
 create mode 100644 tests/test_action_set_catalog.py

diff --git a/app/action/action_set.py b/app/action/action_set.py
index 67430c067..ac0745757 100644
--- a/app/action/action_set.py
+++ b/app/action/action_set.py
@@ -27,6 +27,56 @@
 }
 
 
+_MAX_NOUNS = 6
+
+
+def _umbrella_of(set_name: str, all_sets: Dict[str, List[str]]) -> Optional[str]:
+    """Longest other set name that prefixes this one (``supabase`` for
+    ``supabase_storage``) — the integration's shortlist set."""
+    best = None
+    for other in all_sets:
+        if other != set_name and set_name.startswith(other + "_"):
+            if best is None or len(other) > len(best):
+                best = other
+    return best
+
+
+def describe_set(
+    set_name: str, actions: List[str], all_sets: Dict[str, List[str]]
+) -> str:
+    """Catalog line for a set with no hand-written description.
+
+    The agent picks sets from this catalog, so the line must say what is
+    inside. Integration sets are named by integration and noun
+    (``supabase_storage``) and their actions by verb + integration + noun
+    (``delete_supabase_bucket``); listing the nouns tells the agent where
+    an action lives without spending tokens on every action name.
+    """
+    sub_sets = sorted(s for s in all_sets if s.startswith(set_name + "_"))
+    if sub_sets:
+        return (
+            f"shortlist of the most-used {set_name} actions ({len(actions)}); "
+            f"not everything — load {set_name}_* sets for the rest"
+        )
+
+    umbrella = _umbrella_of(set_name, all_sets)
+    strip = set(umbrella.split("_")) if umbrella else set()
+    shown_as: Dict[str, str] = {}  # singular key -> display form, in order
+    for action in actions:
+        tokens = [t for t in action.split("_") if t not in strip]
+        noun = "_".join(tokens[1:]) if len(tokens) > 1 else action
+        key = noun[:-2] if noun.endswith(("ches", "shes", "xes", "sses")) else noun.rstrip("s")
+        if not key:
+            continue
+        # Keep first-seen order, but prefer the plural form for display.
+        if key not in shown_as or (noun.endswith("s") and not shown_as[key].endswith("s")):
+            shown_as[key] = noun
+    nouns = list(shown_as.values())
+    shown = ", ".join(nouns[:_MAX_NOUNS])
+    more = ", …" if len(nouns) > _MAX_NOUNS else ""
+    return f"{len(actions)} actions: {shown}{more}"
+
+
 class ActionSetManager:
     """
     Singleton managing action set compilation from the ActionRegistry.
@@ -134,7 +184,7 @@ def list_all_sets(self) -> Dict[str, str]:
         from agent_core import registry_instance, PLATFORM_ALL
 
         current_platform = platform_lib.system().lower()
-        discovered_sets: Dict[str, str] = {}
+        members: Dict[str, List[str]] = {}
 
         # Scan all registered actions to find unique set names
         for action_name, platform_impls in registry_instance._registry.items():
@@ -147,14 +197,13 @@ def list_all_sets(self) -> Dict[str, str]:
 
             action_sets = getattr(impl.metadata, "action_sets", [])
             for set_name in action_sets:
-                if set_name not in discovered_sets:
-                    # Use default description if known, otherwise generate one
-                    desc = DEFAULT_SET_DESCRIPTIONS.get(
-                        set_name, f"Custom action set: {set_name}"
-                    )
-                    discovered_sets[set_name] = desc
-
-        return discovered_sets
+                members.setdefault(set_name, []).append(action_name)
+
+        return {
+            set_name: DEFAULT_SET_DESCRIPTIONS.get(set_name)
+            or describe_set(set_name, actions, members)
+            for set_name, actions in members.items()
+        }
 
     def get_set_description(self, set_name: str) -> Optional[str]:
         """
diff --git a/app/agent_base.py b/app/agent_base.py
index 96c2aea46..b7f4f3e6e 100644
--- a/app/agent_base.py
+++ b/app/agent_base.py
@@ -49,6 +49,8 @@
     NOTION_SHARED_CLIENT_SECRET,
     HUBSPOT_SHARED_CLIENT_ID,
     HUBSPOT_SHARED_CLIENT_SECRET,
+    SUPABASE_SHARED_CLIENT_ID,
+    SUPABASE_SHARED_CLIENT_SECRET,
     SLACK_SHARED_CLIENT_ID,
     SLACK_SHARED_CLIENT_SECRET,
     TELEGRAM_SHARED_BOT_TOKEN,
@@ -3542,6 +3544,9 @@ async def _initialize_external_libraries(self) -> None:
                 # HubSpot (only used by the `invite` OAuth path; Private App token login needs nothing)
                 "HUBSPOT_SHARED_CLIENT_ID": HUBSPOT_SHARED_CLIENT_ID,
                 "HUBSPOT_SHARED_CLIENT_SECRET": HUBSPOT_SHARED_CLIENT_SECRET,
+                # Supabase (only used by the OAuth path; personal-access-token login needs nothing)
+                "SUPABASE_SHARED_CLIENT_ID": SUPABASE_SHARED_CLIENT_ID,
+                "SUPABASE_SHARED_CLIENT_SECRET": SUPABASE_SHARED_CLIENT_SECRET,
                 # Slack (only used by the `invite` OAuth path)
                 "SLACK_SHARED_CLIENT_ID": SLACK_SHARED_CLIENT_ID,
                 "SLACK_SHARED_CLIENT_SECRET": SLACK_SHARED_CLIENT_SECRET,
diff --git a/app/config.py b/app/config.py
index 5d59e1989..092f74297 100644
--- a/app/config.py
+++ b/app/config.py
@@ -654,3 +654,12 @@ def detect_and_save_os_language() -> str:
 HUBSPOT_SHARED_CLIENT_SECRET: str = get_credential(
     "hubspot", "client_secret", "HUBSPOT_SHARED_CLIENT_SECRET"
 )
+
+# Supabase (confidential OAuth app + PKCE; empty until the app is registered,
+# in which case the integration offers only personal-access-token login)
+SUPABASE_SHARED_CLIENT_ID: str = get_credential(
+    "supabase", "client_id", "SUPABASE_SHARED_CLIENT_ID"
+)
+SUPABASE_SHARED_CLIENT_SECRET: str = get_credential(
+    "supabase", "client_secret", "SUPABASE_SHARED_CLIENT_SECRET"
+)
diff --git a/app/data/action/integrations/integration_management.py b/app/data/action/integrations/integration_management.py
index 1e6182d75..fe882e338 100644
--- a/app/data/action/integrations/integration_management.py
+++ b/app/data/action/integrations/integration_management.py
@@ -115,7 +115,7 @@ def list_available_integrations(input_data: dict) -> dict:
             "description": (
                 "The integration to connect, using its exact id. Valid values: slack, "
                 "discord, telegram, whatsapp, whatsapp_business, notion, linkedin, "
-                "posthog, and "
+                "posthog, supabase, and "
                 "the Google Workspace apps as SEPARATE ids — gmail, google_drive, "
                 "google_docs, google_calendar, google_youtube (there is no single "
                 "'google' integration). Call list_available_integrations if unsure."
@@ -132,7 +132,8 @@ def list_available_integrations(input_data: dict) -> dict:
                 "whatsapp_business: {access_token, phone_number_id}, "
                 "notion: {token}, "
                 "posthog: {api_key, host(optional: 'us'/'eu'/self-hosted URL), "
-                "project_id(optional)}. "
+                "project_id(optional)}, "
+                "supabase: {access_token (personal access token, sbp_…)}. "
                 "Leave empty for OAuth or interactive (QR code) flows."
             ),
             "example": {"bot_token": "123456:ABC-DEF"},
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/IntegrationsSettings.tsx b/app/ui_layer/browser/frontend/src/pages/Settings/IntegrationsSettings.tsx
index 005a08f76..429bc4737 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/IntegrationsSettings.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/IntegrationsSettings.tsx
@@ -31,6 +31,7 @@ import {
   YouTube,
   MicrosoftOutlook,
   PostHog,
+  Supabase,
 } from '@ridemountainpig/svgl-react'
 import { useTranslation } from 'react-i18next'
 import { Button, Badge, ConfirmModal } from '../../components/ui'
@@ -98,6 +99,7 @@ const SVGL_BY_ID: Record<string, SvglIcon> = {
   google_youtube: YouTube,
   outlook: MicrosoftOutlook,
   posthog: PostHog,
+  supabase: Supabase,
 }
 
 // Integration icon component. Lookup order:
@@ -1592,6 +1594,11 @@ export function IntegrationsSettings({ hideHeader = false }: { hideHeader?: bool
                           : isProblem(account) || account.sessionState === 'reconnecting'
                             ? stateLabel(account)
                             : ''
+                      // Nickname first (staged edit wins); the identity can be an
+                      // opaque id (e.g. a token fingerprint), so it stays in the tooltip.
+                      const nickname = staged && account.identity in staged.aliases
+                        ? staged.aliases[account.identity]
+                        : account.alias
                       return (
                         <button
                           key={account.identity}
@@ -1603,7 +1610,7 @@ export function IntegrationsSettings({ hideHeader = false }: { hideHeader?: bool
                         >
                           <span className={`${styles.mLive} ${dotClass(account)}`} />
                           <span className={styles.mRowId} title={account.identity}>
-                            {account.identity}
+                            {nickname || account.identity}
                           </span>
                           <span className={styles.mRowSpacer} />
                           {meta && <span className={styles.mRowMeta}>{meta}</span>}
diff --git a/craftos_integrations/README.md b/craftos_integrations/README.md
index 5db195cc6..c8f8082e7 100644
--- a/craftos_integrations/README.md
+++ b/craftos_integrations/README.md
@@ -1,6 +1,6 @@
 # craftos_integrations
 
-A plug-and-play package of 24 external integrations (Discord, Slack, Telegram Bot + User, GitHub, Jira, Stripe, HubSpot, Notion, LinkedIn, Outlook, PostHog, Twitter, WhatsApp Web/Business, LINE, Lark + Lark Calendar/Drive, plus per-service Google: Gmail / Calendar / Drive / Docs / YouTube) that any Python host can drop in.
+A plug-and-play package of 25 external integrations (Discord, Slack, Telegram Bot + User, GitHub, Jira, Stripe, HubSpot, Notion, LinkedIn, Outlook, PostHog, Supabase, Twitter, WhatsApp Web/Business, LINE, Lark + Lark Calendar/Drive, plus per-service Google: Gmail / Calendar / Drive / Docs / YouTube) that any Python host can drop in.
 
 The package owns:
 
@@ -195,6 +195,7 @@ Every OAuth-capable integration reads its credentials via `ConfigStore.get_oauth
 | linkedin          | oauth       | `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`                           |
 | notion            | both        | `NOTION_SHARED_CLIENT_ID`, `NOTION_SHARED_CLIENT_SECRET` (only for `invite`) |
 | slack             | both        | `SLACK_SHARED_CLIENT_ID`, `SLACK_SHARED_CLIENT_SECRET` (only for `invite`) |
+| supabase          | token → both | `SUPABASE_SHARED_CLIENT_ID`, `SUPABASE_SHARED_CLIENT_SECRET` (OAuth path; `auth_type` reports `both` only once both are set — personal access token otherwise) |
 
 The discord voice helper additionally reads `extras["openai_api_key"]` (or `OPENAI_API_KEY` env) for STT/TTS.
 
@@ -381,7 +382,7 @@ integration_registry()  # snapshot dict {id: metadata}
 | `INTEGRATION.md` | gotchas: identifier shapes, auth failure modes, rate limits |
 | `GUIDANCE.md` | how the agent should *use* the integration |
 
-Add the provider to `default_providers()`; the autoloader imports `client.py` at startup. This is the **full port** shape — gmail, google_*, hubspot, linkedin, notion, outlook, slack, posthog. Build every new integration this way.
+Add the provider to `default_providers()`; the autoloader imports `client.py` at startup. This is the **full port** shape — gmail, google_*, hubspot, linkedin, notion, outlook, slack, posthog, supabase. Build every new integration this way.
 
 #### The older two-folder shape (auth-layer bridge)
 
diff --git a/craftos_integrations/core/system.py b/craftos_integrations/core/system.py
index 76718e232..586471a39 100644
--- a/craftos_integrations/core/system.py
+++ b/craftos_integrations/core/system.py
@@ -210,10 +210,34 @@ def store_credential(
         self, provider_id: str, identity: Optional[str], credential: Dict[str, Any]
     ) -> str:
         """OAuth-completion write path (used by add_account / re-auth)."""
+        known = {a.identity for a in self.accounts.list_accounts(provider_id)}
         stored = self.accounts.upsert_account(provider_id, identity, credential)
+        if stored not in known:
+            self._apply_default_alias(provider_id, stored, credential)
         self.registry.invalidate(provider_id, stored)
         return stored
 
+    def _apply_default_alias(
+        self, provider_id: str, identity: str, credential: Dict[str, Any]
+    ) -> None:
+        """Name a NEW account with the provider's suggestion, if it has one.
+
+        For providers whose identity is opaque (a token fingerprint, a
+        numeric id) — the user sees a name instead of a hash. Never
+        overwrites: runs only on first store, and a suggestion that is
+        taken or invalid is skipped; the user can always rename.
+        """
+        provider = self.registry.get(provider_id)
+        suggest = getattr(provider, "default_alias", None)
+        if suggest is None:
+            return
+        try:
+            alias = suggest(credential)
+            if alias:
+                self.accounts.set_alias(provider_id, identity, alias)
+        except Exception as exc:  # taken alias, provider bug — never fatal
+            logger.info(f"[ACCOUNTS] {provider_id}: default alias skipped ({exc})")
+
     def update_credential(
         self, provider_id: str, identity: str, credential: Dict[str, Any]
     ) -> None:
diff --git a/craftos_integrations/providers/__init__.py b/craftos_integrations/providers/__init__.py
index 8d008b5fe..b1a7b5261 100644
--- a/craftos_integrations/providers/__init__.py
+++ b/craftos_integrations/providers/__init__.py
@@ -36,6 +36,7 @@ def default_providers() -> List[Provider]:
     from .posthog import PostHogProvider
     from .slack import SlackProvider
     from .stripe import StripeProvider
+    from .supabase import SupabaseProvider
     from .telegram_bot import TelegramBotProvider
     from .telegram_user import TelegramUserProvider
     from .twitter import TwitterProvider
@@ -55,6 +56,7 @@ def default_providers() -> List[Provider]:
         OutlookProvider(),
         PostHogProvider(),
         SlackProvider(),
+        SupabaseProvider(),
         # Auth-layer bridges — multi-account storage/UI/listeners; the
         # action surface stays, made account-aware centrally
         # (see app/data/action/integrations/account_bridge.py).
diff --git a/craftos_integrations/providers/supabase/GUIDANCE.md b/craftos_integrations/providers/supabase/GUIDANCE.md
new file mode 100644
index 000000000..caaa3c713
--- /dev/null
+++ b/craftos_integrations/providers/supabase/GUIDANCE.md
@@ -0,0 +1,136 @@
+# Using Supabase
+
+## Load the set that owns the job
+
+The `supabase` action set is a shortlist — it does NOT contain bucket
+management, secrets, user create/update/delete, branches or project
+settings. Before doing any of those, load the set that has them:
+
+| Job | Load |
+|---|---|
+| Buckets (create / update / empty / delete), move / copy files, signed URLs | `supabase_storage` |
+| Edge-function secrets (list / set / delete) | `supabase_secrets` |
+| Auth users (create / update / ban / delete / invite / magic links) | `supabase_auth` |
+| Functions beyond deploy / invoke / delete (metadata, verify_jwt) | `supabase_functions` |
+| Migrations history, rollback on branches | `supabase_migrations` |
+| Projects: create / rename / pause / restore / settings, organizations | `supabase_projects` |
+| Branches | `supabase_branches` |
+| Logs beyond the default, performance advisors, API usage | `supabase_monitoring` |
+
+**Never work around a missing operation with SQL** on Supabase's own schemas:
+`storage.*` (Supabase blocks deleting buckets/objects there — it fails), `auth.*`
+(skips Auth's own cleanup), or `vault.*`. Edge-function secrets are **not** in
+Vault — they're only reachable through `supabase_secrets`. If an operation
+seems missing, the answer is to load its set, not to tell the user to use the
+dashboard.
+
+## Find the project first
+
+Almost every operation takes a `project_ref` — the 20-letter id of a Supabase
+project. If the user hasn't named one and no default is configured, call
+`list_supabase_projects` and match their words against project names. If
+several fit, ask. Projects with status `INACTIVE` are paused: their data APIs
+are offline until `restore_supabase_project`.
+
+## Look before you query
+
+Before reading or writing data in an unfamiliar project, call
+`list_supabase_tables`, then `describe_supabase_table` on the tables you need.
+Guessing column names produces errors and, worse, wrong filters.
+
+## Reading data
+
+- Questions ("how many orders last week", "top customers"): write SQL and
+  run it with **`run_supabase_sql_readonly`**. It cannot change anything, so
+  use it freely. Pass user-supplied values through `parameters` ($1, $2) —
+  never paste them into the SQL string.
+- Fetching specific rows to show or edit: `select_supabase_rows` with
+  PostgREST filters (`{"status": "eq.open"}`), `order`, `limit`. Follow
+  `next_offset` to page.
+- `select_supabase_rows` only reaches schemas exposed to the API (usually
+  `public`). For `auth`, `storage` or private schemas use SQL.
+
+## Changing data
+
+All row, storage and user operations run with the project's service role:
+**Row Level Security does not protect anything here.** So:
+
+- `update_supabase_rows` / `delete_supabase_rows` need `filters`. Run the same
+  filters through `select_supabase_rows` (with `count: true`) first and tell
+  the user how many rows will change before changing more than a handful.
+- `insert_supabase_rows` returns the inserted rows — report the new ids.
+- Use `run_supabase_sql` only for changes the row operations can't express.
+
+## Changing the schema
+
+Use **`apply_supabase_migration`** for any DDL — create/alter table, indexes,
+RLS policies, functions, extensions — with a snake_case `name`. To undo a
+change on a production project, apply a new migration that reverses it
+(`rollback_supabase_migrations` only works on development branches). It is recorded in migration history, which keeps the
+project in sync with the user's local `supabase/migrations`. Don't use
+`run_supabase_sql` for DDL unless the user asks for an untracked change.
+
+After creating a table, enable RLS and add policies in the same migration
+unless the user says otherwise, then run `get_supabase_security_advisors` —
+it flags tables left open.
+
+## Building an app on Supabase
+
+`get_supabase_project_keys` returns the project URL and the publishable key —
+the two values a frontend needs. The secret key is never available to you and
+must never be put in client code. `generate_supabase_typescript_types` gives
+typed table definitions for a TypeScript app.
+
+A brand-new table may take a couple of seconds to become visible to the row
+operations — they retry automatically, so just call them.
+
+## Storage
+
+Files live in buckets. `list_supabase_files` lists one folder level; entries
+with `is_folder: true` are prefixes to list next. Upload from and download to
+absolute local paths. To share a private file, `create_supabase_signed_url`.
+`delete_supabase_bucket` only works on an empty bucket — `empty_supabase_bucket`
+first, after confirming with the user.
+
+## Users
+
+`list_supabase_users` / `get_supabase_user` are the project's end users, not
+Supabase dashboard members (those are `list_supabase_organization_members`).
+`invite_supabase_user` sends an email; `create_supabase_user` doesn't. To ban,
+`update_supabase_user` with `ban_duration` (`"none"` lifts it). Magic or
+recovery links from `generate_supabase_auth_link` are credentials — hand them
+only to the user who asked.
+
+## Edge functions
+
+Deploy with `deploy_supabase_function` and `files: {"index.ts": "..."}`;
+redeploying the same slug replaces the code. Existing source can't be read
+back — if the user wants an edit, ask for the source or find it in their
+workspace. Function config goes in secrets (`set_supabase_secrets`, read in
+code with `Deno.env.get`). Test with `invoke_supabase_function`, and when it
+fails, `get_supabase_logs` with `source: "edge_function_runtime"`.
+
+## Debugging a project
+
+1. `get_supabase_project_health` — is a service down?
+2. `get_supabase_logs` — `postgres` for database errors, `api` for HTTP
+   errors, `auth` for login problems; narrow with `search`.
+3. `get_supabase_security_advisors` / `get_supabase_performance_advisors`.
+
+## Things that need a yes from the user first
+
+Deleting or pausing a project, `rollback_supabase_migrations`,
+`empty_supabase_bucket`, deleting users, `create_supabase_project` and
+`create_supabase_branch` (both can cost money), and any bulk row change.
+
+## Read-only mode
+
+If an operation fails with "read-only mode", the user has switched the
+integration to read-only in Settings. Tell them; don't look for a workaround.
+
+## Multiple accounts
+
+A personal-access-token account sees every organization its user belongs to.
+An OAuth account sees only the organization chosen when it was connected —
+to add a different organization, connect again and pick that organization on
+Supabase's consent screen.
diff --git a/craftos_integrations/providers/supabase/INTEGRATION.md b/craftos_integrations/providers/supabase/INTEGRATION.md
new file mode 100644
index 000000000..e93f736c6
--- /dev/null
+++ b/craftos_integrations/providers/supabase/INTEGRATION.md
@@ -0,0 +1,167 @@
+# Supabase — integration notes
+
+For whoever debugs this at 2am. Agent-facing advice lives in `GUIDANCE.md`.
+
+## Two planes, one credential
+
+| Plane | Base URL | Auth | Used for |
+|---|---|---|---|
+| Management API | `https://api.supabase.com/v1` | `Authorization: Bearer <PAT or OAuth token>` | projects, orgs, SQL, migrations, functions (manage), branches, secrets, logs, advisors, service config |
+| Project APIs | `https://<ref>.supabase.co` | the project's **secret** key | PostgREST rows (`/rest/v1`), Storage (`/storage/v1`), Auth admin (`/auth/v1`), function invoke (`/functions/v1`) |
+
+The user never pastes a project key. `SupabaseClient._keys_for(ref)` calls
+`GET /v1/projects/{ref}/api-keys?reveal=true` once per project per client
+instance and keeps the result **in memory only** — never persisted, never
+returned to the agent (`get_supabase_project_keys` returns only the URL and
+the publishable key). A 401 from a project API invalidates the cache and
+retries once, which is what a rotated key looks like.
+
+Needs the `secrets:read` permission (OAuth) — without it every data-plane
+operation fails with "Could not read API keys for project …".
+
+### Key formats on the data plane
+
+- **New keys** — `sb_secret_…` / `sb_publishable_…`. Not JWTs. Sent in the
+  `apikey` header only; putting one in `Authorization: Bearer` is rejected
+  by the gateway.
+- **Legacy keys** — `anon` / `service_role`, both JWTs (`eyJ…`). Sent in
+  both `apikey` and `Authorization`.
+
+The client prefers a `secret` key, falls back to legacy `service_role`.
+
+**Edge-function invocation** with `verify_jwt=true` needs a JWT in
+`Authorization`. Only legacy keys are JWTs, so `invoke_function` prefers the
+legacy service_role key when the project still has legacy keys enabled. A
+project that has *disabled* legacy keys and has a verify_jwt function will
+answer 401 to `invoke_supabase_function` — redeploy it with
+`verify_jwt=false` and check auth inside the function, or invoke it with a
+user JWT in `headers`. **Unverified live** — confirm in the smoke test.
+
+### Service role bypasses RLS
+
+Every data-plane operation acts as the service role: Row Level Security does
+not apply. That matches the dashboard table editor and is what "manage my
+Supabase" means, but it is why `update_supabase_rows` / `delete_supabase_rows`
+refuse empty `filters`, and why `GUIDANCE.md` tells the agent to confirm bulk
+changes.
+
+## Identifiers
+
+| Resource | Shape | Example |
+|---|---|---|
+| Project | ref, 20 lowercase letters | `abcdefghijklmnopqrst` |
+| Organization | slug | `acme-inc` (older orgs: 20-letter ref-like string) |
+| Branch | UUID, or the branch's own project ref | both accepted by `/v1/branches/{id_or_ref}` |
+| Edge function | slug `^[A-Za-z][A-Za-z0-9_-]*$` | `hello-world` |
+| Migration | version, timestamp digits | `20250312000000` |
+| Auth user | UUID | `7f3c2a10-…` |
+| Storage object | `<bucket>` + `/`-separated path, no leading slash | `avatars` + `users/42/a.png` |
+
+`project_ref` falls back to the `default_project_ref` config knob. **Except**
+`delete_supabase_project`, which requires it explicitly.
+
+## Auth
+
+### Personal access token (always available)
+
+`sbp_…`, from supabase.com/dashboard/account/tokens. Never expires unless
+revoked; `refresh()` returns None. Spans every organization the user is in.
+
+**`/v1/profile` answers 403 to personal access tokens** (seen live
+2026-10-05; the schema gives it no permission scope, unlike every endpoint a
+PAT can call). So validity is checked with `GET /v1/organizations`, profile is
+best-effort, and identity is `token:<sha256(token)[:16]>` unless the profile
+happened to be readable (`user:<gotrue_id>`). Same token reconnected → same
+account; a new token → a new account (remove the old one).
+
+`verify_token` distinguishes 401 (invalid / revoked) from 403 (token valid,
+access refused).
+
+`verify_token` rejects `sb_secret_`, `sb_publishable_` and `eyJ…` (anon /
+service_role JWT) by prefix — the three things people paste by mistake.
+Other unknown prefixes are still tried, deliberately.
+
+### OAuth (one-click, once our app is registered)
+
+- Endpoints confirmed via `https://api.supabase.com/.well-known/oauth-authorization-server`:
+  authorize `/v1/oauth/authorize`, token `/v1/oauth/token`, PKCE S256,
+  `client_secret_basic`. Refresh tokens issued.
+- **Infra to do:** register a Supabase OAuth app (Organization settings →
+  OAuth Apps), redirect URI `http://localhost:8765`, tick the permissions in
+  `SUPABASE_SCOPES` (client.py). Put the id/secret in
+  `SUPABASE_SHARED_CLIENT_ID` / `SUPABASE_SHARED_CLIENT_SECRET` (env, or the
+  embedded credential registry under service `supabase`).
+- `auth_type` is a property: `"token"` until both keys are configured,
+  `"both"` after. Nothing else changes.
+- Permissions are fixed on the app registration; the authorize URL carries
+  no `scope`.
+- An OAuth grant is scoped to the organization the user picks on the consent
+  screen → identity `org:<slug>`.
+- Access tokens expire; the client refreshes inline (`_ensure_token`,
+  2-minute margin, serialized by a lock) and persists through the core.
+
+### Failure modes
+
+| Symptom | Meaning |
+|---|---|
+| 401 on Management API | token revoked / expired OAuth token that failed to refresh. Reconnect. |
+| 403 on Management API | OAuth app lacks the permission for that endpoint, or the user's org role is read-only. Retrying won't help. |
+| "Could not read API keys for project …" | no `secrets:read`, or the project is paused (`INACTIVE`). |
+| 404 on `/rest/v1/<table>` | table not in an exposed schema (PostgREST `db_schema`), or doesn't exist. Use SQL. |
+| 400 `PGRST…` codes | PostgREST query error — bad filter syntax or column name. Body says which. |
+| 540 / connection error on data plane | project paused. `restore_supabase_project`. |
+
+## Rate limits
+
+- Management API: documented at roughly **120 requests / minute per user**
+  (per token), across all projects — re-check the current number in
+  Supabase's docs if 429s show up. Bursty agents on large accounts can hit it — `list_supabase_*`
+  then fan-out is the usual cause. 429 = wait a minute.
+- Project APIs are not rate-limited by the gateway beyond the plan's compute;
+  heavy `select_supabase_rows` paging is bounded by `max_rows` config
+  (default 500 per call).
+- Logs API: window ≤ 24h per query (`get_logs` clamps `minutes` to 1440).
+
+## Read-only mode
+
+Config `read_only = true` makes every mutating client method raise before
+any request (`_guard_write`). The SQL read path uses Supabase's dedicated
+`/database/query/read-only` endpoint, which runs as `supabase_read_only_user`
+— a database-enforced guarantee, not a regex on the SQL.
+
+## Live findings (2026-10-05, scratch project)
+
+- **PostgREST schema cache.** Right after DDL the row API answers 404
+  `PGRST205` for a few seconds. `SupabaseClient._rest` sends
+  `notify pgrst, 'reload schema'` and retries (1s, 2.5s).
+- **Migration rollback is branch-only.** `DELETE /database/migrations` on a
+  production project → 400 "You cannot rollback a production branch". Undo on
+  production = a new reversing migration.
+- **Logs API moved.** `logs.all` → 410 Gone. `logs` takes ClickHouse SQL over
+  one `logs` table filtered by `source_name`; nested fields in
+  `log_attributes[...]`. Failed queries come back as HTTP 200 with
+  `{"error": ...}` in the body — `_analytics_result` turns that into an error.
+  On the test project every query (even `SELECT 1`) returned "Backend error!"
+  — a Supabase-side outage for that project, not a query problem. The logs
+  endpoint has its own, tighter throttle (429 after ~10 quick calls).
+- **Organizations can be invisible.** A valid token listed zero
+  organizations (and 403 on members) while reaching a project in one —
+  connect messages describe reach by projects.
+- **`/v1/profile` is 403 for PATs** — see Auth above.
+
+## What isn't here and why
+
+See the exclusion block at the bottom of `operations.py`. Notably: billing,
+API-key and signing-key admin, SSO, network restrictions, backup restore /
+PITR, Postgres upgrades, custom domains.
+
+Function **source** can't be read back: `GET /functions/{slug}/body` returns
+the compiled eszip bundle, not the files. Keep source in the workspace.
+
+## No listener
+
+Supabase's push channels are database webhooks (need a public URL) and
+Realtime (a websocket per project, per table). Neither fits the per-account
+listener model without the user choosing what to watch — a v2 candidate:
+poll a user-chosen table via `select_supabase_rows` with an `updated_at`
+cursor.
diff --git a/craftos_integrations/providers/supabase/__init__.py b/craftos_integrations/providers/supabase/__init__.py
new file mode 100644
index 000000000..cc21fbf4d
--- /dev/null
+++ b/craftos_integrations/providers/supabase/__init__.py
@@ -0,0 +1,3 @@
+from .provider import SupabaseProvider
+
+__all__ = ["SupabaseProvider"]
diff --git a/craftos_integrations/providers/supabase/client.py b/craftos_integrations/providers/supabase/client.py
new file mode 100644
index 000000000..521ea6a6f
--- /dev/null
+++ b/craftos_integrations/providers/supabase/client.py
@@ -0,0 +1,1949 @@
+# -*- coding: utf-8 -*-
+"""Supabase integration — one credential, two API planes.
+
+Supabase exposes two separate HTTP surfaces and this client covers both:
+
+- **Management API** (``https://api.supabase.com/v1``) — the control plane.
+  Projects, organizations, SQL, migrations, edge functions, branches,
+  secrets, logs, advisors, service config. Authenticated with the
+  connected account's bearer token (a personal access token ``sbp_...``
+  or an OAuth access token). One token reaches every project the account
+  can see.
+
+- **Project APIs** (``https://<ref>.supabase.co``) — the data plane.
+  PostgREST rows, Storage objects, Auth (GoTrue) admin, edge-function
+  invocation. Each project needs its *own* key. Rather than make the user
+  paste one per project, the client fetches the project's secret key
+  through the Management API (``GET /v1/projects/{ref}/api-keys?reveal=true``)
+  on first use and caches it in memory for the life of the client. The
+  key is never persisted and never returned to the agent.
+
+That secret key bypasses Row Level Security — data-plane operations act
+with full privileges, exactly like the dashboard's table editor. See
+INTEGRATION.md for the consequences and GUIDANCE.md for how the agent is
+told to handle them.
+
+See INTEGRATION.md for identifier shapes, key-format quirks, rate limits
+and auth failure modes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import mimetypes
+import re
+import os
+import time
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+
+from ... import BasePlatformClient, load_config, register_client
+from ...config import ConfigStore
+from ...helpers import Result, arequest
+from ...helpers import request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+SUPABASE_API = "https://api.supabase.com"
+SUPABASE_MGMT = f"{SUPABASE_API}/v1"
+
+# OAuth — confirmed against /.well-known/oauth-authorization-server.
+# Supabase OAuth apps are confidential clients (client_secret_basic/post)
+# and support PKCE S256. Referenced by the provider.
+SUPABASE_OAUTH_AUTHORIZE = f"{SUPABASE_MGMT}/oauth/authorize"
+SUPABASE_OAUTH_TOKEN = f"{SUPABASE_MGMT}/oauth/token"
+SUPABASE_CLIENT_ID_KEY = "SUPABASE_SHARED_CLIENT_ID"
+SUPABASE_CLIENT_SECRET_KEY = "SUPABASE_SHARED_CLIENT_SECRET"
+
+# The permission set this integration's surface needs. Supabase OAuth apps
+# fix their permissions at registration time (org settings → OAuth Apps),
+# so this tuple documents what to tick there; it is not sent on the
+# authorize URL.
+SUPABASE_SCOPES = (
+    "organizations:read",
+    "projects:read",
+    "projects:write",
+    "database:read",
+    "database:write",
+    "analytics:read",
+    "auth:read",
+    "auth:write",
+    "edge_functions:read",
+    "edge_functions:write",
+    "environment:read",
+    "environment:write",
+    "secrets:read",
+    "secrets:write",
+    "storage:read",
+    "storage:write",
+    "rest:read",
+    "rest:write",
+)
+
+# Service configs reachable through get/update_supabase_service_config.
+# Value: (path under /projects/{ref}/, update method).
+SERVICE_CONFIG_PATHS: Dict[str, Tuple[str, str]] = {
+    "auth": ("config/auth", "PATCH"),
+    "postgrest": ("postgrest", "PATCH"),
+    "realtime": ("config/realtime", "PATCH"),
+    "storage": ("config/storage", "PATCH"),
+    "postgres": ("config/database/postgres", "PUT"),
+}
+
+# Log sources for get_supabase_logs → the analytics table behind each.
+LOG_SOURCES: Dict[str, str] = {
+    "api": "edge_logs",
+    "postgres": "postgres_logs",
+    "auth": "auth_logs",
+    "storage": "storage_logs",
+    "realtime": "realtime_logs",
+    "edge_function": "function_edge_logs",
+    "edge_function_runtime": "function_logs",
+    "postgrest": "postgrest_logs",
+    "pooler": "supavisor_logs",
+}
+
+HEALTH_SERVICES = ("auth", "db", "pooler", "realtime", "rest", "storage")
+
+_EXPECT_READ = (200,)
+_EXPECT_WRITE = (200, 201, 202, 204)
+
+# Refresh OAuth access tokens this many seconds before they expire.
+_REFRESH_MARGIN = 120
+
+
+@dataclass
+class SupabaseCredential:
+    # Bearer token for the Management API: a personal access token
+    # (``sbp_...``) or an OAuth access token.
+    access_token: str = ""
+    # "token" (PAT pasted by the user) or "oauth".
+    auth_kind: str = "token"
+    refresh_token: str = ""
+    # Epoch seconds; 0 = never expires (PATs).
+    token_expiry: float = 0.0
+    # Identity. PAT accounts span every org the user belongs to and are
+    # keyed by a fingerprint of the token (the API won't name the user to
+    # a PAT); OAuth grants are scoped to one organization and keyed by it.
+    token_id: str = ""
+    # Human name suggested for the account at connect time (see
+    # SupabaseProvider.default_alias); the identity itself is opaque.
+    display_name: str = ""
+    user_id: str = ""
+    email: str = ""
+    username: str = ""
+    org_slug: str = ""
+    org_name: str = ""
+
+
+@dataclass
+class SupabaseConfig:
+    """Post-connect runtime knobs."""
+
+    # Project ref used when an operation omits ``project_ref``.
+    default_project_ref: str = ""
+    # When True every mutating operation is refused client-side — the same
+    # guarantee as the official Supabase MCP server's --read-only flag.
+    read_only: bool = False
+    # Ceiling on rows returned by SQL helpers and select_supabase_rows.
+    max_rows: int = 500
+
+
+class ReadOnlyModeError(RuntimeError):
+    pass
+
+
+def _clamp(value: Any, low: int, high: int, default: int) -> int:
+    try:
+        number = int(value)
+    except (TypeError, ValueError):
+        return default
+    return min(max(number, low), high)
+
+
+def _clean(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Drop keys the caller did not set, so a PATCH never blanks a field."""
+    return {k: v for k, v in payload.items() if v is not None}
+
+
+def _object_path(path: str) -> str:
+    """URL-encode a storage object path, keeping its ``/`` separators."""
+    return "/".join(quote(part, safe="") for part in path.strip("/").split("/"))
+
+
+def _is_jwt(key: str) -> bool:
+    return key.startswith("eyJ") and key.count(".") == 2
+
+
+_DDL_START = re.compile(
+    r"^\s*(create|alter|drop|comment\s+on|grant|revoke)\b", re.IGNORECASE
+)
+_DDL_OBJECT = re.compile(
+    r"^\s*(create(?:\s+or\s+replace)?|alter|drop|comment\s+on|grant|revoke)\s+"
+    r"(?:unique\s+|materialized\s+|temp(?:orary)?\s+)?"
+    r"(table|view|index|function|policy|trigger|type|schema|extension|sequence|"
+    r"role|column)?\s*(?:if\s+(?:not\s+)?exists\s+)?((?:\w+\.)?(?:\"[^\"]+\"|\w+))?",
+    re.IGNORECASE,
+)
+
+
+def _sql_statements(query: str) -> List[str]:
+    """Statements of a SQL script with comments removed (dollar-quoted
+    bodies are kept intact so a function body doesn't split)."""
+    text = re.sub(r"/\*.*?\*/", " ", query, flags=re.DOTALL)
+    text = re.sub(r"--[^\n]*", " ", text)
+    parts, buf, in_dollar = [], [], None
+    for token in re.split(r"(\$[A-Za-z_]*\$|;)", text):
+        if token is None:
+            continue
+        if re.fullmatch(r"\$[A-Za-z_]*\$", token):
+            in_dollar = None if in_dollar == token else (in_dollar or token)
+            buf.append(token)
+        elif token == ";" and not in_dollar:
+            parts.append("".join(buf)); buf = []
+        else:
+            buf.append(token)
+    parts.append("".join(buf))
+    return [p.strip() for p in parts if p.strip()]
+
+
+def ddl_migration_name(query: str) -> Optional[str]:
+    """A snake_case migration name if the script changes the schema, else
+    None. Temporary objects don't count — they vanish with the session."""
+    for statement in _sql_statements(query):
+        if not _DDL_START.match(statement):
+            continue
+        if re.match(r"^\s*create\s+temp(orary)?\b", statement, re.IGNORECASE):
+            continue
+        m = _DDL_OBJECT.match(statement)
+        words = [w for w in (m.groups() if m else ()) if w]
+        name = "_".join(words).lower()
+        name = re.sub(r"[^a-z0-9]+", "_", name.replace('"', "")).strip("_")
+        name = re.sub(r"^(\w+?)_public_", r"\1_", name)  # drop default schema
+        return (name or "schema_change")[:60]
+    return None
+
+
+def _ch_literal(value: str) -> str:
+    """Quote a value as a ClickHouse string literal (logs SQL)."""
+    return "'" + str(value).replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+
+def _analytics_result(result: Result) -> Result:
+    """Analytics endpoints answer HTTP 200 with ``{"error": ...}`` in the
+    body when the query fails (bad SQL, unknown table). Surface that as a
+    failure instead of a success that happens to contain an error."""
+    if "error" in result:
+        return result
+    body = result.get("result")
+    if isinstance(body, dict) and body.get("error"):
+        return {"error": "Log query failed", "details": body["error"]}
+    if isinstance(body, dict) and "result" in body:
+        return {"ok": True, "result": body["result"]}
+    return result
+
+
+def _shape_response(r: httpx.Response, expected: Iterable[int]) -> Result:
+    if r.status_code in expected:
+        if not r.content:
+            return {"ok": True, "result": {}}
+        try:
+            return {"ok": True, "result": r.json()}
+        except Exception:
+            return {"ok": True, "result": r.text}
+    return {"error": f"API error: {r.status_code}", "details": r.text[:2000]}
+
+
+@register_client
+class SupabaseClient(BasePlatformClient):
+    """Supabase client, one instance per connected account.
+
+    Credential-injected: the provider calls ``bind_credential`` before
+    use. There is no disk-credential path — Supabase is a greenfield
+    integration.
+    """
+
+    PLATFORM_ID = "supabase"
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._cred: Optional[SupabaseCredential] = None
+        self._persist = None
+        # project ref → {"secret": key, "publishable": key, "jwt": key|None}
+        self._project_keys: Dict[str, Dict[str, Optional[str]]] = {}
+        self._token_lock = asyncio.Lock()
+
+    # ── credential plumbing ──────────────────────────────────────────
+
+    def bind_credential(self, credential: Dict[str, Any], persist) -> None:
+        known = set(SupabaseCredential.__dataclass_fields__)
+        self._cred = SupabaseCredential(
+            **{k: v for k, v in credential.items() if k in known}
+        )
+        self._persist = persist
+        self._project_keys.clear()
+
+    def has_credentials(self) -> bool:
+        return self._cred is not None and bool(self._cred.access_token)
+
+    def _load(self) -> SupabaseCredential:
+        if self._cred is None:
+            raise RuntimeError("client used before bind_credential()")
+        return self._cred
+
+    def _config(self) -> SupabaseConfig:
+        # Read fresh so a config change takes effect without a restart.
+        return load_config("supabase_config.json", SupabaseConfig) or SupabaseConfig()
+
+    def _guard_write(self) -> None:
+        if self._config().read_only:
+            raise ReadOnlyModeError(
+                "Supabase integration is in read-only mode (integration config "
+                "'read_only'). Turn it off in Settings → Integrations → Supabase "
+                "to allow changes."
+            )
+
+    def _ref(self, project_ref: Optional[str]) -> str:
+        ref = (project_ref or self._config().default_project_ref or "").strip()
+        if not ref:
+            raise ValueError(
+                "project_ref is required — call list_supabase_projects to find "
+                "the 20-character project ref, or set a default project in the "
+                "integration config."
+            )
+        return ref
+
+    def _max_rows(self) -> int:
+        return _clamp(self._config().max_rows, 1, 10000, 500)
+
+    # ── OAuth token lifecycle ────────────────────────────────────────
+
+    def _refresh_sync(self) -> bool:
+        cred = self._load()
+        client_id = ConfigStore.get_oauth(SUPABASE_CLIENT_ID_KEY)
+        client_secret = ConfigStore.get_oauth(SUPABASE_CLIENT_SECRET_KEY)
+        if not (client_id and client_secret and cred.refresh_token):
+            logger.warning(
+                "[SUPABASE] Cannot refresh OAuth token (missing client "
+                "credentials or refresh token). Reconnect the account."
+            )
+            return False
+        result = http_request(
+            "POST",
+            SUPABASE_OAUTH_TOKEN,
+            data={"grant_type": "refresh_token", "refresh_token": cred.refresh_token},
+            headers={
+                "Authorization": "Basic "
+                + base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()
+            },
+            expected=(200, 201),
+            timeout=30.0,
+        )
+        if "error" in result:
+            logger.warning(f"[SUPABASE] Token refresh failed: {result.get('error')}")
+            return False
+        data = result.get("result") or {}
+        token = data.get("access_token")
+        if not token:
+            return False
+        cred.access_token = token
+        cred.refresh_token = data.get("refresh_token") or cred.refresh_token
+        expires_in = data.get("expires_in") or 3600
+        cred.token_expiry = time.time() + float(expires_in)
+        if self._persist:
+            self._persist(asdict(cred))
+        logger.info("[SUPABASE] OAuth access token refreshed.")
+        return True
+
+    async def _ensure_token(self) -> str:
+        cred = self._load()
+        if (
+            cred.auth_kind == "oauth"
+            and cred.token_expiry
+            and time.time() > cred.token_expiry - _REFRESH_MARGIN
+        ):
+            async with self._token_lock:
+                if time.time() > cred.token_expiry - _REFRESH_MARGIN:
+                    await asyncio.to_thread(self._refresh_sync)
+        return cred.access_token
+
+    # ── transport: Management API ────────────────────────────────────
+
+    async def _mgmt(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json_body: Any = None,
+        data: Any = None,
+        files: Any = None,
+        expected: Iterable[int] = _EXPECT_READ,
+        timeout: float = 30.0,
+    ) -> Result:
+        token = await self._ensure_token()
+        headers = {"Authorization": f"Bearer {token}"}
+        result = await arequest(
+            method,
+            f"{SUPABASE_MGMT}/{path.lstrip('/')}",
+            headers=headers,
+            params=params,
+            json=json_body,
+            data=data,
+            files=files,
+            expected=expected,
+            timeout=timeout,
+        )
+        if result.get("error") == "API error: 403":
+            # Supabase's body is a bare {"message":"Forbidden"}; say what it
+            # means so the agent stops instead of retrying variations.
+            result["details"] = (
+                f"{str(result.get('details') or '')[:200]} — Supabase refused this "
+                "for the connected account. The token works but lacks "
+                "permission here: usually the user's organization role (e.g. "
+                "Developer instead of Owner/Administrator) or how the token was "
+                "scoped. Retrying won't help; the user must change the role or "
+                "connect a token with more access."
+            ).strip()
+        return result
+
+    async def _mgmt_text(self, path: str, params: Dict[str, Any]) -> Result:
+        """GET a Management endpoint whose 200 body may be plain text."""
+        token = await self._ensure_token()
+
+        def _go() -> Result:
+            try:
+                r = httpx.get(
+                    f"{SUPABASE_MGMT}/{path.lstrip('/')}",
+                    headers={"Authorization": f"Bearer {token}"},
+                    params=params,
+                    timeout=60.0,
+                )
+                return _shape_response(r, _EXPECT_READ)
+            except Exception as e:
+                return {"error": str(e)}
+
+        return await asyncio.to_thread(_go)
+
+    # ── transport: project data plane ────────────────────────────────
+
+    async def _keys_for(self, ref: str, *, refresh: bool = False) -> Dict[str, Optional[str]]:
+        if not refresh and ref in self._project_keys:
+            return self._project_keys[ref]
+        result = await self._mgmt(
+            "GET", f"projects/{ref}/api-keys", params={"reveal": "true"}
+        )
+        if "error" in result:
+            raise RuntimeError(
+                f"Could not read API keys for project {ref}: {result['error']} "
+                f"{str(result.get('details') or '')[:200]}".strip()
+                + " — the connected account needs the secrets:read permission "
+                "on this project."
+            )
+        keys: Dict[str, Optional[str]] = {"secret": None, "publishable": None, "jwt": None}
+        legacy_anon: Optional[str] = None
+        for item in result.get("result") or []:
+            kind = item.get("type")
+            name = (item.get("name") or "").lower()
+            value = item.get("api_key")
+            if not value:
+                continue
+            if kind == "secret" and not keys["secret"]:
+                keys["secret"] = value
+            elif kind == "publishable" and not keys["publishable"]:
+                keys["publishable"] = value
+            elif kind == "legacy" and name == "service_role":
+                keys["jwt"] = value
+            elif kind == "legacy" and name == "anon":
+                legacy_anon = value
+        # New-style keys win regardless of the order Supabase lists them in.
+        keys["publishable"] = keys["publishable"] or legacy_anon
+        if not keys["secret"]:
+            keys["secret"] = keys["jwt"]
+        if not keys["secret"]:
+            raise RuntimeError(
+                f"Project {ref} has no secret or service_role key available. "
+                "Create a secret key under Project Settings → API Keys."
+            )
+        self._project_keys[ref] = keys
+        return keys
+
+    @staticmethod
+    def _project_url(ref: str) -> str:
+        return f"https://{ref}.supabase.co"
+
+    async def _data(
+        self,
+        ref: str,
+        method: str,
+        path: str,
+        *,
+        params: Any = None,
+        json_body: Any = None,
+        content: Optional[bytes] = None,
+        headers: Optional[Dict[str, str]] = None,
+        expected: Iterable[int] = _EXPECT_WRITE,
+        timeout: float = 60.0,
+        prefer_jwt: bool = False,
+        raw: bool = False,
+    ) -> Tuple[Result, Optional[httpx.Response]]:
+        """Request against ``https://<ref>.supabase.co``.
+
+        Retries once with freshly fetched keys on 401, which is what a
+        rotated or revoked key looks like. ``raw=True`` hands back the
+        response for callers that need headers or bytes.
+        """
+        url = f"{self._project_url(ref)}/{path.lstrip('/')}"
+
+        def _send(keys: Dict[str, Optional[str]]) -> httpx.Response:
+            key = (keys.get("jwt") if prefer_jwt else None) or keys["secret"] or ""
+            h = {"apikey": key}
+            # Legacy keys are JWTs and go in Authorization too. The new
+            # sb_secret_ keys are not JWTs: the gateway rejects them in
+            # Authorization and mints the JWT itself from ``apikey``.
+            if _is_jwt(key):
+                h["Authorization"] = f"Bearer {key}"
+            if headers:
+                h.update(headers)
+            return httpx.request(
+                method,
+                url,
+                params=params,
+                json=json_body if content is None else None,
+                content=content,
+                headers=h,
+                timeout=timeout,
+            )
+
+        try:
+            keys = await self._keys_for(ref)
+            r = await asyncio.to_thread(_send, keys)
+            if r.status_code == 401:
+                keys = await self._keys_for(ref, refresh=True)
+                r = await asyncio.to_thread(_send, keys)
+        except Exception as e:
+            return {"error": str(e)}, None
+        if raw:
+            return (
+                {"ok": True, "result": {}}
+                if r.status_code in expected
+                else {"error": f"API error: {r.status_code}", "details": r.text[:2000]}
+            ), r
+        return _shape_response(r, expected), r
+
+    async def _rest(self, ref: str, *args: Any, **kwargs: Any):
+        """PostgREST request that survives a stale schema cache.
+
+        PostgREST caches the database schema. Right after a table or
+        function is created (apply_supabase_migration / run_supabase_sql)
+        it answers 404 PGRST205 / PGRST202 — "could not find the table /
+        function in the schema cache" — for a few seconds (seen live). Ask
+        it to reload, wait, retry; a real "no such table" still fails, just
+        after the retries.
+        """
+        result, response = await self._data(ref, *args, **kwargs)
+        for delay in (1.0, 2.5):
+            details = str(result.get("details") or "") if "error" in result else ""
+            if "PGRST205" not in details and "PGRST202" not in details:
+                break
+            # Internal maintenance, not a user write — bypasses read-only.
+            await self._mgmt(
+                "POST",
+                f"projects/{ref}/database/query",
+                json_body={"query": "notify pgrst, 'reload schema';"},
+                expected=_EXPECT_WRITE,
+            )
+            await asyncio.sleep(delay)
+            result, response = await self._data(ref, *args, **kwargs)
+        return result, response
+
+    # ── BasePlatformClient contract ──────────────────────────────────
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        """Supabase has no messaging surface.
+
+        The closest equivalent is invoking an edge function: ``recipient``
+        is read as ``<project_ref>/<function_slug>`` and ``text`` is sent as
+        the JSON body ``{"message": text}``.
+        """
+        ref, _, slug = (recipient or "").partition("/")
+        if not ref or not slug:
+            return {
+                "error": "Supabase has no messaging; recipient must be "
+                "'<project_ref>/<function_slug>' to invoke an edge function."
+            }
+        return await self.invoke_function(slug, body={"message": text}, project_ref=ref)
+
+    # =================================================================
+    # Account, organizations, projects
+    # =================================================================
+
+    async def get_profile(self) -> Result:
+        return await self._mgmt("GET", "profile")
+
+    async def list_organizations(self) -> Result:
+        """Organizations the account belongs to.
+
+        Some tokens get an empty list here while still reaching projects
+        inside an organization (seen live). Then the organizations are
+        recovered from the projects, so the agent still has a slug for
+        list_supabase_regions / create_supabase_project.
+        """
+        result = await self._mgmt("GET", "organizations")
+        if "error" in result or result.get("result"):
+            return result
+        projects = await self._mgmt("GET", "projects")
+        if "error" in projects:
+            return result
+        seen: Dict[str, Dict[str, Any]] = {}
+        for project in projects.get("result") or []:
+            slug = project.get("organization_slug")
+            if slug and slug not in seen:
+                seen[slug] = {
+                    "slug": slug,
+                    "name": None,
+                    "projects": [],
+                    "source": "derived from your projects — this token can't "
+                    "list organizations directly",
+                }
+            if slug:
+                seen[slug]["projects"].append(project.get("name"))
+        return {"ok": True, "result": list(seen.values())}
+
+    async def list_organization_members(self, organization_slug: str) -> Result:
+        result = await self._mgmt("GET", f"organizations/{organization_slug}/members")
+        if "403" in str(result.get("error") or ""):
+            return {
+                "error": "Supabase refused to list this organization's members (403).",
+                "details": "Member lists need an organization owner/admin role, or a "
+                "token allowed to read the organization. Project operations are "
+                "unaffected.",
+            }
+        return result
+
+    async def list_projects(self, *, organization_slug: Optional[str] = None) -> Result:
+        result = await self._mgmt("GET", "projects")
+        if "error" in result or not organization_slug:
+            return result
+        projects = [
+            p
+            for p in result.get("result") or []
+            if p.get("organization_slug") == organization_slug
+        ]
+        return {"ok": True, "result": projects}
+
+    async def get_project(self, project_ref: Optional[str] = None) -> Result:
+        return await self._mgmt("GET", f"projects/{self._ref(project_ref)}")
+
+    async def list_regions(
+        self, organization_slug: str, *, continent: Optional[str] = None
+    ) -> Result:
+        params = _clean({"organization_slug": organization_slug, "continent": continent})
+        return await self._mgmt("GET", "projects/available-regions", params=params)
+
+    async def create_project(
+        self,
+        *,
+        name: str,
+        organization_slug: str,
+        db_pass: Optional[str] = None,
+        region: Optional[str] = None,
+        desired_instance_size: Optional[str] = None,
+    ) -> Result:
+        """Create a project. Generates a strong database password when none
+        is given and returns it — it is shown once and needed for direct
+        Postgres connections."""
+        self._guard_write()
+        import secrets as _secrets
+
+        generated = not db_pass
+        password = db_pass or _secrets.token_urlsafe(24)
+        body: Dict[str, Any] = {
+            "name": name,
+            "organization_slug": organization_slug,
+            "db_pass": password,
+        }
+        if region:
+            smart = region.lower() in ("americas", "emea", "apac")
+            body["region_selection"] = {
+                "type": "smartGroup" if smart else "specific",
+                "code": region.lower() if smart else region,
+            }
+        if desired_instance_size:
+            body["desired_instance_size"] = desired_instance_size
+        result = await self._mgmt(
+            "POST", "projects", json_body=body, expected=_EXPECT_WRITE, timeout=60.0
+        )
+        if "error" not in result and generated and isinstance(result.get("result"), dict):
+            result["result"]["generated_db_password"] = password
+        return result
+
+    async def update_project(self, name: str, *, project_ref: Optional[str] = None) -> Result:
+        self._guard_write()
+        return await self._mgmt(
+            "PATCH",
+            f"projects/{self._ref(project_ref)}",
+            json_body={"name": name},
+            expected=_EXPECT_WRITE,
+        )
+
+    async def delete_project(self, project_ref: str) -> Result:
+        self._guard_write()
+        # Explicit ref only — never fall back to the default project here.
+        if not project_ref:
+            return {"error": "project_ref is required to delete a project."}
+        return await self._mgmt(
+            "DELETE", f"projects/{project_ref}", expected=_EXPECT_WRITE, timeout=60.0
+        )
+
+    async def pause_project(self, project_ref: Optional[str] = None) -> Result:
+        self._guard_write()
+        return await self._mgmt(
+            "POST", f"projects/{self._ref(project_ref)}/pause", expected=_EXPECT_WRITE
+        )
+
+    async def restore_project(self, project_ref: Optional[str] = None) -> Result:
+        """Un-pause a paused project (POST /restore — not a backup restore)."""
+        self._guard_write()
+        return await self._mgmt(
+            "POST", f"projects/{self._ref(project_ref)}/restore", expected=_EXPECT_WRITE
+        )
+
+    async def restart_project(self, project_ref: Optional[str] = None) -> Result:
+        self._guard_write()
+        return await self._mgmt(
+            "POST", f"projects/{self._ref(project_ref)}/restart", expected=_EXPECT_WRITE
+        )
+
+    async def get_project_health(
+        self,
+        *,
+        services: Optional[List[str]] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        chosen = [s for s in (services or HEALTH_SERVICES) if s in HEALTH_SERVICES]
+        return await self._mgmt(
+            "GET",
+            f"projects/{self._ref(project_ref)}/health",
+            params={"services": ",".join(chosen or HEALTH_SERVICES)},
+        )
+
+    async def get_project_keys(self, project_ref: Optional[str] = None) -> Result:
+        """Project URL + the *publishable* (anon) key — the two values a
+        client app needs. The secret key is deliberately not returned."""
+        ref = self._ref(project_ref)
+        try:
+            keys = await self._keys_for(ref)
+        except Exception as e:
+            return {"error": str(e)}
+        return {
+            "ok": True,
+            "result": {
+                "project_ref": ref,
+                "url": self._project_url(ref),
+                "publishable_key": keys.get("publishable"),
+                "note": "Safe to embed in client apps when Row Level Security is "
+                "enabled. The secret/service_role key is never exposed here.",
+            },
+        }
+
+    async def get_service_config(
+        self, service: str, *, project_ref: Optional[str] = None
+    ) -> Result:
+        if service not in SERVICE_CONFIG_PATHS:
+            return {
+                "error": f"Unknown service {service!r}; one of "
+                f"{', '.join(SERVICE_CONFIG_PATHS)}"
+            }
+        path, _ = SERVICE_CONFIG_PATHS[service]
+        result = await self._mgmt("GET", f"projects/{self._ref(project_ref)}/{path}")
+        if "error" not in result and isinstance(result.get("result"), dict):
+            # Never surface signing material to the agent.
+            for secret_field in ("jwt_secret", "smtp_pass"):
+                if result["result"].get(secret_field):
+                    result["result"][secret_field] = "***redacted***"
+        return result
+
+    async def update_service_config(
+        self,
+        service: str,
+        config: Dict[str, Any],
+        *,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        if service not in SERVICE_CONFIG_PATHS:
+            return {
+                "error": f"Unknown service {service!r}; one of "
+                f"{', '.join(SERVICE_CONFIG_PATHS)}"
+            }
+        if not isinstance(config, dict) or not config:
+            return {"error": "config must be a non-empty object of fields to change."}
+        path, method = SERVICE_CONFIG_PATHS[service]
+        return await self._mgmt(
+            method,
+            f"projects/{self._ref(project_ref)}/{path}",
+            json_body=config,
+            expected=_EXPECT_WRITE,
+        )
+
+    # =================================================================
+    # Database — SQL, schema introspection, types, backups
+    # =================================================================
+
+    async def run_sql_readonly(
+        self,
+        query: str,
+        *,
+        parameters: Optional[List[Any]] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        body = _clean({"query": query, "parameters": parameters or None})
+        return await self._mgmt(
+            "POST",
+            f"projects/{self._ref(project_ref)}/database/query/read-only",
+            json_body=body,
+            expected=_EXPECT_WRITE,
+            timeout=120.0,
+        )
+
+    async def run_sql(
+        self,
+        query: str,
+        *,
+        parameters: Optional[List[Any]] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        """Run SQL with full privileges.
+
+        Schema changes are recorded, whichever operation the agent picked:
+        a query containing DDL (and no $n parameters, which the migrations
+        endpoint can't take) goes through ``/database/migrations``, which
+        executes it identically AND records it in migration history — so a
+        "create a table" never leaves an untracked change behind.
+        """
+        self._guard_write()
+        migration_name = None if parameters else ddl_migration_name(query)
+        if migration_name:
+            result = await self.apply_migration(
+                query, name=migration_name, project_ref=project_ref
+            )
+            if "error" not in result:
+                result = {
+                    "ok": True,
+                    "result": {
+                        "applied_as_migration": migration_name,
+                        "note": "Schema change recorded in migration history "
+                        "(list_supabase_migrations).",
+                    },
+                }
+            return result
+        body = _clean({"query": query, "parameters": parameters or None})
+        return await self._mgmt(
+            "POST",
+            f"projects/{self._ref(project_ref)}/database/query",
+            json_body=body,
+            expected=_EXPECT_WRITE,
+            timeout=120.0,
+        )
+
+    async def list_tables(
+        self, *, schemas: Optional[List[str]] = None, project_ref: Optional[str] = None
+    ) -> Result:
+        sql = (
+            "select n.nspname as schema, c.relname as name, "
+            "case c.relkind when 'r' then 'table' when 'p' then 'partitioned table' "
+            "when 'v' then 'view' when 'm' then 'materialized view' "
+            "when 'f' then 'foreign table' end as kind, "
+            "c.relrowsecurity as rls_enabled, "
+            "greatest(c.reltuples, 0)::bigint as estimated_rows, "
+            "obj_description(c.oid, 'pg_class') as comment "
+            "from pg_class c join pg_namespace n on n.oid = c.relnamespace "
+            "where c.relkind in ('r','p','v','m','f') "
+            "and n.nspname = any(string_to_array($1, ',')) "
+            "order by 1, 2"
+        )
+        return await self.run_sql_readonly(
+            sql,
+            parameters=[",".join(schemas or ["public"])],
+            project_ref=project_ref,
+        )
+
+    async def describe_table(
+        self, table: str, *, schema: str = "public", project_ref: Optional[str] = None
+    ) -> Result:
+        sql = (
+            "with t as (select c.oid from pg_class c join pg_namespace n "
+            "on n.oid = c.relnamespace where n.nspname = $1 and c.relname = $2) "
+            "select "
+            "(select json_agg(json_build_object('name', column_name, 'type', "
+            "data_type, 'udt', udt_name, 'nullable', is_nullable = 'YES', "
+            "'default', column_default, 'identity', is_identity = 'YES') "
+            "order by ordinal_position) from information_schema.columns "
+            "where table_schema = $1 and table_name = $2) as columns, "
+            "(select json_agg(json_build_object('name', conname, 'type', contype, "
+            "'definition', pg_get_constraintdef(oid))) from pg_constraint "
+            "where conrelid = (select oid from t)) as constraints, "
+            "(select json_agg(json_build_object('name', indexname, 'definition', "
+            "indexdef)) from pg_indexes where schemaname = $1 and tablename = $2) "
+            "as indexes, "
+            "(select json_agg(json_build_object('name', policyname, 'command', cmd, "
+            "'roles', roles, 'using', qual, 'with_check', with_check)) "
+            "from pg_policies where schemaname = $1 and tablename = $2) as policies, "
+            "(select relrowsecurity from pg_class where oid = (select oid from t)) "
+            "as rls_enabled, "
+            "(select json_agg(json_build_object('name', tgname, 'definition', "
+            "pg_get_triggerdef(oid))) from pg_trigger where tgrelid = "
+            "(select oid from t) and not tgisinternal) as triggers"
+        )
+        result = await self.run_sql_readonly(
+            sql, parameters=[schema, table], project_ref=project_ref
+        )
+        if "error" in result:
+            return result
+        rows = result.get("result") or []
+        row = rows[0] if rows else {}
+        if not row or row.get("columns") is None:
+            return {"error": f"Table {schema}.{table} not found."}
+        return {"ok": True, "result": {"schema": schema, "table": table, **row}}
+
+    async def list_extensions(self, *, project_ref: Optional[str] = None) -> Result:
+        sql = (
+            "select name, default_version, installed_version, comment "
+            "from pg_available_extensions "
+            "order by installed_version is null, name"
+        )
+        return await self.run_sql_readonly(sql, project_ref=project_ref)
+
+    async def generate_typescript_types(
+        self, *, schemas: Optional[List[str]] = None, project_ref: Optional[str] = None
+    ) -> Result:
+        return await self._mgmt(
+            "GET",
+            f"projects/{self._ref(project_ref)}/types/typescript",
+            params={"included_schemas": ",".join(schemas or ["public"])},
+            timeout=60.0,
+        )
+
+    async def list_backups(self, *, project_ref: Optional[str] = None) -> Result:
+        return await self._mgmt(
+            "GET", f"projects/{self._ref(project_ref)}/database/backups"
+        )
+
+    # =================================================================
+    # Migrations
+    # =================================================================
+
+    async def list_migrations(self, *, project_ref: Optional[str] = None) -> Result:
+        return await self._mgmt(
+            "GET", f"projects/{self._ref(project_ref)}/database/migrations"
+        )
+
+    async def get_migration(
+        self, version: str, *, project_ref: Optional[str] = None
+    ) -> Result:
+        return await self._mgmt(
+            "GET", f"projects/{self._ref(project_ref)}/database/migrations/{version}"
+        )
+
+    async def apply_migration(
+        self,
+        query: str,
+        *,
+        name: Optional[str] = None,
+        rollback: Optional[str] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        return await self._mgmt(
+            "POST",
+            f"projects/{self._ref(project_ref)}/database/migrations",
+            json_body=_clean({"query": query, "name": name, "rollback": rollback}),
+            expected=_EXPECT_WRITE,
+            timeout=120.0,
+        )
+
+    async def rollback_migrations(
+        self, from_version: str, *, project_ref: Optional[str] = None
+    ) -> Result:
+        """Run the stored rollback SQL of every migration >= from_version and
+        remove them from history."""
+        self._guard_write()
+        return await self._mgmt(
+            "DELETE",
+            f"projects/{self._ref(project_ref)}/database/migrations",
+            params={"gte": from_version},
+            expected=_EXPECT_WRITE,
+            timeout=120.0,
+        )
+
+    # =================================================================
+    # Rows (PostgREST)
+    # =================================================================
+
+    @staticmethod
+    def _filter_params(filters: Optional[Dict[str, Any]]) -> List[Tuple[str, str]]:
+        """``{"age": "gte.18", "status": ["neq.banned", "not.is.null"]}`` →
+        repeated PostgREST query params. Values use PostgREST's own
+        ``<operator>.<value>`` syntax; ``or``/``and`` keys pass through."""
+        params: List[Tuple[str, str]] = []
+        for column, condition in (filters or {}).items():
+            values = condition if isinstance(condition, list) else [condition]
+            for value in values:
+                params.append((str(column), str(value)))
+        return params
+
+    @staticmethod
+    def _profile_headers(schema: Optional[str], *, write: bool) -> Dict[str, str]:
+        if not schema or schema == "public":
+            return {}
+        return {"Content-Profile" if write else "Accept-Profile": schema}
+
+    async def select_rows(
+        self,
+        table: str,
+        *,
+        columns: str = "*",
+        filters: Optional[Dict[str, Any]] = None,
+        order: Optional[str] = None,
+        limit: int = 30,
+        offset: int = 0,
+        schema: str = "public",
+        count: bool = False,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        ref = self._ref(project_ref)
+        params = [("select", columns or "*")] + self._filter_params(filters)
+        if order:
+            params.append(("order", order))
+        params.append(("limit", str(_clamp(limit, 1, self._max_rows(), 30))))
+        params.append(("offset", str(max(int(offset or 0), 0))))
+        headers = self._profile_headers(schema, write=False)
+        if count:
+            headers["Prefer"] = "count=exact"
+        result, response = await self._rest(
+            ref, "GET", f"rest/v1/{quote(table, safe='')}",
+            params=params, headers=headers, expected=(200, 206),
+        )
+        if "error" in result:
+            return result
+        rows = result.get("result") or []
+        payload: Dict[str, Any] = {"rows": rows, "returned": len(rows)}
+        if response is not None:
+            content_range = response.headers.get("content-range", "")
+            total = content_range.rpartition("/")[2]
+            if total and total != "*":
+                payload["total"] = int(total)
+        payload["next_offset"] = (
+            max(int(offset or 0), 0) + len(rows)
+            if len(rows) >= _clamp(limit, 1, self._max_rows(), 30)
+            else None
+        )
+        return {"ok": True, "result": payload}
+
+    async def insert_rows(
+        self,
+        table: str,
+        rows: Any,
+        *,
+        upsert: bool = False,
+        on_conflict: Optional[str] = None,
+        schema: str = "public",
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        ref = self._ref(project_ref)
+        if isinstance(rows, dict):
+            rows = [rows]
+        if not isinstance(rows, list) or not rows:
+            return {"error": "rows must be an object or a non-empty list of objects."}
+        prefer = ["return=representation"]
+        if upsert:
+            prefer.append("resolution=merge-duplicates")
+        headers = self._profile_headers(schema, write=True)
+        headers["Prefer"] = ",".join(prefer)
+        params = [("on_conflict", on_conflict)] if on_conflict else None
+        result, _ = await self._rest(
+            ref, "POST", f"rest/v1/{quote(table, safe='')}",
+            params=params, json_body=rows, headers=headers,
+        )
+        return result
+
+    async def update_rows(
+        self,
+        table: str,
+        values: Dict[str, Any],
+        filters: Dict[str, Any],
+        *,
+        schema: str = "public",
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        if not filters:
+            return {
+                "error": "filters are required — refusing to update every row. "
+                "Use run_supabase_sql for an intentional full-table update."
+            }
+        if not isinstance(values, dict) or not values:
+            return {"error": "values must be a non-empty object of columns to set."}
+        headers = self._profile_headers(schema, write=True)
+        headers["Prefer"] = "return=representation"
+        result, _ = await self._rest(
+            self._ref(project_ref), "PATCH", f"rest/v1/{quote(table, safe='')}",
+            params=self._filter_params(filters), json_body=values, headers=headers,
+        )
+        return result
+
+    async def delete_rows(
+        self,
+        table: str,
+        filters: Dict[str, Any],
+        *,
+        schema: str = "public",
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        if not filters:
+            return {
+                "error": "filters are required — refusing to delete every row. "
+                "Use run_supabase_sql for an intentional truncate."
+            }
+        headers = self._profile_headers(schema, write=True)
+        headers["Prefer"] = "return=representation"
+        result, _ = await self._rest(
+            self._ref(project_ref), "DELETE", f"rest/v1/{quote(table, safe='')}",
+            params=self._filter_params(filters), headers=headers,
+        )
+        return result
+
+    async def call_rpc(
+        self,
+        function: str,
+        *,
+        args: Optional[Dict[str, Any]] = None,
+        schema: str = "public",
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        # A database function can do anything, so treat it as a write.
+        self._guard_write()
+        result, _ = await self._rest(
+            self._ref(project_ref), "POST", f"rest/v1/rpc/{quote(function, safe='')}",
+            json_body=args or {}, headers=self._profile_headers(schema, write=True),
+        )
+        return result
+
+    # =================================================================
+    # Storage
+    # =================================================================
+
+    async def list_buckets(self, *, project_ref: Optional[str] = None) -> Result:
+        result, _ = await self._data(
+            self._ref(project_ref), "GET", "storage/v1/bucket", expected=_EXPECT_READ
+        )
+        return result
+
+    async def create_bucket(
+        self,
+        name: str,
+        *,
+        public: bool = False,
+        file_size_limit: Optional[int] = None,
+        allowed_mime_types: Optional[List[str]] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        body = _clean(
+            {
+                "id": name,
+                "name": name,
+                "public": bool(public),
+                "file_size_limit": file_size_limit,
+                "allowed_mime_types": allowed_mime_types,
+            }
+        )
+        result, _ = await self._data(
+            self._ref(project_ref), "POST", "storage/v1/bucket", json_body=body
+        )
+        return result
+
+    async def update_bucket(
+        self,
+        name: str,
+        *,
+        public: Optional[bool] = None,
+        file_size_limit: Optional[int] = None,
+        allowed_mime_types: Optional[List[str]] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        ref = self._ref(project_ref)
+        # PUT replaces the bucket's settings — read first so unspecified
+        # fields keep their current values.
+        current, _ = await self._data(
+            ref, "GET", f"storage/v1/bucket/{quote(name, safe='')}", expected=_EXPECT_READ
+        )
+        if "error" in current:
+            return current
+        existing = current.get("result") or {}
+        body = {
+            "id": name,
+            "name": name,
+            "public": existing.get("public", False) if public is None else bool(public),
+            "file_size_limit": (
+                existing.get("file_size_limit")
+                if file_size_limit is None
+                else file_size_limit
+            ),
+            "allowed_mime_types": (
+                existing.get("allowed_mime_types")
+                if allowed_mime_types is None
+                else allowed_mime_types
+            ),
+        }
+        result, _ = await self._data(
+            ref, "PUT", f"storage/v1/bucket/{quote(name, safe='')}", json_body=body
+        )
+        return result
+
+    async def delete_bucket(self, name: str, *, project_ref: Optional[str] = None) -> Result:
+        self._guard_write()
+        result, _ = await self._data(
+            self._ref(project_ref), "DELETE", f"storage/v1/bucket/{quote(name, safe='')}"
+        )
+        return result
+
+    async def empty_bucket(self, name: str, *, project_ref: Optional[str] = None) -> Result:
+        self._guard_write()
+        result, _ = await self._data(
+            self._ref(project_ref), "POST",
+            f"storage/v1/bucket/{quote(name, safe='')}/empty",
+        )
+        return result
+
+    async def list_files(
+        self,
+        bucket: str,
+        *,
+        prefix: str = "",
+        search: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        body = _clean(
+            {
+                "prefix": prefix.strip("/"),
+                "limit": _clamp(limit, 1, 1000, 100),
+                "offset": max(int(offset or 0), 0),
+                "search": search,
+                "sortBy": {"column": "name", "order": "asc"},
+            }
+        )
+        result, _ = await self._data(
+            self._ref(project_ref), "POST",
+            f"storage/v1/object/list/{quote(bucket, safe='')}",
+            json_body=body, expected=_EXPECT_READ,
+        )
+        if "error" in result:
+            return result
+        entries = result.get("result") or []
+        # Folders come back as entries with a null id.
+        for entry in entries:
+            if isinstance(entry, dict):
+                entry["is_folder"] = entry.get("id") is None
+        return {"ok": True, "result": entries}
+
+    async def upload_file(
+        self,
+        bucket: str,
+        path: str,
+        file_path: str,
+        *,
+        upsert: bool = False,
+        content_type: Optional[str] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        local = os.path.abspath(file_path)
+        if not os.path.isfile(local):
+            return {"error": f"File not found: {local}"}
+        mime = content_type or mimetypes.guess_type(local)[0] or "application/octet-stream"
+        with open(local, "rb") as f:
+            payload = f.read()
+        headers = {"Content-Type": mime, "x-upsert": "true" if upsert else "false"}
+        result, _ = await self._data(
+            self._ref(project_ref), "POST",
+            f"storage/v1/object/{quote(bucket, safe='')}/{_object_path(path)}",
+            content=payload, headers=headers, timeout=300.0,
+        )
+        if "error" not in result:
+            result["result"] = {
+                "bucket": bucket,
+                "path": path.strip("/"),
+                "size": len(payload),
+                "content_type": mime,
+                **(result.get("result") if isinstance(result.get("result"), dict) else {}),
+            }
+        return result
+
+    async def download_file(
+        self,
+        bucket: str,
+        path: str,
+        save_to: str,
+        *,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        result, response = await self._data(
+            self._ref(project_ref), "GET",
+            f"storage/v1/object/{quote(bucket, safe='')}/{_object_path(path)}",
+            expected=_EXPECT_READ, timeout=300.0, raw=True,
+        )
+        if "error" in result or response is None:
+            return result
+        target = os.path.abspath(save_to)
+        parent = os.path.dirname(target)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(target, "wb") as f:
+            f.write(response.content)
+        return {
+            "ok": True,
+            "result": {
+                "saved_to": target,
+                "size": len(response.content),
+                "content_type": response.headers.get("content-type"),
+            },
+        }
+
+    async def delete_files(
+        self, bucket: str, paths: List[str], *, project_ref: Optional[str] = None
+    ) -> Result:
+        self._guard_write()
+        if isinstance(paths, str):
+            paths = [paths]
+        if not paths:
+            return {"error": "paths must list at least one object path."}
+        result, _ = await self._data(
+            self._ref(project_ref), "DELETE",
+            f"storage/v1/object/{quote(bucket, safe='')}",
+            json_body={"prefixes": [p.strip("/") for p in paths]},
+        )
+        return result
+
+    async def move_file(
+        self,
+        bucket: str,
+        from_path: str,
+        to_path: str,
+        *,
+        to_bucket: Optional[str] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        body = _clean(
+            {
+                "bucketId": bucket,
+                "sourceKey": from_path.strip("/"),
+                "destinationKey": to_path.strip("/"),
+                "destinationBucket": to_bucket,
+            }
+        )
+        result, _ = await self._data(
+            self._ref(project_ref), "POST", "storage/v1/object/move", json_body=body
+        )
+        return result
+
+    async def copy_file(
+        self,
+        bucket: str,
+        from_path: str,
+        to_path: str,
+        *,
+        to_bucket: Optional[str] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        body = _clean(
+            {
+                "bucketId": bucket,
+                "sourceKey": from_path.strip("/"),
+                "destinationKey": to_path.strip("/"),
+                "destinationBucket": to_bucket,
+            }
+        )
+        result, _ = await self._data(
+            self._ref(project_ref), "POST", "storage/v1/object/copy", json_body=body
+        )
+        return result
+
+    async def create_signed_url(
+        self,
+        bucket: str,
+        path: str,
+        *,
+        expires_in: int = 3600,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        ref = self._ref(project_ref)
+        result, _ = await self._data(
+            ref, "POST",
+            f"storage/v1/object/sign/{quote(bucket, safe='')}/{_object_path(path)}",
+            json_body={"expiresIn": _clamp(expires_in, 1, 60 * 60 * 24 * 365, 3600)},
+        )
+        if "error" in result:
+            return result
+        signed = (result.get("result") or {}).get("signedURL") or ""
+        return {
+            "ok": True,
+            "result": {
+                "signed_url": f"{self._project_url(ref)}/storage/v1{signed}"
+                if signed.startswith("/")
+                else signed,
+                "expires_in": _clamp(expires_in, 1, 60 * 60 * 24 * 365, 3600),
+                "public_url_if_bucket_public": f"{self._project_url(ref)}/storage/v1/"
+                f"object/public/{quote(bucket, safe='')}/{_object_path(path)}",
+            },
+        }
+
+    # =================================================================
+    # Auth users (GoTrue admin)
+    # =================================================================
+
+    async def list_users(
+        self, *, page: int = 1, per_page: int = 50, project_ref: Optional[str] = None
+    ) -> Result:
+        per = _clamp(per_page, 1, 1000, 50)
+        result, _ = await self._data(
+            self._ref(project_ref), "GET", "auth/v1/admin/users",
+            params={"page": max(int(page or 1), 1), "per_page": per},
+            expected=_EXPECT_READ,
+        )
+        if "error" in result:
+            return result
+        users = (result.get("result") or {}).get("users") or []
+        return {
+            "ok": True,
+            "result": {
+                "users": users,
+                "page": max(int(page or 1), 1),
+                "next_page": max(int(page or 1), 1) + 1 if len(users) >= per else None,
+            },
+        }
+
+    async def get_user(self, user_id: str, *, project_ref: Optional[str] = None) -> Result:
+        result, _ = await self._data(
+            self._ref(project_ref), "GET", f"auth/v1/admin/users/{quote(user_id, safe='')}",
+            expected=_EXPECT_READ,
+        )
+        return result
+
+    async def create_user(
+        self,
+        *,
+        email: Optional[str] = None,
+        phone: Optional[str] = None,
+        password: Optional[str] = None,
+        email_confirm: Optional[bool] = None,
+        phone_confirm: Optional[bool] = None,
+        user_metadata: Optional[Dict[str, Any]] = None,
+        app_metadata: Optional[Dict[str, Any]] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        if not email and not phone:
+            return {"error": "email or phone is required."}
+        body = _clean(
+            {
+                "email": email,
+                "phone": phone,
+                "password": password,
+                "email_confirm": email_confirm,
+                "phone_confirm": phone_confirm,
+                "user_metadata": user_metadata,
+                "app_metadata": app_metadata,
+            }
+        )
+        result, _ = await self._data(
+            self._ref(project_ref), "POST", "auth/v1/admin/users", json_body=body
+        )
+        return result
+
+    async def update_user(
+        self,
+        user_id: str,
+        *,
+        email: Optional[str] = None,
+        phone: Optional[str] = None,
+        password: Optional[str] = None,
+        email_confirm: Optional[bool] = None,
+        phone_confirm: Optional[bool] = None,
+        user_metadata: Optional[Dict[str, Any]] = None,
+        app_metadata: Optional[Dict[str, Any]] = None,
+        ban_duration: Optional[str] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        body = _clean(
+            {
+                "email": email,
+                "phone": phone,
+                "password": password,
+                "email_confirm": email_confirm,
+                "phone_confirm": phone_confirm,
+                "user_metadata": user_metadata,
+                "app_metadata": app_metadata,
+                "ban_duration": ban_duration,
+            }
+        )
+        if not body:
+            return {"error": "Nothing to update — pass at least one field."}
+        result, _ = await self._data(
+            self._ref(project_ref), "PUT",
+            f"auth/v1/admin/users/{quote(user_id, safe='')}", json_body=body,
+        )
+        return result
+
+    async def delete_user(
+        self,
+        user_id: str,
+        *,
+        soft_delete: bool = False,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        result, _ = await self._data(
+            self._ref(project_ref), "DELETE",
+            f"auth/v1/admin/users/{quote(user_id, safe='')}",
+            json_body={"should_soft_delete": bool(soft_delete)},
+        )
+        return result
+
+    async def invite_user(
+        self,
+        email: str,
+        *,
+        redirect_to: Optional[str] = None,
+        data: Optional[Dict[str, Any]] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        params = {"redirect_to": redirect_to} if redirect_to else None
+        result, _ = await self._data(
+            self._ref(project_ref), "POST", "auth/v1/invite",
+            params=params, json_body=_clean({"email": email, "data": data}),
+        )
+        return result
+
+    async def generate_auth_link(
+        self,
+        link_type: str,
+        email: str,
+        *,
+        password: Optional[str] = None,
+        new_email: Optional[str] = None,
+        redirect_to: Optional[str] = None,
+        data: Optional[Dict[str, Any]] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        """Generate a signup / magiclink / recovery / invite / email-change
+        link without sending an email."""
+        self._guard_write()
+        valid = ("signup", "magiclink", "recovery", "invite", "email_change_current",
+                 "email_change_new")
+        if link_type not in valid:
+            return {"error": f"link_type must be one of {', '.join(valid)}"}
+        params = {"redirect_to": redirect_to} if redirect_to else None
+        body = _clean(
+            {
+                "type": link_type,
+                "email": email,
+                "password": password,
+                "new_email": new_email,
+                "data": data,
+            }
+        )
+        result, _ = await self._data(
+            self._ref(project_ref), "POST", "auth/v1/admin/generate_link",
+            params=params, json_body=body,
+        )
+        return result
+
+    # =================================================================
+    # Edge functions
+    # =================================================================
+
+    async def list_functions(self, *, project_ref: Optional[str] = None) -> Result:
+        return await self._mgmt("GET", f"projects/{self._ref(project_ref)}/functions")
+
+    async def get_function(self, slug: str, *, project_ref: Optional[str] = None) -> Result:
+        return await self._mgmt(
+            "GET", f"projects/{self._ref(project_ref)}/functions/{quote(slug, safe='')}"
+        )
+
+    async def deploy_function(
+        self,
+        slug: str,
+        *,
+        files: Optional[Dict[str, str]] = None,
+        source_dir: Optional[str] = None,
+        entrypoint: str = "index.ts",
+        name: Optional[str] = None,
+        verify_jwt: bool = True,
+        import_map_path: Optional[str] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        """Create or replace an edge function from source.
+
+        Source comes from ``files`` (``{relative_path: source_text}``) or
+        from every file under ``source_dir`` on disk. Paths are relative to
+        the function root and must include the entrypoint.
+        """
+        self._guard_write()
+        sources: List[Tuple[str, bytes]] = []
+        if files:
+            sources = [(p.replace("\\", "/").lstrip("/"), c.encode("utf-8"))
+                       for p, c in files.items()]
+        elif source_dir:
+            root = os.path.abspath(source_dir)
+            if not os.path.isdir(root):
+                return {"error": f"source_dir not found: {root}"}
+            for folder, _, names in os.walk(root):
+                for fname in names:
+                    full = os.path.join(folder, fname)
+                    rel = os.path.relpath(full, root).replace("\\", "/")
+                    with open(full, "rb") as f:
+                        sources.append((rel, f.read()))
+        else:
+            return {"error": "Pass either 'files' (path → source) or 'source_dir'."}
+        if entrypoint not in {p for p, _ in sources}:
+            return {
+                "error": f"Entrypoint {entrypoint!r} is not among the files: "
+                f"{sorted(p for p, _ in sources)[:20]}"
+            }
+        metadata = _clean(
+            {
+                "entrypoint_path": entrypoint,
+                "name": name or slug,
+                "verify_jwt": bool(verify_jwt),
+                "import_map_path": import_map_path,
+            }
+        )
+        multipart = [
+            ("file", (path, content, mimetypes.guess_type(path)[0] or "text/plain"))
+            for path, content in sources
+        ]
+        return await self._mgmt(
+            "POST",
+            f"projects/{self._ref(project_ref)}/functions/deploy",
+            params={"slug": slug},
+            data={"metadata": json.dumps(metadata)},
+            files=multipart,
+            expected=_EXPECT_WRITE,
+            timeout=180.0,
+        )
+
+    async def update_function(
+        self,
+        slug: str,
+        *,
+        name: Optional[str] = None,
+        verify_jwt: Optional[bool] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        body = _clean({"name": name, "verify_jwt": verify_jwt})
+        if not body:
+            return {"error": "Nothing to update — pass name and/or verify_jwt. "
+                    "To change code, use deploy_supabase_function."}
+        return await self._mgmt(
+            "PATCH",
+            f"projects/{self._ref(project_ref)}/functions/{quote(slug, safe='')}",
+            json_body=body,
+            expected=_EXPECT_WRITE,
+        )
+
+    async def delete_function(self, slug: str, *, project_ref: Optional[str] = None) -> Result:
+        self._guard_write()
+        return await self._mgmt(
+            "DELETE",
+            f"projects/{self._ref(project_ref)}/functions/{quote(slug, safe='')}",
+            expected=_EXPECT_WRITE,
+        )
+
+    async def invoke_function(
+        self,
+        slug: str,
+        *,
+        body: Any = None,
+        method: str = "POST",
+        headers: Optional[Dict[str, str]] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        # Invocation can have arbitrary side effects inside the function.
+        self._guard_write()
+        verb = (method or "POST").upper()
+        if verb not in ("GET", "POST", "PUT", "PATCH", "DELETE"):
+            return {"error": f"Unsupported method {method!r}."}
+        extra = {k: v for k, v in (headers or {}).items()
+                 if k.lower() not in ("apikey", "authorization")}
+        # Functions with verify_jwt need a JWT; only legacy keys are JWTs.
+        result, response = await self._data(
+            self._ref(project_ref), verb, f"functions/v1/{quote(slug, safe='')}",
+            json_body=body if verb != "GET" else None,
+            headers=extra, prefer_jwt=True, expected=range(200, 300),
+            timeout=150.0, raw=True,
+        )
+        if response is None:
+            return result
+        try:
+            parsed: Any = response.json()
+        except Exception:
+            parsed = response.text[:20000]
+        envelope = {
+            "status_code": response.status_code,
+            "content_type": response.headers.get("content-type"),
+            "body": parsed,
+        }
+        if "error" in result:
+            return {"error": result["error"], "details": envelope}
+        return {"ok": True, "result": envelope}
+
+    # =================================================================
+    # Secrets (edge-function environment variables)
+    # =================================================================
+
+    async def list_secrets(self, *, project_ref: Optional[str] = None) -> Result:
+        """Names and update times only — values are stripped before they
+        reach the agent."""
+        result = await self._mgmt("GET", f"projects/{self._ref(project_ref)}/secrets")
+        if "error" in result:
+            return result
+        return {
+            "ok": True,
+            "result": [
+                {"name": s.get("name"), "updated_at": s.get("updated_at")}
+                for s in result.get("result") or []
+                if isinstance(s, dict)
+            ],
+        }
+
+    async def set_secrets(
+        self, secrets: Dict[str, str], *, project_ref: Optional[str] = None
+    ) -> Result:
+        self._guard_write()
+        if not isinstance(secrets, dict) or not secrets:
+            return {"error": "secrets must be a non-empty object of NAME → value."}
+        bad = [n for n in secrets if str(n).upper().startswith("SUPABASE_")]
+        if bad:
+            return {"error": f"Names starting with SUPABASE_ are reserved: {bad}"}
+        result = await self._mgmt(
+            "POST",
+            f"projects/{self._ref(project_ref)}/secrets",
+            json_body=[{"name": n, "value": str(v)} for n, v in secrets.items()],
+            expected=_EXPECT_WRITE,
+        )
+        if "error" not in result:
+            result["result"] = {"set": sorted(secrets)}
+        return result
+
+    async def delete_secrets(
+        self, names: List[str], *, project_ref: Optional[str] = None
+    ) -> Result:
+        self._guard_write()
+        if isinstance(names, str):
+            names = [names]
+        if not names:
+            return {"error": "names must list at least one secret name."}
+        result = await self._mgmt(
+            "DELETE",
+            f"projects/{self._ref(project_ref)}/secrets",
+            json_body=list(names),
+            expected=_EXPECT_WRITE,
+        )
+        if "error" not in result:
+            result["result"] = {"deleted": sorted(names)}
+        return result
+
+    # =================================================================
+    # Branches
+    # =================================================================
+
+    async def list_branches(self, *, project_ref: Optional[str] = None) -> Result:
+        return await self._mgmt("GET", f"projects/{self._ref(project_ref)}/branches")
+
+    async def get_branch(self, branch_id: str) -> Result:
+        return await self._mgmt("GET", f"branches/{quote(branch_id, safe='')}")
+
+    async def create_branch(
+        self,
+        branch_name: str,
+        *,
+        git_branch: Optional[str] = None,
+        persistent: Optional[bool] = None,
+        with_data: Optional[bool] = None,
+        region: Optional[str] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        self._guard_write()
+        body = _clean(
+            {
+                "branch_name": branch_name,
+                "git_branch": git_branch,
+                "persistent": persistent,
+                "with_data": with_data,
+                "region": region,
+            }
+        )
+        return await self._mgmt(
+            "POST",
+            f"projects/{self._ref(project_ref)}/branches",
+            json_body=body,
+            expected=_EXPECT_WRITE,
+            timeout=60.0,
+        )
+
+    async def update_branch(
+        self,
+        branch_id: str,
+        *,
+        branch_name: Optional[str] = None,
+        git_branch: Optional[str] = None,
+        persistent: Optional[bool] = None,
+    ) -> Result:
+        self._guard_write()
+        body = _clean(
+            {"branch_name": branch_name, "git_branch": git_branch, "persistent": persistent}
+        )
+        if not body:
+            return {"error": "Nothing to update — pass branch_name, git_branch or persistent."}
+        return await self._mgmt(
+            "PATCH", f"branches/{quote(branch_id, safe='')}",
+            json_body=body, expected=_EXPECT_WRITE,
+        )
+
+    async def delete_branch(self, branch_id: str) -> Result:
+        self._guard_write()
+        return await self._mgmt(
+            "DELETE", f"branches/{quote(branch_id, safe='')}", expected=_EXPECT_WRITE
+        )
+
+    async def merge_branch(
+        self, branch_id: str, *, migration_version: Optional[str] = None
+    ) -> Result:
+        self._guard_write()
+        return await self._mgmt(
+            "POST", f"branches/{quote(branch_id, safe='')}/merge",
+            json_body=_clean({"migration_version": migration_version}),
+            expected=_EXPECT_WRITE, timeout=60.0,
+        )
+
+    async def reset_branch(
+        self, branch_id: str, *, migration_version: Optional[str] = None
+    ) -> Result:
+        self._guard_write()
+        return await self._mgmt(
+            "POST", f"branches/{quote(branch_id, safe='')}/reset",
+            json_body=_clean({"migration_version": migration_version}),
+            expected=_EXPECT_WRITE, timeout=60.0,
+        )
+
+    async def diff_branch(
+        self, branch_id: str, *, schemas: Optional[List[str]] = None
+    ) -> Result:
+        params = {"included_schemas": ",".join(schemas)} if schemas else {}
+        return await self._mgmt_text(f"branches/{quote(branch_id, safe='')}/diff", params)
+
+    # =================================================================
+    # Monitoring — logs, advisors, usage
+    # =================================================================
+
+    async def get_logs(
+        self,
+        *,
+        source: str = "api",
+        sql: Optional[str] = None,
+        minutes: int = 60,
+        limit: int = 100,
+        search: Optional[str] = None,
+        project_ref: Optional[str] = None,
+    ) -> Result:
+        """Recent logs for one service.
+
+        Since Supabase retired ``logs.all`` the endpoint takes ClickHouse
+        SQL over ONE ``logs`` table, filtered by ``source_name`` (the old
+        per-source table names). Nested fields live in the
+        ``log_attributes`` map, e.g. ``log_attributes['request.method']``.
+        """
+        source_name = LOG_SOURCES.get(source)
+        if not sql and not source_name:
+            return {"error": f"source must be one of {', '.join(LOG_SOURCES)}"}
+        if not sql:
+            where = f"source_name = {_ch_literal(source_name)}"
+            if search:
+                # re2 regex, case-insensitive unless the caller set flags.
+                pattern = search if search.startswith("(?") else f"(?i){search}"
+                where += f" and match(event_message, {_ch_literal(pattern)})"
+            sql = (
+                f"select timestamp, event_message from logs where {where} "
+                f"order by timestamp desc limit {_clamp(limit, 1, 1000, 100)}"
+            )
+        span = _clamp(minutes, 1, 60 * 24, 60)
+        end = time.time()
+        start = end - span * 60
+
+        def _iso(ts: float) -> str:
+            return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(ts))
+
+        params = {
+            "sql": sql,
+            "iso_timestamp_start": _iso(start),
+            "iso_timestamp_end": _iso(end),
+        }
+        path = f"projects/{self._ref(project_ref)}/analytics/endpoints/logs"
+        result = _analytics_result(await self._mgmt("GET", path, params=params, timeout=60.0))
+        # Supabase asks for a retry on transient backend failures.
+        if "Backend error" in str(result.get("details") or ""):
+            await asyncio.sleep(2.0)
+            result = _analytics_result(
+                await self._mgmt("GET", path, params=params, timeout=60.0)
+            )
+            if "Backend error" in str(result.get("details") or ""):
+                result["details"] = (
+                    "Supabase's logs service is failing for this project (it "
+                    "rejects even trivial queries, so this isn't the query). "
+                    "Try again later, or check Logs Explorer in the Supabase "
+                    "dashboard."
+                )
+        return result
+
+    async def get_security_advisors(self, *, project_ref: Optional[str] = None) -> Result:
+        return await self._mgmt(
+            "GET", f"projects/{self._ref(project_ref)}/advisors/security", timeout=60.0
+        )
+
+    async def get_performance_advisors(self, *, project_ref: Optional[str] = None) -> Result:
+        return await self._mgmt(
+            "GET", f"projects/{self._ref(project_ref)}/advisors/performance", timeout=60.0
+        )
+
+    async def get_api_usage(
+        self, *, interval: str = "1day", project_ref: Optional[str] = None
+    ) -> Result:
+        valid = ("15min", "30min", "1hr", "3hr", "1day", "3day", "7day")
+        result = await self._mgmt(
+            "GET",
+            f"projects/{self._ref(project_ref)}/analytics/endpoints/usage.api-counts",
+            params={"interval": interval if interval in valid else "1day"},
+        )
+        return _analytics_result(result)
diff --git a/craftos_integrations/providers/supabase/operations.py b/craftos_integrations/providers/supabase/operations.py
new file mode 100644
index 000000000..d12f2a2dd
--- /dev/null
+++ b/craftos_integrations/providers/supabase/operations.py
@@ -0,0 +1,1344 @@
+"""Supabase operations — the agent-facing surface.
+
+71 operations across ten tag sets. Every op maps to exactly one
+``SupabaseClient`` method via ``client_op``; the client returns the
+package ``{ok, result}`` / ``{error, details}`` envelope, which
+``shape_result`` collapses with no options needed.
+
+Conventions enforced here (see craftos_integrations/README.md):
+- names are verb-first and carry the integration name
+- every project-scoped op takes an optional ``project_ref``; omitted, the
+  client falls back to the configured default project
+- mutations set ``parallelizable=False``; anything that deletes, wipes,
+  or takes a service offline also sets ``destructive=True``
+- ``account`` is never declared — the host injects it
+
+The intentionally-excluded surface is listed at the bottom of this file.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from ...contracts import Operation
+from .._shared import client_op
+
+_UMBRELLA = "supabase"
+_PROJECTS = "supabase_projects"
+_DATABASE = "supabase_database"
+_MIGRATIONS = "supabase_migrations"
+_ROWS = "supabase_rows"
+_STORAGE = "supabase_storage"
+_AUTH = "supabase_auth"
+_FUNCTIONS = "supabase_functions"
+_SECRETS = "supabase_secrets"
+_BRANCHES = "supabase_branches"
+_MONITORING = "supabase_monitoring"
+
+
+# ────────────────────────────────────────────────────────────────────────
+# Schema-fragment builders (fresh dicts per call — never share instances)
+# ────────────────────────────────────────────────────────────────────────
+
+
+def _s(description: str, example: str = "") -> Dict[str, Any]:
+    return {"type": "string", "description": description, "example": example}
+
+
+def _i(description: str, example: int) -> Dict[str, Any]:
+    return {"type": "integer", "description": description, "example": example}
+
+
+def _b(description: str, example: bool = False) -> Dict[str, Any]:
+    return {"type": "boolean", "description": description, "example": example}
+
+
+def _arr(description: str, example: List[Any]) -> Dict[str, Any]:
+    return {"type": "array", "description": description, "example": example}
+
+
+def _obj(description: str, example: Dict[str, Any]) -> Dict[str, Any]:
+    return {"type": "object", "description": description, "example": example}
+
+
+def _ref() -> Dict[str, Any]:
+    return _s(
+        "20-character project ref (e.g. from list_supabase_projects). Omit to "
+        "use the default project from the integration config.",
+        "abcdefghijklmnopqrst",
+    )
+
+
+def _schema() -> Dict[str, Any]:
+    return _s("Postgres schema. Default 'public'.", "public")
+
+
+def _table() -> Dict[str, Any]:
+    return _s("Table or view name, without the schema prefix.", "orders")
+
+
+def _filters(example: Dict[str, Any]) -> Dict[str, Any]:
+    return _obj(
+        "Row filters in PostgREST syntax: {column: '<op>.<value>'}. Operators: "
+        "eq, neq, gt, gte, lt, lte, like, ilike, is, in, cs, cd. Examples: "
+        "{'id': 'eq.42'}, {'status': 'in.(open,pending)'}, "
+        "{'deleted_at': 'is.null'}. A list value repeats the column "
+        "(['gte.18', 'lt.65']). Use key 'or' for "
+        "'(status.eq.open,priority.gt.3)'.",
+        example,
+    )
+
+
+def _bucket() -> Dict[str, Any]:
+    return _s("Storage bucket id (its name).", "avatars")
+
+
+def _object_path() -> Dict[str, Any]:
+    return _s(
+        "Object path inside the bucket, '/'-separated, no leading slash.",
+        "users/42/profile.png",
+    )
+
+
+def _branch_id() -> Dict[str, Any]:
+    return _s(
+        "Branch id (UUID) or the branch's own project ref, from "
+        "list_supabase_branches.",
+        "0b4c1f9e-2a7d-4c3e-9f10-5d6e7a8b9c0d",
+    )
+
+
+def build_operations() -> List[Operation]:
+    return [
+        # ═════════════════════════════════════════════════════════════
+        # Projects & organizations — tag: supabase_projects
+        # ═════════════════════════════════════════════════════════════
+        client_op(
+            "list_supabase_projects",
+            "list_projects",
+            description=(
+                "List every Supabase project the connected account can see. "
+                "Returns ref (the project identifier every other operation "
+                "takes), name, organization_slug, region and status."
+            ),
+            input_schema={
+                "organization_slug": _s(
+                    "Only projects in this organization.", ""
+                ),
+            },
+            tags=(_PROJECTS, _UMBRELLA),
+        ),
+        client_op(
+            "get_supabase_project",
+            "get_project",
+            description=(
+                "Get one project by ref: name, region, status (ACTIVE_HEALTHY, "
+                "INACTIVE = paused, …), database host and Postgres version."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_PROJECTS, _UMBRELLA),
+        ),
+        client_op(
+            "get_supabase_project_keys",
+            "get_project_keys",
+            description=(
+                "Get a project's API URL and publishable (anon) key — the two "
+                "values a frontend or mobile app needs to talk to Supabase. "
+                "Never returns the secret/service_role key."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_PROJECTS, _UMBRELLA),
+        ),
+        client_op(
+            "create_supabase_project",
+            "create_project",
+            description=(
+                "Create a new Supabase project in an organization. May incur "
+                "charges on paid plans — confirm with the user first. Returns "
+                "the new project (ref, status COMING_UP); when db_pass is "
+                "omitted a strong one is generated and returned once as "
+                "generated_db_password."
+            ),
+            input_schema={
+                "name": _s("Project name.", "acme-prod"),
+                "organization_slug": _s(
+                    "Organization slug from list_supabase_organizations.",
+                    "acme-inc",
+                ),
+                "db_pass": _s(
+                    "Database password. Omit to generate a strong one.", ""
+                ),
+                "region": _s(
+                    "Region code (e.g. 'us-east-1', 'eu-central-1') or a "
+                    "smart group ('americas', 'emea', 'apac'). See "
+                    "list_supabase_regions.",
+                    "us-east-1",
+                ),
+                "desired_instance_size": _s(
+                    "Compute size (nano, micro, small, medium, large, …). "
+                    "Omit for the plan default.",
+                    "",
+                ),
+            },
+            parallelizable=False,
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "update_supabase_project",
+            "update_project",
+            description="Rename a Supabase project. Returns its id, ref and new name.",
+            input_schema={
+                "name": _s("New project name.", "acme-production"),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "delete_supabase_project",
+            "delete_project",
+            description=(
+                "Permanently delete a Supabase project and ALL its data, "
+                "storage and functions. Irreversible — confirm the exact ref "
+                "and name with the user first. project_ref is required here "
+                "(no default fallback)."
+            ),
+            input_schema={
+                "project_ref": _s(
+                    "20-character ref of the project to delete. Required.",
+                    "abcdefghijklmnopqrst",
+                ),
+            },
+            destructive=True,
+            parallelizable=False,
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "pause_supabase_project",
+            "pause_project",
+            description=(
+                "Pause a project: its API and database go offline until "
+                "restored. Data is kept. Use restore_supabase_project to "
+                "bring it back."
+            ),
+            input_schema={"project_ref": _ref()},
+            destructive=True,
+            parallelizable=False,
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "restore_supabase_project",
+            "restore_project",
+            description=(
+                "Un-pause a paused project (status INACTIVE). Takes a few "
+                "minutes; poll get_supabase_project until ACTIVE_HEALTHY. "
+                "This is not a backup restore."
+            ),
+            input_schema={"project_ref": _ref()},
+            parallelizable=False,
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "restart_supabase_project",
+            "restart_project",
+            description=(
+                "Restart a project's services (database, API, auth). Causes a "
+                "short outage. Use after config changes that require it."
+            ),
+            input_schema={"project_ref": _ref()},
+            parallelizable=False,
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "get_supabase_project_health",
+            "get_project_health",
+            description=(
+                "Health status of a project's services (auth, db, pooler, "
+                "realtime, rest, storage). Returns one entry per service with "
+                "status ACTIVE_HEALTHY / COMING_UP / UNHEALTHY."
+            ),
+            input_schema={
+                "services": _arr(
+                    "Subset of services to check. Omit for all.", ["db", "rest"]
+                ),
+                "project_ref": _ref(),
+            },
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "list_supabase_regions",
+            "list_regions",
+            description=(
+                "Regions available for a new project in an organization, with "
+                "Supabase's recommendation. Use before create_supabase_project."
+            ),
+            input_schema={
+                "organization_slug": _s("Organization slug.", "acme-inc"),
+                "continent": _s(
+                    "Bias the recommendation: NA, SA, EU, AF, AS, OC.", "EU"
+                ),
+            },
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "list_supabase_organizations",
+            "list_organizations",
+            description=(
+                "List the Supabase organizations the account belongs to. "
+                "Returns slug (the organization identifier) and name."
+            ),
+            input_schema={},
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "list_supabase_organization_members",
+            "list_organization_members",
+            description=(
+                "List members of an organization: user id, name, email, role "
+                "and whether MFA is enabled."
+            ),
+            input_schema={
+                "organization_slug": _s("Organization slug.", "acme-inc"),
+            },
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "get_supabase_service_config",
+            "get_service_config",
+            description=(
+                "Read a project service's configuration. service is one of: "
+                "auth (site URL, redirect URLs, providers, SMTP, signup "
+                "rules), postgrest (exposed schemas, max rows), realtime, "
+                "storage (file size limit, features), postgres (server "
+                "settings). Secrets in the result are redacted."
+            ),
+            input_schema={
+                "service": _s(
+                    "auth | postgrest | realtime | storage | postgres.", "auth"
+                ),
+                "project_ref": _ref(),
+            },
+            tags=(_PROJECTS,),
+        ),
+        client_op(
+            "update_supabase_service_config",
+            "update_service_config",
+            description=(
+                "Change fields of a project service's configuration. Pass only "
+                "the fields to change (read them first with "
+                "get_supabase_service_config). Examples: auth {'site_url': "
+                "'https://app.acme.com', 'disable_signup': true}; postgrest "
+                "{'db_schema': 'public,api'}. Returns the updated config."
+            ),
+            input_schema={
+                "service": _s(
+                    "auth | postgrest | realtime | storage | postgres.", "auth"
+                ),
+                "config": _obj(
+                    "Fields to change, using the names from "
+                    "get_supabase_service_config.",
+                    {"site_url": "https://app.acme.com"},
+                ),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_PROJECTS,),
+        ),
+        # ═════════════════════════════════════════════════════════════
+        # Database — tag: supabase_database
+        # ═════════════════════════════════════════════════════════════
+        client_op(
+            "run_supabase_sql_readonly",
+            "run_sql_readonly",
+            description=(
+                "Run a SQL query as Supabase's read-only database role — any "
+                "write fails, so this is the safe default for SELECTs, "
+                "counts, joins and catalog queries. Returns the result rows "
+                "as a list of objects."
+            ),
+            input_schema={
+                "query": _s(
+                    "SQL to run. Use $1, $2 placeholders with 'parameters' "
+                    "for any user-supplied values.",
+                    "select status, count(*) from public.orders group by 1",
+                ),
+                "parameters": _arr("Values for $1, $2, … placeholders.", []),
+                "project_ref": _ref(),
+            },
+            tags=(_DATABASE, _UMBRELLA),
+        ),
+        client_op(
+            "run_supabase_sql",
+            "run_sql",
+            description=(
+                "Run any SQL with full privileges (postgres role) on the "
+                "user's own tables: INSERT/UPDATE/DELETE, grants, functions, "
+                "policies. Schema changes (CREATE/ALTER/DROP/GRANT…) without "
+                "$n parameters are recorded in migration history "
+                "automatically. Use run_supabase_sql_readonly for reads. "
+                "Never use it on "
+                "storage.*, auth.* or vault.* — buckets, files, auth users "
+                "and edge-function secrets have their own operations (sets "
+                "supabase_storage / supabase_auth / supabase_secrets). "
+                "Returns result rows."
+            ),
+            input_schema={
+                "query": _s(
+                    "SQL to run. Use $1, $2 placeholders with 'parameters'.",
+                    "update public.orders set status = 'shipped' where id = $1",
+                ),
+                "parameters": _arr("Values for $1, $2, … placeholders.", [42]),
+                "project_ref": _ref(),
+            },
+            destructive=True,
+            parallelizable=False,
+            tags=(_DATABASE, _UMBRELLA),
+        ),
+        client_op(
+            "list_supabase_tables",
+            "list_tables",
+            description=(
+                "List tables, views and materialized views in the given "
+                "schemas with RLS status, estimated row count and comment. "
+                "Call this before querying an unfamiliar database."
+            ),
+            input_schema={
+                "schemas": _arr(
+                    "Schemas to list. Default ['public'].", ["public"]
+                ),
+                "project_ref": _ref(),
+            },
+            tags=(_DATABASE, _UMBRELLA),
+        ),
+        client_op(
+            "describe_supabase_table",
+            "describe_table",
+            description=(
+                "Full definition of one table: columns (type, nullable, "
+                "default), constraints (primary/foreign keys, checks), "
+                "indexes, RLS status and policies, and triggers."
+            ),
+            input_schema={
+                "table": _table(),
+                "schema": _schema(),
+                "project_ref": _ref(),
+            },
+            tags=(_DATABASE, _UMBRELLA),
+        ),
+        client_op(
+            "list_supabase_extensions",
+            "list_extensions",
+            description=(
+                "List Postgres extensions available to the project, installed "
+                "ones first, with installed and default versions. Enable one "
+                "with apply_supabase_migration ('create extension …')."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_DATABASE,),
+        ),
+        client_op(
+            "generate_supabase_typescript_types",
+            "generate_typescript_types",
+            description=(
+                "Generate TypeScript type definitions for the database schema "
+                "(the same output as `supabase gen types`). Returns {types: "
+                "<source text>}."
+            ),
+            input_schema={
+                "schemas": _arr("Schemas to include. Default ['public'].", ["public"]),
+                "project_ref": _ref(),
+            },
+            tags=(_DATABASE,),
+        ),
+        client_op(
+            "list_supabase_backups",
+            "list_backups",
+            description=(
+                "List the project's database backups and whether point-in-time "
+                "recovery is enabled. Read-only; restoring is done from the "
+                "Supabase dashboard."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_DATABASE,),
+        ),
+        # ═════════════════════════════════════════════════════════════
+        # Migrations — tag: supabase_migrations
+        # ═════════════════════════════════════════════════════════════
+        client_op(
+            "list_supabase_migrations",
+            "list_migrations",
+            description=(
+                "List migrations applied to the project's database, oldest "
+                "first. Returns version (timestamp string) and name."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_MIGRATIONS, _UMBRELLA),
+        ),
+        client_op(
+            "get_supabase_migration",
+            "get_migration",
+            description=(
+                "Get one applied migration by version: its SQL statements and "
+                "stored rollback statements."
+            ),
+            input_schema={
+                "version": _s("Migration version from list_supabase_migrations.",
+                              "20250312000000"),
+                "project_ref": _ref(),
+            },
+            tags=(_MIGRATIONS,),
+        ),
+        client_op(
+            "apply_supabase_migration",
+            "apply_migration",
+            description=(
+                "Apply a schema change (DDL) as a tracked migration — the "
+                "right way to create/alter tables, add columns, indexes, RLS "
+                "policies, functions or extensions. Recorded in migration "
+                "history. To undo on a production project, apply another "
+                "migration that reverses it; 'rollback' SQL is only used on "
+                "development branches."
+            ),
+            input_schema={
+                "query": _s(
+                    "Migration SQL.",
+                    "create table public.widgets (id bigint generated always "
+                    "as identity primary key, name text not null);",
+                ),
+                "name": _s("snake_case migration name.", "create_widgets_table"),
+                "rollback": _s(
+                    "SQL that undoes this migration.",
+                    "drop table if exists public.widgets;",
+                ),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_MIGRATIONS, _UMBRELLA),
+        ),
+        client_op(
+            "rollback_supabase_migrations",
+            "rollback_migrations",
+            description=(
+                "On a DEVELOPMENT BRANCH only: undo every migration with "
+                "version >= from_version by running their stored rollback SQL "
+                "and remove them from history. Supabase refuses this on a "
+                "production project — there, apply a new migration that "
+                "reverses the change. Can drop tables and data — confirm with "
+                "the user first."
+            ),
+            input_schema={
+                "from_version": _s(
+                    "Oldest migration version to roll back (inclusive).",
+                    "20250312000000",
+                ),
+                "project_ref": _ref(),
+            },
+            destructive=True,
+            parallelizable=False,
+            tags=(_MIGRATIONS,),
+        ),
+        # ═════════════════════════════════════════════════════════════
+        # Rows (PostgREST, service role) — tag: supabase_rows
+        # ═════════════════════════════════════════════════════════════
+        client_op(
+            "select_supabase_rows",
+            "select_rows",
+            description=(
+                "Read rows from a table or view with filters, ordering and "
+                "paging. Bypasses RLS (service role). Returns {rows, returned, "
+                "next_offset, total?}. The schema must be exposed to the API "
+                "(see get_supabase_service_config 'postgrest'); otherwise use "
+                "run_supabase_sql_readonly."
+            ),
+            input_schema={
+                "table": _table(),
+                "columns": _s(
+                    "PostgREST select list; supports embedded relations "
+                    "('id,total,customer:customers(name)'). Default '*'.",
+                    "id,status,total",
+                ),
+                "filters": _filters({"status": "eq.open"}),
+                "order": _s(
+                    "Ordering, e.g. 'created_at.desc' or 'name.asc,id.desc'.",
+                    "created_at.desc",
+                ),
+                "limit": _i("Max rows (default 30, capped by config max_rows).", 30),
+                "offset": _i("Rows to skip; pass next_offset to page.", 0),
+                "count": _b("Also return the exact total matching rows.", False),
+                "schema": _schema(),
+                "project_ref": _ref(),
+            },
+            tags=(_ROWS, _UMBRELLA),
+        ),
+        client_op(
+            "insert_supabase_rows",
+            "insert_rows",
+            description=(
+                "Insert one row (object) or many (list of objects) into a "
+                "table; set upsert=true to update rows that conflict on the "
+                "primary key or on_conflict columns. Bypasses RLS. Returns "
+                "the inserted rows."
+            ),
+            input_schema={
+                "table": _table(),
+                "rows": _arr(
+                    "Rows to insert (a single object is also accepted).",
+                    [{"name": "Widget", "price": 9.5}],
+                ),
+                "upsert": _b("Merge into existing rows on conflict.", False),
+                "on_conflict": _s(
+                    "Comma-separated unique columns for upsert. Default: "
+                    "primary key.",
+                    "",
+                ),
+                "schema": _schema(),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_ROWS, _UMBRELLA),
+        ),
+        client_op(
+            "update_supabase_rows",
+            "update_rows",
+            description=(
+                "Update the rows matching filters with new column values. "
+                "Filters are required (refuses to touch every row). Bypasses "
+                "RLS. Returns the updated rows."
+            ),
+            input_schema={
+                "table": _table(),
+                "values": _obj("Columns to set.", {"status": "shipped"}),
+                "filters": _filters({"id": "eq.42"}),
+                "schema": _schema(),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_ROWS, _UMBRELLA),
+        ),
+        client_op(
+            "delete_supabase_rows",
+            "delete_rows",
+            description=(
+                "Delete the rows matching filters. Filters are required "
+                "(refuses to delete every row). Bypasses RLS. Returns the "
+                "deleted rows."
+            ),
+            input_schema={
+                "table": _table(),
+                "filters": _filters({"id": "eq.42"}),
+                "schema": _schema(),
+                "project_ref": _ref(),
+            },
+            destructive=True,
+            parallelizable=False,
+            tags=(_ROWS, _UMBRELLA),
+        ),
+        client_op(
+            "call_supabase_rpc",
+            "call_rpc",
+            description=(
+                "Call a Postgres function exposed through the API "
+                "(/rest/v1/rpc/<function>) with named arguments. Returns the "
+                "function's result."
+            ),
+            input_schema={
+                "function": _s("Function name.", "get_monthly_revenue"),
+                "args": _obj("Named arguments.", {"month": "2026-09"}),
+                "schema": _schema(),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_ROWS,),
+        ),
+        # ═════════════════════════════════════════════════════════════
+        # Storage — tag: supabase_storage
+        # ═════════════════════════════════════════════════════════════
+        client_op(
+            "list_supabase_buckets",
+            "list_buckets",
+            description=(
+                "List storage buckets: id, public flag, file size limit and "
+                "allowed MIME types."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_STORAGE,),
+        ),
+        client_op(
+            "create_supabase_bucket",
+            "create_bucket",
+            description=(
+                "Create a storage bucket. public=true makes every file "
+                "readable by URL without auth. Returns the bucket name."
+            ),
+            input_schema={
+                "name": _s("Bucket id/name (lowercase, no spaces).", "avatars"),
+                "public": _b("Files readable without auth.", False),
+                "file_size_limit": _i("Max file size in bytes.", 5242880),
+                "allowed_mime_types": _arr(
+                    "Accepted MIME types; wildcards ok.", ["image/*"]
+                ),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_STORAGE,),
+        ),
+        client_op(
+            "update_supabase_bucket",
+            "update_bucket",
+            description=(
+                "Change a bucket's public flag, size limit or allowed MIME "
+                "types. Unspecified settings are kept."
+            ),
+            input_schema={
+                "name": _bucket(),
+                "public": _b("Files readable without auth.", False),
+                "file_size_limit": _i("Max file size in bytes.", 10485760),
+                "allowed_mime_types": _arr("Accepted MIME types.", ["image/*"]),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_STORAGE,),
+        ),
+        client_op(
+            "delete_supabase_bucket",
+            "delete_bucket",
+            description=(
+                "Delete a storage bucket. It must be empty — call "
+                "empty_supabase_bucket first."
+            ),
+            input_schema={"name": _bucket(), "project_ref": _ref()},
+            destructive=True,
+            parallelizable=False,
+            tags=(_STORAGE,),
+        ),
+        client_op(
+            "empty_supabase_bucket",
+            "empty_bucket",
+            description=(
+                "Permanently delete every file in a bucket (the bucket itself "
+                "stays). Irreversible — confirm with the user first."
+            ),
+            input_schema={"name": _bucket(), "project_ref": _ref()},
+            destructive=True,
+            parallelizable=False,
+            tags=(_STORAGE,),
+        ),
+        client_op(
+            "list_supabase_files",
+            "list_files",
+            description=(
+                "List files and folders in a bucket under a prefix (one level, "
+                "like `ls`). Entries with is_folder=true are prefixes to list "
+                "next. Returns name, size/mimetype metadata and timestamps."
+            ),
+            input_schema={
+                "bucket": _bucket(),
+                "prefix": _s("Folder path to list. Default: bucket root.", "users/42"),
+                "search": _s("Only names containing this text.", ""),
+                "limit": _i("Max entries (default 100, max 1000).", 100),
+                "offset": _i("Entries to skip.", 0),
+                "project_ref": _ref(),
+            },
+            tags=(_STORAGE, _UMBRELLA),
+        ),
+        client_op(
+            "upload_supabase_file",
+            "upload_file",
+            description=(
+                "Upload a local file to a bucket at the given object path. "
+                "Fails if the path exists unless upsert=true. Returns bucket, "
+                "path, size and content type."
+            ),
+            input_schema={
+                "bucket": _bucket(),
+                "path": _object_path(),
+                "file_path": _s(
+                    "Absolute local path of the file to upload.",
+                    "/home/user/workspace/profile.png",
+                ),
+                "upsert": _b("Overwrite an existing object.", False),
+                "content_type": _s("MIME type. Default: guessed from name.", ""),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_STORAGE, _UMBRELLA),
+        ),
+        client_op(
+            "download_supabase_file",
+            "download_file",
+            description=(
+                "Download a file from a bucket to a local path. Returns "
+                "saved_to, size and content type."
+            ),
+            input_schema={
+                "bucket": _bucket(),
+                "path": _object_path(),
+                "save_to": _s(
+                    "Absolute local path to write.",
+                    "/home/user/workspace/profile.png",
+                ),
+                "project_ref": _ref(),
+            },
+            tags=(_STORAGE, _UMBRELLA),
+        ),
+        client_op(
+            "delete_supabase_files",
+            "delete_files",
+            description=(
+                "Delete one or more files from a bucket by object path. "
+                "Returns the deleted objects."
+            ),
+            input_schema={
+                "bucket": _bucket(),
+                "paths": _arr("Object paths to delete.", ["users/42/old.png"]),
+                "project_ref": _ref(),
+            },
+            destructive=True,
+            parallelizable=False,
+            tags=(_STORAGE, _UMBRELLA),
+        ),
+        client_op(
+            "move_supabase_file",
+            "move_file",
+            description=(
+                "Move or rename a file within a bucket, or to another bucket "
+                "with to_bucket."
+            ),
+            input_schema={
+                "bucket": _bucket(),
+                "from_path": _object_path(),
+                "to_path": _s("New object path.", "users/42/avatar.png"),
+                "to_bucket": _s("Destination bucket if different.", ""),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_STORAGE,),
+        ),
+        client_op(
+            "copy_supabase_file",
+            "copy_file",
+            description=(
+                "Copy a file to a new path in the same bucket, or to another "
+                "bucket with to_bucket."
+            ),
+            input_schema={
+                "bucket": _bucket(),
+                "from_path": _object_path(),
+                "to_path": _s("Destination object path.", "backups/profile.png"),
+                "to_bucket": _s("Destination bucket if different.", ""),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_STORAGE,),
+        ),
+        client_op(
+            "create_supabase_signed_url",
+            "create_signed_url",
+            description=(
+                "Create a time-limited download URL for a file in a private "
+                "bucket, shareable with anyone. Returns signed_url and also the "
+                "permanent public URL form (works only for public buckets)."
+            ),
+            input_schema={
+                "bucket": _bucket(),
+                "path": _object_path(),
+                "expires_in": _i("Validity in seconds (default 3600).", 3600),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_STORAGE,),
+        ),
+        # ═════════════════════════════════════════════════════════════
+        # Auth users — tag: supabase_auth
+        # ═════════════════════════════════════════════════════════════
+        client_op(
+            "list_supabase_users",
+            "list_users",
+            description=(
+                "List the project's end users (Supabase Auth): id (UUID), "
+                "email, phone, providers, created/last-sign-in times, "
+                "metadata. Paged; returns next_page when more exist."
+            ),
+            input_schema={
+                "page": _i("Page number, from 1.", 1),
+                "per_page": _i("Users per page (default 50, max 1000).", 50),
+                "project_ref": _ref(),
+            },
+            tags=(_AUTH, _UMBRELLA),
+        ),
+        client_op(
+            "get_supabase_user",
+            "get_user",
+            description="Get one auth user by UUID, including identities and metadata.",
+            input_schema={
+                "user_id": _s("User UUID.", "7f3c2a10-1b2c-4d5e-8f90-a1b2c3d4e5f6"),
+                "project_ref": _ref(),
+            },
+            tags=(_AUTH,),
+        ),
+        client_op(
+            "create_supabase_user",
+            "create_user",
+            description=(
+                "Create an auth user directly (no email sent). Set "
+                "email_confirm=true to skip email verification. Returns the "
+                "new user."
+            ),
+            input_schema={
+                "email": _s("Email address.", "jane@example.com"),
+                "phone": _s("Phone in E.164.", ""),
+                "password": _s("Initial password.", ""),
+                "email_confirm": _b("Mark the email as confirmed.", True),
+                "phone_confirm": _b("Mark the phone as confirmed.", False),
+                "user_metadata": _obj("Profile data the user can edit.",
+                                      {"full_name": "Jane Doe"}),
+                "app_metadata": _obj("Server-controlled data (roles, plan).",
+                                     {"role": "admin"}),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_AUTH,),
+        ),
+        client_op(
+            "update_supabase_user",
+            "update_user",
+            description=(
+                "Update an auth user by UUID: email, phone, password, "
+                "confirmation flags, metadata, or ban_duration ('24h', "
+                "'876000h' to ban, 'none' to unban). Returns the user."
+            ),
+            input_schema={
+                "user_id": _s("User UUID.", "7f3c2a10-1b2c-4d5e-8f90-a1b2c3d4e5f6"),
+                "email": _s("New email.", ""),
+                "phone": _s("New phone.", ""),
+                "password": _s("New password.", ""),
+                "email_confirm": _b("Mark the email as confirmed.", True),
+                "phone_confirm": _b("Mark the phone as confirmed.", False),
+                "user_metadata": _obj("Replaces user_metadata.", {}),
+                "app_metadata": _obj("Replaces app_metadata.", {}),
+                "ban_duration": _s("Ban length, or 'none' to lift a ban.", ""),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_AUTH,),
+        ),
+        client_op(
+            "delete_supabase_user",
+            "delete_user",
+            description=(
+                "Delete an auth user by UUID. soft_delete=true keeps the row "
+                "(anonymised) so foreign keys don't break."
+            ),
+            input_schema={
+                "user_id": _s("User UUID.", "7f3c2a10-1b2c-4d5e-8f90-a1b2c3d4e5f6"),
+                "soft_delete": _b("Soft delete instead of hard delete.", False),
+                "project_ref": _ref(),
+            },
+            destructive=True,
+            parallelizable=False,
+            tags=(_AUTH,),
+        ),
+        client_op(
+            "invite_supabase_user",
+            "invite_user",
+            description=(
+                "Send an invitation email (via the project's auth email "
+                "settings) so a new user can set a password. Returns the "
+                "invited user."
+            ),
+            input_schema={
+                "email": _s("Email to invite.", "jane@example.com"),
+                "redirect_to": _s(
+                    "URL to land on after accepting; must be in the auth "
+                    "redirect allow-list.",
+                    "https://app.acme.com/welcome",
+                ),
+                "data": _obj("Initial user_metadata.", {}),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_AUTH,),
+        ),
+        client_op(
+            "generate_supabase_auth_link",
+            "generate_auth_link",
+            description=(
+                "Generate an auth action link WITHOUT sending email — for "
+                "magic links, password recovery, signup confirmation, invite "
+                "or email change. Returns action_link and the user. Treat the "
+                "link as a credential."
+            ),
+            input_schema={
+                "link_type": _s(
+                    "signup | magiclink | recovery | invite | "
+                    "email_change_current | email_change_new.",
+                    "magiclink",
+                ),
+                "email": _s("User email.", "jane@example.com"),
+                "password": _s("Required for type 'signup'.", ""),
+                "new_email": _s("Required for email_change types.", ""),
+                "redirect_to": _s("Post-action redirect URL.", ""),
+                "data": _obj("user_metadata for signup/invite.", {}),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_AUTH,),
+        ),
+        # ═════════════════════════════════════════════════════════════
+        # Edge functions — tag: supabase_functions
+        # ═════════════════════════════════════════════════════════════
+        client_op(
+            "list_supabase_functions",
+            "list_functions",
+            description=(
+                "List the project's edge functions: slug (the identifier), "
+                "name, status, version, verify_jwt and timestamps."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_FUNCTIONS, _UMBRELLA),
+        ),
+        client_op(
+            "get_supabase_function",
+            "get_function",
+            description=(
+                "Get one edge function's metadata by slug (status, version, "
+                "entrypoint, verify_jwt). Source code is not retrievable "
+                "through the API."
+            ),
+            input_schema={
+                "slug": _s("Function slug.", "hello-world"),
+                "project_ref": _ref(),
+            },
+            tags=(_FUNCTIONS,),
+        ),
+        client_op(
+            "deploy_supabase_function",
+            "deploy_function",
+            description=(
+                "Create or redeploy an edge function (Deno/TypeScript) from "
+                "source. Pass 'files' as {relative_path: source} or a local "
+                "'source_dir'. Redeploying an existing slug replaces its code. "
+                "Returns the function with its new version."
+            ),
+            input_schema={
+                "slug": _s("Function slug (letters, digits, - and _).", "hello-world"),
+                "files": _obj(
+                    "Source files keyed by path relative to the function root.",
+                    {
+                        "index.ts": "Deno.serve(async (req) => new Response("
+                        "JSON.stringify({ ok: true }), { headers: { "
+                        "'Content-Type': 'application/json' } }))"
+                    },
+                ),
+                "source_dir": _s(
+                    "Alternative to 'files': local folder holding the function.",
+                    "",
+                ),
+                "entrypoint": _s("Entrypoint file. Default 'index.ts'.", "index.ts"),
+                "name": _s("Display name. Default: the slug.", ""),
+                "verify_jwt": _b(
+                    "Require a valid JWT in Authorization. Set false for "
+                    "public webhooks.",
+                    True,
+                ),
+                "import_map_path": _s("Import map / deno.json path, if any.", ""),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_FUNCTIONS, _UMBRELLA),
+        ),
+        client_op(
+            "update_supabase_function",
+            "update_function",
+            description=(
+                "Change an edge function's display name or verify_jwt setting "
+                "without redeploying code."
+            ),
+            input_schema={
+                "slug": _s("Function slug.", "hello-world"),
+                "name": _s("New display name.", ""),
+                "verify_jwt": _b("Require a valid JWT.", True),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_FUNCTIONS,),
+        ),
+        client_op(
+            "delete_supabase_function",
+            "delete_function",
+            description="Delete an edge function by slug. Its URL stops working immediately.",
+            input_schema={
+                "slug": _s("Function slug.", "hello-world"),
+                "project_ref": _ref(),
+            },
+            destructive=True,
+            parallelizable=False,
+            tags=(_FUNCTIONS, _UMBRELLA),
+        ),
+        client_op(
+            "invoke_supabase_function",
+            "invoke_function",
+            description=(
+                "Call a deployed edge function over HTTP with a JSON body. "
+                "Returns status_code, content_type and the parsed response "
+                "body. Runs with service-role credentials."
+            ),
+            input_schema={
+                "slug": _s("Function slug.", "hello-world"),
+                "body": _obj("JSON request body.", {"name": "Jane"}),
+                "method": _s("HTTP method. Default POST.", "POST"),
+                "headers": _obj("Extra request headers.", {}),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_FUNCTIONS, _UMBRELLA),
+        ),
+        # ═════════════════════════════════════════════════════════════
+        # Secrets — tag: supabase_secrets
+        # ═════════════════════════════════════════════════════════════
+        client_op(
+            "list_supabase_secrets",
+            "list_secrets",
+            description=(
+                "List the names of the project's edge-function secrets "
+                "(environment variables). Values are never returned."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_SECRETS,),
+        ),
+        client_op(
+            "set_supabase_secrets",
+            "set_secrets",
+            description=(
+                "Create or overwrite edge-function secrets, readable in "
+                "functions via Deno.env.get(NAME). Names may not start with "
+                "SUPABASE_. Returns the names set."
+            ),
+            input_schema={
+                "secrets": _obj(
+                    "NAME → value.", {"STRIPE_WEBHOOK_SECRET": "whsec_..."}
+                ),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_SECRETS,),
+        ),
+        client_op(
+            "delete_supabase_secrets",
+            "delete_secrets",
+            description="Delete edge-function secrets by name.",
+            input_schema={
+                "names": _arr("Secret names to delete.", ["OLD_API_KEY"]),
+                "project_ref": _ref(),
+            },
+            destructive=True,
+            parallelizable=False,
+            tags=(_SECRETS,),
+        ),
+        # ═════════════════════════════════════════════════════════════
+        # Branches — tag: supabase_branches
+        # ═════════════════════════════════════════════════════════════
+        client_op(
+            "list_supabase_branches",
+            "list_branches",
+            description=(
+                "List a project's preview/persistent branches: id, name, its "
+                "own project_ref, git branch, status. Requires branching "
+                "enabled on a paid plan."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_BRANCHES,),
+        ),
+        client_op(
+            "get_supabase_branch",
+            "get_branch",
+            description=(
+                "Get a branch's database details (host, port, Postgres "
+                "version, status) by branch id or branch ref."
+            ),
+            input_schema={"branch_id": _branch_id()},
+            tags=(_BRANCHES,),
+        ),
+        client_op(
+            "create_supabase_branch",
+            "create_branch",
+            description=(
+                "Create a development branch — a separate copy of the project "
+                "with the same migrations. Billed per hour; confirm with the "
+                "user. Work on it with its own project_ref."
+            ),
+            input_schema={
+                "branch_name": _s("Branch name.", "feature-login"),
+                "git_branch": _s("Linked git branch, if any.", ""),
+                "persistent": _b("Keep it instead of auto-pausing.", False),
+                "with_data": _b("Copy production data into the branch.", False),
+                "region": _s("Region code. Default: parent's region.", ""),
+                "project_ref": _ref(),
+            },
+            parallelizable=False,
+            tags=(_BRANCHES,),
+        ),
+        client_op(
+            "update_supabase_branch",
+            "update_branch",
+            description="Rename a branch, change its git branch, or toggle persistence.",
+            input_schema={
+                "branch_id": _branch_id(),
+                "branch_name": _s("New name.", ""),
+                "git_branch": _s("Linked git branch.", ""),
+                "persistent": _b("Keep it running.", True),
+            },
+            parallelizable=False,
+            tags=(_BRANCHES,),
+        ),
+        client_op(
+            "delete_supabase_branch",
+            "delete_branch",
+            description="Delete a branch and its database.",
+            input_schema={"branch_id": _branch_id()},
+            destructive=True,
+            parallelizable=False,
+            tags=(_BRANCHES,),
+        ),
+        client_op(
+            "merge_supabase_branch",
+            "merge_branch",
+            description=(
+                "Merge a branch's migrations (and edge functions) into the "
+                "parent project. Check diff_supabase_branch first. Returns a "
+                "workflow_run_id."
+            ),
+            input_schema={
+                "branch_id": _branch_id(),
+                "migration_version": _s("Merge only up to this version.", ""),
+            },
+            parallelizable=False,
+            tags=(_BRANCHES,),
+        ),
+        client_op(
+            "reset_supabase_branch",
+            "reset_branch",
+            description=(
+                "Reset a branch's database to its migrations, discarding all "
+                "data and untracked changes on the branch."
+            ),
+            input_schema={
+                "branch_id": _branch_id(),
+                "migration_version": _s("Reset to this version.", ""),
+            },
+            destructive=True,
+            parallelizable=False,
+            tags=(_BRANCHES,),
+        ),
+        client_op(
+            "diff_supabase_branch",
+            "diff_branch",
+            description=(
+                "Show the schema SQL diff between a branch and its parent — "
+                "what merge_supabase_branch would apply."
+            ),
+            input_schema={
+                "branch_id": _branch_id(),
+                "schemas": _arr("Schemas to diff. Default: all.", ["public"]),
+            },
+            tags=(_BRANCHES,),
+        ),
+        # ═════════════════════════════════════════════════════════════
+        # Monitoring — tag: supabase_monitoring
+        # ═════════════════════════════════════════════════════════════
+        client_op(
+            "get_supabase_logs",
+            "get_logs",
+            description=(
+                "Recent logs for one project service, newest first. source: "
+                "api, postgres, auth, storage, realtime, edge_function "
+                "(invocations), edge_function_runtime (console output), "
+                "postgrest, pooler. Window up to 24h. Pass 'sql' for a custom "
+                "Logflare query instead."
+            ),
+            input_schema={
+                "source": _s("Log source.", "postgres"),
+                "minutes": _i("Look-back window in minutes (max 1440).", 60),
+                "limit": _i("Max log lines (default 100).", 100),
+                "search": _s("Case-insensitive regex on the message.", "error"),
+                "sql": _s("Custom log query; overrides source/search/limit.", ""),
+                "project_ref": _ref(),
+            },
+            tags=(_MONITORING, _UMBRELLA),
+        ),
+        client_op(
+            "get_supabase_security_advisors",
+            "get_security_advisors",
+            description=(
+                "Security lint for the project: tables without RLS, policies "
+                "that leak data, exposed auth.users, mutable search paths. "
+                "Each finding has a level, description and remediation link."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_MONITORING, _UMBRELLA),
+        ),
+        client_op(
+            "get_supabase_performance_advisors",
+            "get_performance_advisors",
+            description=(
+                "Performance lint for the project: unindexed foreign keys, "
+                "unused or duplicate indexes, slow RLS patterns."
+            ),
+            input_schema={"project_ref": _ref()},
+            tags=(_MONITORING,),
+        ),
+        client_op(
+            "get_supabase_api_usage",
+            "get_api_usage",
+            description=(
+                "API request counts over time (REST, auth, storage, realtime) "
+                "for an interval: 15min, 30min, 1hr, 3hr, 1day, 3day, 7day."
+            ),
+            input_schema={
+                "interval": _s("Time window.", "1day"),
+                "project_ref": _ref(),
+            },
+            tags=(_MONITORING,),
+        ),
+    ]
+
+
+# ────────────────────────────────────────────────────────────────────────
+# Intentionally excluded (Management API v1, 169 endpoints) — one line per
+# group, so the next session doesn't re-litigate it.
+#
+# Billing / add-ons (billing/addons)          — money; dashboard only.
+# Organization create + project-claim tokens  — account administration.
+# Project API-key management (api-keys CRUD,
+#   legacy-key toggle, JWT signing keys)       — credential admin; the client
+#                                                reads keys internally only.
+# SSO providers, third-party auth             — org identity admin.
+# Network bans / restrictions, SSL enforcement — perimeter security; a
+#                                                wrong call locks the user out.
+# JIT database access, CLI login role         — privilege grants.
+# pgsodium root key                           — rotating it makes encrypted
+#                                                data unreadable.
+# Backup restore / PITR / restore points /
+#   undo                                       — overwrites the live database;
+#                                                listing backups is kept.
+# Postgres version upgrade, disk config /
+#   autoscale, read replicas, pooler config   — infra changes with cost and
+#                                                downtime.
+# Custom hostname, vanity subdomain           — DNS-coupled, multi-step.
+# Readonly-mode override, database webhooks
+#   enable, realtime shutdown                  — operational escape hatches.
+# Branch push / restore, disable branching,
+#   action runs                                — CI plumbing, covered by
+#                                                merge/reset/diff.
+# Function bulk update, function body          — bulk update is CI plumbing;
+#                                                body is an eszip bundle, not
+#                                                readable source.
+# Analytics: metrics scrape, function stats,
+#   requests-count                             — overlaps get_supabase_logs /
+#                                                get_supabase_api_usage.
+# SQL snippets, entitlements, database
+#   context, PostgREST OpenAPI                 — dashboard conveniences;
+#                                                list_supabase_tables covers it.
+# OAuth endpoints                              — used by the provider, not
+#                                                the agent.
+# ────────────────────────────────────────────────────────────────────────
diff --git a/craftos_integrations/providers/supabase/provider.py b/craftos_integrations/providers/supabase/provider.py
new file mode 100644
index 000000000..f562ceb5c
--- /dev/null
+++ b/craftos_integrations/providers/supabase/provider.py
@@ -0,0 +1,420 @@
+"""Supabase provider — personal access token or OAuth, one credential for
+every project the account can reach.
+
+**Auth decision (README "three questions").** Supabase OAuth installs our
+app into the user's *organization*: calls act as that user (Q1: user's
+identity), Management API rate limits are counted per user/token (Q2:
+user's quota), and abuse gets the user's account limited, not every
+install (Q3: user's account). All three are "the user's", so OAuth with
+our embedded client credentials is the right one-click path. Supabase
+OAuth apps are confidential clients (``client_secret_basic``) with PKCE
+S256 — confirmed against ``/.well-known/oauth-authorization-server``.
+
+That path needs a registered Supabase OAuth app (Organization settings →
+OAuth Apps, redirect URI ``http://localhost:8765``) whose id and secret
+land in ``SUPABASE_SHARED_CLIENT_ID`` / ``SUPABASE_SHARED_CLIENT_SECRET``.
+Until they are configured ``auth_type`` reports ``"token"`` so the UI does
+not offer a button that cannot work; the moment they are set it reports
+``"both"`` — nothing else moves. The personal-access-token path is always
+available and is the fallback for power users.
+
+**Identity.** A personal access token belongs to a *user* and spans every
+organization that user is in. The Management API won't tell an access
+token who its user is (``/v1/profile`` answers 403 to PATs), so a PAT
+account is keyed ``token:<sha256 fingerprint>`` — or ``user:<gotrue id>``
+on the rare occasion the profile is readable. An OAuth grant is scoped to the one organization the user picked on
+Supabase's consent screen, so an OAuth account is keyed ``org:<slug>`` —
+the same person granting two organizations gets two accounts, which is
+exactly how the grants behave.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import time
+from dataclasses import asdict
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Tuple
+
+from ...config import ConfigStore
+from ...contracts import OAuthSpec, Operation
+from ...helpers import request as http_request
+from ...logger import get_logger
+from ...oauth_flow import OAuthFlow
+from .._shared import ClientListenerAdapter, read_guidance
+from .client import (
+    SUPABASE_CLIENT_ID_KEY,
+    SUPABASE_CLIENT_SECRET_KEY,
+    SUPABASE_MGMT,
+    SUPABASE_OAUTH_AUTHORIZE,
+    SUPABASE_OAUTH_TOKEN,
+    SUPABASE_SCOPES,
+    SupabaseClient,
+    SupabaseConfig,
+    SupabaseCredential,
+)
+from .operations import build_operations
+
+logger = get_logger(__name__)
+
+# Keys users paste by mistake, with the message that sends them to the
+# right one. Checked before spending a request — every one of these gets
+# an unhelpful 401 from the Management API.
+_WRONG_KEY_PREFIXES = (
+    (
+        "sb_secret_",
+        "That's a project secret key (sb_secret_…). It only works for one "
+        "project's data API. Create a personal access token instead: "
+        "supabase.com/dashboard/account/tokens.",
+    ),
+    (
+        "sb_publishable_",
+        "That's a project publishable key (sb_publishable_…), meant for "
+        "browsers and apps. Create a personal access token instead: "
+        "supabase.com/dashboard/account/tokens.",
+    ),
+    (
+        "eyJ",
+        "That looks like a project anon or service_role key (a JWT). Those "
+        "only work for one project's data API. Create a personal access "
+        "token instead: supabase.com/dashboard/account/tokens.",
+    ),
+)
+
+
+def token_fingerprint(token: str) -> str:
+    """Stable, non-reversible id for a personal access token.
+
+    The Management API exposes no "who am I" endpoint to access tokens
+    (/v1/profile answers 403), so the token itself is the only stable
+    thing that identifies the account. Re-connecting with the same token
+    updates the account in place; a new token is a new account.
+    """
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()[:16]
+
+
+def _rejection_message(result: Dict[str, Any]) -> str:
+    """Turn a failed validity check into what the user should do."""
+    error = str(result.get("error") or "")
+    detail = str(result.get("details") or "")[:200]
+    if "401" in error:
+        return (
+            "Supabase rejected the token (401): it's invalid, expired or "
+            "revoked. Generate a new one at supabase.com/dashboard/account/tokens "
+            "and paste it whole."
+        )
+    if "403" in error:
+        return (
+            "Supabase accepted the token but refused to list your "
+            f"organizations (403). {detail}".strip()
+        )
+    return f"Couldn't reach Supabase to check the token: {error} {detail}".strip()
+
+
+def _text(value: Any) -> str:
+    if value is None or isinstance(value, (dict, list)):
+        return ""
+    return str(value).strip()
+
+
+class SupabaseProvider:
+    id = "supabase"
+    family = None  # standalone — no cross-provider alias sharing
+
+    # ----- UI metadata -----
+    display_name = "Supabase"
+    description = "Postgres database, auth, storage, edge functions and projects"
+    icon = "supabase"
+    fields = [
+        {
+            "key": "access_token",
+            "label": "Personal Access Token (sbp_…)",
+            "placeholder": "sbp_…",
+            "password": True,
+        },
+    ]
+    connect_help = [
+        "Open supabase.com/dashboard/account/tokens (avatar → Account "
+        "preferences → Access Tokens)",
+        "Click 'Generate new token' and name it (e.g. 'CraftBot')",
+        "Copy the token — it starts with sbp_ and is shown only once",
+        "Paste it here. One token covers every project in every organization "
+        "you belong to; the agent reads each project's keys on its own",
+        "Not a project API key: sb_secret_, sb_publishable_ and anon/"
+        "service_role keys won't work here",
+    ]
+    subcommands = ["invite", "login", "logout", "status"]
+
+    config_class = SupabaseConfig
+    config_fields = [
+        {
+            "key": "default_project_ref",
+            "label": "Default project",
+            "type": "text",
+            "placeholder": "abcdefghijklmnopqrst",
+            "help": (
+                "Project ref used when an action omits 'project_ref'. Find it in "
+                "the project URL (supabase.com/dashboard/project/<ref>) or with "
+                "list_supabase_projects."
+            ),
+        },
+        {
+            "key": "read_only",
+            "label": "Read-only mode",
+            "type": "checkbox",
+            "help": (
+                "Refuse every change — SQL writes, migrations, row edits, "
+                "uploads, deploys, project changes. Reads keep working."
+            ),
+        },
+        {
+            "key": "max_rows",
+            "label": "Max rows per read",
+            "type": "number",
+            "placeholder": "500",
+            "help": "Ceiling on rows select_supabase_rows returns in one call.",
+        },
+    ]
+
+    client_cls = SupabaseClient
+
+    # ----- auth type follows configuration -----
+
+    @property
+    def auth_type(self) -> str:
+        """``both`` once our OAuth app's credentials are configured,
+        ``token`` until then — never advertise a flow that cannot run."""
+        if ConfigStore.get_oauth(SUPABASE_CLIENT_ID_KEY) and ConfigStore.get_oauth(
+            SUPABASE_CLIENT_SECRET_KEY
+        ):
+            return "both"
+        return "token"
+
+    # ----- accounts -----
+
+    def identity_of(self, credential: Dict[str, Any]) -> Optional[str]:
+        """``org:<slug>`` for OAuth grants; ``user:<id>`` for personal
+        tokens when the profile is readable, else ``token:<fingerprint>``
+        (see module docstring). Lowercased; None for junk."""
+        if not isinstance(credential, dict):
+            return None
+        kind = _text(credential.get("auth_kind")).lower()
+        org = _text(credential.get("org_slug"))
+        user = _text(credential.get("user_id")) or _text(credential.get("email"))
+        token_id = _text(credential.get("token_id"))
+        if kind == "oauth" and org:
+            return f"org:{org}".lower()
+        if user:
+            return f"user:{user}".lower()
+        if token_id:
+            return f"token:{token_id}".lower()
+        if org:
+            return f"org:{org}".lower()
+        return None
+
+    def default_alias(self, credential: Dict[str, Any]) -> Optional[str]:
+        """Name for a newly connected account. The identity is opaque (a
+        token fingerprint or org slug), so suggest what the user knows it
+        by: their email, the OAuth organization, or the projects it reaches.
+        """
+        if not isinstance(credential, dict):
+            return None
+        for key in ("email", "org_name", "display_name"):
+            value = _text(credential.get(key))
+            if value:
+                return value[:60]
+        return None
+
+    def oauth_spec(self) -> OAuthSpec:
+        """Supabase's consent screen asks the user which organization to
+        grant, so a second connect can pick a different one."""
+        return OAuthSpec(
+            authorize_url=SUPABASE_OAUTH_AUTHORIZE,
+            token_url=SUPABASE_OAUTH_TOKEN,
+            scopes=SUPABASE_SCOPES,
+            has_chooser=True,
+        )
+
+    def build_client(
+        self,
+        credential: Dict[str, Any],
+        persist: Callable[[Dict[str, Any]], None],
+    ) -> Any:
+        client = self.client_cls()
+        client.bind_credential(credential, persist)
+        return client
+
+    async def refresh(self, credential: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Out-of-band refresh. Operations refresh inline before each
+        Management API call; personal access tokens never expire."""
+        if _text(credential.get("auth_kind")) != "oauth":
+            return None
+        holder: Dict[str, Any] = {}
+        client = self.build_client(credential, holder.update)
+        ok = await asyncio.to_thread(client._refresh_sync)
+        return holder or None if ok else None
+
+    # ----- token path -----
+
+    def verify_token(
+        self, credentials: Dict[str, str]
+    ) -> Tuple[bool, str, Optional[Dict[str, Any]]]:
+        """Validate a personal access token and capture the user identity.
+
+        Rejects the project-level keys users reach for by mistake before
+        spending a request. Unknown prefixes are still tried — Supabase
+        has changed token formats before and a strict allow-list would
+        lock out a valid new one.
+        """
+        token = (credentials.get("access_token") or "").strip()
+        if not token:
+            return False, "Missing Supabase personal access token (access_token).", None
+        for prefix, message in _WRONG_KEY_PREFIXES:
+            if token.startswith(prefix):
+                return False, message, None
+
+        headers = {"Authorization": f"Bearer {token}"}
+        # Validity check against an endpoint access tokens are actually
+        # granted. /v1/profile is NOT one of them: it carries no permission
+        # scope in the API schema and answers 403 to personal access
+        # tokens, so it can only ever be a best-effort extra.
+        orgs = http_request(
+            "GET", f"{SUPABASE_MGMT}/organizations", headers=headers, expected=(200,)
+        )
+        if "error" in orgs:
+            return False, _rejection_message(orgs), None
+        org_list = [o for o in (orgs.get("result") or []) if isinstance(o, dict)]
+        org_names = [o.get("name") for o in org_list if o.get("name")]
+
+        profile = http_request(
+            "GET", f"{SUPABASE_MGMT}/profile", headers=headers, expected=(200,)
+        )
+        me = (profile.get("result") or {}) if "error" not in profile else {}
+
+        credential = asdict(
+            SupabaseCredential(
+                access_token=token,
+                auth_kind="token",
+                token_id=token_fingerprint(token),
+                user_id=_text(me.get("gotrue_id")),
+                email=_text(me.get("primary_email")),
+                username=_text(me.get("username")),
+            )
+        )
+        who = credential["email"] or credential["username"] or "Supabase token"
+        # Some tokens list no organizations even though they reach projects
+        # (seen live) — so describe reach by projects, not organizations.
+        projects = http_request(
+            "GET", f"{SUPABASE_MGMT}/projects", headers=headers, expected=(200,)
+        )
+        project_names = [
+            p.get("name")
+            for p in ((projects.get("result") or []) if "error" not in projects else [])
+            if isinstance(p, dict) and p.get("name")
+        ]
+        parts = []
+        if org_names:
+            parts.append(f"{len(org_names)} organization(s): {', '.join(org_names)}")
+        if project_names:
+            shown = ", ".join(project_names[:5])
+            more = f" +{len(project_names) - 5} more" if len(project_names) > 5 else ""
+            parts.append(f"{len(project_names)} project(s): {shown}{more}")
+        scope = " · ".join(parts) or "no projects visible yet"
+        if project_names:
+            more = f" +{len(project_names) - 2}" if len(project_names) > 2 else ""
+            credential["display_name"] = ", ".join(project_names[:2]) + more
+        return True, f"Supabase connected: {who} — {scope}", credential
+
+    # ----- OAuth path -----
+
+    async def run_login(self) -> Tuple[Optional[str], Optional[Dict[str, Any]], str]:
+        """Browser OAuth: authorize → token → read which organization was
+        granted. Returns (identity, credential, message)."""
+        if self.auth_type != "both":
+            return (
+                None,
+                None,
+                "Supabase OAuth isn't configured in this build (missing "
+                f"{SUPABASE_CLIENT_ID_KEY}/{SUPABASE_CLIENT_SECRET_KEY}). Connect "
+                "with a personal access token instead.",
+            )
+        flow = OAuthFlow(
+            client_id_key=SUPABASE_CLIENT_ID_KEY,
+            client_secret_key=SUPABASE_CLIENT_SECRET_KEY,
+            auth_url=SUPABASE_OAUTH_AUTHORIZE,
+            token_url=SUPABASE_OAUTH_TOKEN,
+            # Permissions are fixed on the registered OAuth app; Supabase
+            # does not take a scope parameter on authorize.
+            scopes="",
+            use_pkce=True,
+            token_auth_basic=True,
+        )
+        result = await flow.run()
+        access_token = result.get("access_token") or ""
+        if not access_token:
+            return None, None, f"Supabase OAuth failed: {result.get('error', 'no token')}"
+
+        headers = {"Authorization": f"Bearer {access_token}"}
+        orgs = http_request(
+            "GET", f"{SUPABASE_MGMT}/organizations", headers=headers, expected=(200,)
+        )
+        org_list = [o for o in (orgs.get("result") or []) if isinstance(o, dict)] \
+            if "error" not in orgs else []
+        org = org_list[0] if org_list else {}
+        if len(org_list) > 1:
+            logger.warning(
+                "[SUPABASE] OAuth grant spans %d organizations; keying the "
+                "account by the first (%s).", len(org_list), org.get("slug")
+            )
+
+        # Best effort — some OAuth grants cannot read /profile.
+        profile = http_request(
+            "GET", f"{SUPABASE_MGMT}/profile", headers=headers, expected=(200,)
+        )
+        me = (profile.get("result") or {}) if "error" not in profile else {}
+
+        expires_in = float(result.get("expires_in") or 0)
+        credential = asdict(
+            SupabaseCredential(
+                access_token=access_token,
+                auth_kind="oauth",
+                refresh_token=result.get("refresh_token") or "",
+                token_expiry=time.time() + expires_in if expires_in else 0.0,
+                user_id=_text(me.get("gotrue_id")),
+                email=_text(me.get("primary_email")),
+                username=_text(me.get("username")),
+                org_slug=_text(org.get("slug")),
+                org_name=_text(org.get("name")),
+            )
+        )
+        identity = self.identity_of(credential)
+        label = credential["org_name"] or credential["org_slug"] or "organization"
+        message = f"Supabase connected via OAuth: {label}"
+        if not identity:
+            message += " (organization not captured — stored without an identity)"
+        return identity, credential, message
+
+    # ----- agent surface -----
+
+    def operations(self) -> List[Operation]:
+        return build_operations()
+
+    def guidance(self) -> str:
+        return read_guidance(__file__)
+
+    def make_listener(
+        self,
+        client: Any,
+        cursor: Optional[Dict[str, Any]],
+        emit: Callable[[Dict[str, Any]], Awaitable[None]],
+    ) -> Optional[ClientListenerAdapter]:
+        """No inbound events in v1.
+
+        Supabase's push channels (database webhooks, Realtime) deliver to a
+        public URL or a long-lived websocket per project; neither fits the
+        per-account listener model without choosing tables to watch.
+        Checked dynamically so a future client loop bridges automatically.
+        """
+        if getattr(client, "supports_listening", False):
+            return ClientListenerAdapter(client, emit)
+        return None
diff --git a/scripts/smoke_supabase.py b/scripts/smoke_supabase.py
new file mode 100644
index 000000000..d1cd6181b
--- /dev/null
+++ b/scripts/smoke_supabase.py
@@ -0,0 +1,383 @@
+#!/usr/bin/env python
+"""Live smoke test for the Supabase integration — the gate the offline checks can't cover.
+
+Drives the real Supabase client against a real account and prints one line per
+operation. Read-only by default. `--write` additionally exercises every write
+path on throwaway resources in ONE project, then removes them again:
+
+  migration (create table) → insert / select / update / delete rows → RPC-free
+  SQL write → bucket + upload / download / sign / move / delete → auth user
+  create / update / delete → secret set / delete → edge function deploy /
+  invoke / delete → a reversing migration that drops the table.
+
+    python scripts/smoke_supabase.py --token sbp_xxx
+    python scripts/smoke_supabase.py --token sbp_xxx --project-ref abcdefghijklmnopqrst
+    python scripts/smoke_supabase.py --token sbp_xxx --project-ref abcd... --write
+
+Use a scratch project for --write. Nothing here creates, pauses or deletes a
+project. Every throwaway resource is named craftbot_smoke_<timestamp>.
+
+Exit code is 0 when every check passed or was skipped, 1 if any failed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+# Windows consoles default to cp1252 and raise UnicodeEncodeError on the
+# arrows and dashes in provider messages. Force UTF-8 where we can.
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+except (AttributeError, ValueError):  # pragma: no cover - non-reconfigurable stream
+    pass
+
+
+def _reexec_on_craftbot_interpreter() -> None:
+    """Re-run under the interpreter that has CraftBot's dependencies."""
+    if os.environ.get("_CRAFTBOT_REEXEC") == "1":
+        return
+    try:
+        from app.python_runtime import resolve
+    except Exception:  # pragma: no cover - fall through to a normal import error
+        return
+    target = resolve()
+    if not target or Path(target).resolve() == Path(sys.executable).resolve():
+        return
+    os.environ["_CRAFTBOT_REEXEC"] = "1"
+    raise SystemExit(
+        subprocess.call([target, str(Path(__file__).resolve()), *sys.argv[1:]])
+    )
+
+
+_reexec_on_craftbot_interpreter()
+
+PASS, FAIL, SKIP = "PASS", "FAIL", "SKIP"
+
+
+class Results:
+    def __init__(self) -> None:
+        self.rows: List[Tuple[str, str, str]] = []
+
+    def add(self, status: str, name: str, detail: str = "") -> None:
+        icon = {PASS: "  ok  ", FAIL: " FAIL ", SKIP: " skip "}[status]
+        print(f"{icon} {name:42s} {detail}"[:160], flush=True)
+        self.rows.append((status, name, detail))
+
+    @property
+    def failed(self) -> List[Tuple[str, str, str]]:
+        return [r for r in self.rows if r[0] == FAIL]
+
+
+def summarize(raw: Any) -> str:
+    if not isinstance(raw, dict):
+        return str(raw)[:80]
+    if "error" in raw:
+        return f"{raw['error']} {str(raw.get('details') or '')[:90]}"
+    result = raw.get("result")
+    if isinstance(result, dict):
+        for key in ("rows", "users", "lints"):
+            if isinstance(result.get(key), list):
+                return f"{len(result[key])} {key}"
+        return f"keys: {', '.join(list(result)[:5])}"
+    if isinstance(result, list):
+        return f"{len(result)} items"
+    return str(result)[:80]
+
+
+async def check(results: Results, name: str, coro) -> Optional[Dict[str, Any]]:
+    try:
+        raw = await coro
+    except Exception as exc:  # noqa: BLE001 - surfacing any failure is the point
+        results.add(FAIL, name, f"raised {type(exc).__name__}: {exc}")
+        return None
+    if isinstance(raw, dict) and "error" in raw:
+        results.add(FAIL, name, summarize(raw))
+        return None
+    results.add(PASS, name, summarize(raw))
+    return raw
+
+
+def result_of(raw: Optional[Dict[str, Any]]) -> Any:
+    return (raw or {}).get("result")
+
+
+async def run(args: argparse.Namespace) -> int:
+    from craftos_integrations import autoload_integrations, configure
+    from craftos_integrations.providers.supabase import SupabaseProvider
+
+    configure(project_root=REPO_ROOT)
+    autoload_integrations(force=True)
+
+    provider = SupabaseProvider()
+    results = Results()
+
+    print("\n--- connect ---")
+    if args.connected:
+        # The account the user connected in Settings — the token never
+        # appears on the command line or in shell history.
+        from craftos_integrations.core.storage import FileCredentialStore
+        from craftos_integrations.core.system import IntegrationSystem
+        from craftos_integrations.providers import default_providers
+
+        system = IntegrationSystem(
+            store=FileCredentialStore(), providers=default_providers()
+        )
+        accounts = system.list_accounts("supabase")
+        if not accounts:
+            print("\nNo Supabase account connected in CraftBot.")
+            return 1
+        client = system.client_for("supabase", accounts[0].identity)
+        results.add(PASS, "connected account", accounts[0].identity)
+        ok, message, _ = provider.verify_token(
+            {"access_token": client._load().access_token}
+        )
+        results.add(PASS if ok else FAIL, "verify_token", message)
+    else:
+        if not args.token:
+            print("Pass --token or --connected.")
+            return 1
+        ok, message, credential = provider.verify_token({"access_token": args.token})
+        if not ok or credential is None:
+            results.add(FAIL, "verify_token", message)
+            print(f"\nCannot continue: {message}")
+            return 1
+        results.add(PASS, "verify_token", message)
+        print(f"       identity={provider.identity_of(credential)}")
+        client = provider.build_client(credential, lambda _: None)
+
+    # ── account level ────────────────────────────────────────────────
+    print("\n--- account ---")
+    orgs = await check(results, "list_organizations", client.list_organizations())
+    projects = await check(results, "list_projects", client.list_projects())
+    # Some tokens list no organizations even though their projects belong
+    # to one — fall back to the projects' organization.
+    slugs = [o.get("slug") for o in (result_of(orgs) or [])] or [
+        p.get("organization_slug") for p in (result_of(projects) or [])
+    ]
+    if slugs and slugs[0]:
+        await check(results, "list_organization_members",
+                    client.list_organization_members(slugs[0]))
+        await check(results, "list_regions", client.list_regions(slugs[0]))
+    else:
+        results.add(SKIP, "list_organization_members", "no organization visible")
+
+    ref = args.project_ref
+    if not ref:
+        active = [
+            p for p in (result_of(projects) or [])
+            if str(p.get("status", "")).startswith("ACTIVE")
+        ]
+        ref = active[0]["ref"] if active else ""
+    if not ref:
+        print("\nNo active project to test against — pass --project-ref.")
+        return 1 if results.failed else 0
+    print(f"       project={ref}")
+
+    # ── project reads ────────────────────────────────────────────────
+    print("\n--- project reads ---")
+    await check(results, "get_project", client.get_project(ref))
+    await check(results, "get_project_health", client.get_project_health(project_ref=ref))
+    await check(results, "get_project_keys", client.get_project_keys(ref))
+    for service in ("auth", "postgrest", "realtime", "storage", "postgres"):
+        await check(
+            results, f"get_service_config[{service}]",
+            client.get_service_config(service, project_ref=ref),
+        )
+    await check(results, "run_sql_readonly", client.run_sql_readonly(
+        "select $1::text as echo, now() as at", parameters=["hi"], project_ref=ref))
+    tables = await check(results, "list_tables", client.list_tables(project_ref=ref))
+    table_rows = result_of(tables) or []
+    if table_rows:
+        first = table_rows[0]
+        await check(results, "describe_table", client.describe_table(
+            first["name"], schema=first["schema"], project_ref=ref))
+    else:
+        results.add(SKIP, "describe_table", "no tables in public")
+    await check(results, "list_extensions", client.list_extensions(project_ref=ref))
+    await check(results, "generate_typescript_types",
+                client.generate_typescript_types(project_ref=ref))
+    await check(results, "list_backups", client.list_backups(project_ref=ref))
+    await check(results, "list_migrations", client.list_migrations(project_ref=ref))
+    await check(results, "list_buckets", client.list_buckets(project_ref=ref))
+    await check(results, "list_users", client.list_users(per_page=5, project_ref=ref))
+    await check(results, "list_functions", client.list_functions(project_ref=ref))
+    await check(results, "list_secrets", client.list_secrets(project_ref=ref))
+    await check(results, "list_branches", client.list_branches(project_ref=ref))
+    for source in ("api", "postgres", "auth"):
+        await check(results, f"get_logs[{source}]",
+                    client.get_logs(source=source, limit=5, project_ref=ref))
+    await check(results, "get_security_advisors", client.get_security_advisors(project_ref=ref))
+    await check(results, "get_performance_advisors",
+                client.get_performance_advisors(project_ref=ref))
+    await check(results, "get_api_usage", client.get_api_usage(project_ref=ref))
+
+    if args.write:
+        await run_writes(client, ref, results)
+
+    # ── summary ──────────────────────────────────────────────────────
+    passed = sum(1 for r in results.rows if r[0] == PASS)
+    skipped = sum(1 for r in results.rows if r[0] == SKIP)
+    print("\n" + "=" * 68)
+    print(f"{passed} passed, {len(results.failed)} failed, {skipped} skipped")
+    if results.failed:
+        print("\nFailures:")
+        for _, name, detail in results.failed:
+            print(f"  - {name}: {detail}")
+        print(
+            "\nBranch calls 4xx on projects without branching (paid plans) — "
+            "expected there. A 403 elsewhere means the account's org role is "
+            "read-only."
+        )
+        return 1
+    print("\nEvery call the API was asked to accept, it accepted.")
+    return 0
+
+
+async def run_writes(client: Any, ref: str, results: Results) -> None:
+    stamp = time.strftime("%Y%m%d%H%M%S")
+    name = f"craftbot_smoke_{stamp}"
+
+    # ── migrations + rows ────────────────────────────────────────────
+    print("\n--- write: schema + rows ---")
+    migration = await check(results, "apply_migration", client.apply_migration(
+        f"create table public.{name} (id bigint generated always as identity "
+        f"primary key, label text not null, n int default 0);",
+        name=f"create_{name}",
+        rollback=f"drop table if exists public.{name};",
+        project_ref=ref,
+    ))
+    if migration is not None:
+        await check(results, "insert_rows", client.insert_rows(
+            name, [{"label": "a"}, {"label": "b"}], project_ref=ref))
+        await check(results, "select_rows", client.select_rows(
+            name, order="id.asc", count=True, project_ref=ref))
+        await check(results, "update_rows", client.update_rows(
+            name, {"n": 5}, {"label": "eq.a"}, project_ref=ref))
+        await check(results, "delete_rows", client.delete_rows(
+            name, {"label": "eq.b"}, project_ref=ref))
+        await check(results, "run_sql (write)", client.run_sql(
+            f"insert into public.{name} (label) values ($1) returning id",
+            parameters=["c"], project_ref=ref))
+    else:
+        for step in ("insert_rows", "select_rows", "update_rows", "delete_rows",
+                     "run_sql (write)"):
+            results.add(SKIP, step, "table was not created")
+
+    # ── storage ──────────────────────────────────────────────────────
+    print("\n--- write: storage ---")
+    bucket = name.replace("_", "-")
+    made = await check(results, "create_bucket", client.create_bucket(bucket, project_ref=ref))
+    if made is not None:
+        await check(results, "update_bucket", client.update_bucket(
+            bucket, file_size_limit=1048576, project_ref=ref))
+        with tempfile.TemporaryDirectory() as tmp:
+            src = os.path.join(tmp, "hello.txt")
+            with open(src, "w", encoding="utf-8") as f:
+                f.write("hello from craftbot")
+            await check(results, "upload_file", client.upload_file(
+                bucket, "dir/hello.txt", src, project_ref=ref))
+            await check(results, "list_files", client.list_files(
+                bucket, prefix="dir", project_ref=ref))
+            dst = os.path.join(tmp, "back.txt")
+            got = await check(results, "download_file", client.download_file(
+                bucket, "dir/hello.txt", dst, project_ref=ref))
+            if got is not None:
+                with open(dst, encoding="utf-8") as f:
+                    same = f.read() == "hello from craftbot"
+                results.add(PASS if same else FAIL, "download round-trip",
+                            "content matches" if same else "content differs")
+        await check(results, "create_signed_url", client.create_signed_url(
+            bucket, "dir/hello.txt", expires_in=60, project_ref=ref))
+        await check(results, "copy_file", client.copy_file(
+            bucket, "dir/hello.txt", "dir/copy.txt", project_ref=ref))
+        await check(results, "move_file", client.move_file(
+            bucket, "dir/copy.txt", "dir/moved.txt", project_ref=ref))
+        await check(results, "delete_files", client.delete_files(
+            bucket, ["dir/moved.txt"], project_ref=ref))
+        await check(results, "empty_bucket", client.empty_bucket(bucket, project_ref=ref))
+        await check(results, "delete_bucket", client.delete_bucket(bucket, project_ref=ref))
+
+    # ── auth users ───────────────────────────────────────────────────
+    print("\n--- write: auth users ---")
+    user = await check(results, "create_user", client.create_user(
+        email=f"{name}@example.com", password=f"Smoke-{stamp}-pw!",
+        email_confirm=True, project_ref=ref))
+    user_id = (result_of(user) or {}).get("id") if user else None
+    if user_id:
+        await check(results, "get_user", client.get_user(user_id, project_ref=ref))
+        await check(results, "update_user", client.update_user(
+            user_id, user_metadata={"smoke": True}, project_ref=ref))
+        await check(results, "generate_auth_link", client.generate_auth_link(
+            "magiclink", f"{name}@example.com", project_ref=ref))
+        await check(results, "delete_user", client.delete_user(user_id, project_ref=ref))
+    else:
+        for step in ("get_user", "update_user", "generate_auth_link", "delete_user"):
+            results.add(SKIP, step, "user was not created")
+
+    # ── secrets + edge function ──────────────────────────────────────
+    print("\n--- write: secrets + edge function ---")
+    secret = f"CRAFTBOT_SMOKE_{stamp}"
+    await check(results, "set_secrets", client.set_secrets({secret: "ok"}, project_ref=ref))
+    slug = f"craftbot-smoke-{stamp}"
+    deployed = await check(results, "deploy_function", client.deploy_function(
+        slug,
+        files={"index.ts": (
+            "Deno.serve(async (req) => new Response(JSON.stringify({ "
+            f"secret: Deno.env.get('{secret}') }}), "
+            "{ headers: { 'Content-Type': 'application/json' } }))"
+        )},
+        verify_jwt=False,
+        project_ref=ref,
+    ))
+    if deployed is not None:
+        await check(results, "get_function", client.get_function(slug, project_ref=ref))
+        await check(results, "update_function", client.update_function(
+            slug, name="CraftBot smoke", project_ref=ref))
+        # Freshly deployed functions can take a few seconds to route.
+        await asyncio.sleep(5)
+        await check(results, "invoke_function", client.invoke_function(
+            slug, body={}, project_ref=ref))
+        await check(results, "delete_function", client.delete_function(slug, project_ref=ref))
+    await check(results, "delete_secrets", client.delete_secrets([secret], project_ref=ref))
+
+    # ── cleanup: a reversing migration (rollback is branch-only) ─────
+    print("\n--- write: cleanup ---")
+    if migration is not None:
+        await check(results, "apply_migration (drop)", client.apply_migration(
+            f"drop table if exists public.{name};",
+            name=f"drop_{name}",
+            project_ref=ref,
+        ))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--token", default="", help="Supabase personal access token (sbp_…)")
+    parser.add_argument(
+        "--connected", action="store_true",
+        help="use the Supabase account connected in CraftBot instead of --token",
+    )
+    parser.add_argument("--project-ref", default="", help="project to test (default: first active)")
+    parser.add_argument(
+        "--write",
+        action="store_true",
+        help="also exercise every write path on throwaway resources, then clean up",
+    )
+    return asyncio.run(run(parser.parse_args()))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tests/integrations/test_provider_listeners.py b/tests/integrations/test_provider_listeners.py
index 8d7fe5145..ad53843d6 100644
--- a/tests/integrations/test_provider_listeners.py
+++ b/tests/integrations/test_provider_listeners.py
@@ -506,8 +506,8 @@ async def emit(event):  # no-op
         pass
 
     providers = default_providers()
-    # 11 full ports + 5 wave-1 + 6 wave-2 + 2 wave-3 bridges
-    assert len(providers) == 24
+    # 12 full ports + 5 wave-1 + 6 wave-2 + 2 wave-3 bridges
+    assert len(providers) == 25
     with_listeners = set()
     for provider in providers:
         listener = provider.make_listener(object(), None, emit)
diff --git a/tests/integrations/test_supabase_conformance.py b/tests/integrations/test_supabase_conformance.py
new file mode 100644
index 000000000..ed7add176
--- /dev/null
+++ b/tests/integrations/test_supabase_conformance.py
@@ -0,0 +1,716 @@
+"""Supabase provider conformance + identity/verify/client-behaviour tests.
+
+No network: every HTTP call is monkeypatched. What's real is conformance,
+identity composition, the wrong-key rejections, the auth_type flip, and
+the client rules that protect the user — read-only mode, filter-less
+writes refused, secret values never surfaced, the right key chosen and
+sent in the right header.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List
+
+import pytest
+
+import craftos_integrations.providers.supabase.client as client_mod
+import craftos_integrations.providers.supabase.provider as provider_mod
+from craftos_integrations.config import ConfigStore
+from craftos_integrations.providers.supabase import SupabaseProvider
+from craftos_integrations.providers.supabase.client import (
+    SupabaseClient,
+    SupabaseConfig,
+)
+
+from .conformance import ProviderConformance
+
+# Realistic SHAPES, fake values — asdict(SupabaseCredential) as verify_token
+# (PAT) and run_login (OAuth) build them.
+PAT_CRED = {
+    "access_token": "sbp_FAKE-test-token-not-a-real-secret",
+    "auth_kind": "token",
+    "token_id": "3f1c9a0b7d2e4f60",
+    "refresh_token": "",
+    "token_expiry": 0.0,
+    "user_id": "8C2B6A1E-0000-4000-8000-000000000001",
+    "email": "Dev@Acme.com",
+    "username": "dev",
+    "org_slug": "",
+    "org_name": "",
+}
+OAUTH_CRED = {
+    "access_token": "sbp_oauth_fake",
+    "auth_kind": "oauth",
+    "refresh_token": "refresh_fake",
+    "token_expiry": 9999999999.0,
+    "user_id": "",
+    "email": "",
+    "username": "",
+    "org_slug": "Acme-Inc",
+    "org_name": "Acme Inc",
+}
+
+
+class TestSupabaseConformance(ProviderConformance):
+    provider = SupabaseProvider()
+    credential_fixtures = [
+        PAT_CRED,  # personal access token, post-verify shape
+        OAUTH_CRED,  # OAuth grant scoped to one org
+        {"access_token": "sbp_x", "email": "Only@Email.com"},  # no gotrue id
+        {"access_token": "sbp_x", "token_id": "ABCDEF0123456789"},  # profile 403
+        {},  # junk — must not raise
+    ]
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+# ── identity ─────────────────────────────────────────────────────────
+
+
+def test_pat_identity_is_the_user():
+    assert (
+        SupabaseProvider().identity_of(PAT_CRED)
+        == "user:8c2b6a1e-0000-4000-8000-000000000001"
+    )
+
+
+def test_oauth_identity_is_the_org():
+    assert SupabaseProvider().identity_of(OAUTH_CRED) == "org:acme-inc"
+
+
+def test_identity_falls_back_to_email_then_none():
+    provider = SupabaseProvider()
+    assert provider.identity_of({"email": "A@B.com"}) == "user:a@b.com"
+    assert provider.identity_of({}) is None
+    assert provider.identity_of({"access_token": "sbp_x"}) is None
+    assert provider.identity_of([]) is None  # type: ignore[arg-type]
+    assert provider.identity_of({"user_id": {"nested": 1}}) is None
+
+
+def test_two_oauth_orgs_are_two_accounts():
+    provider = SupabaseProvider()
+    a = dict(OAUTH_CRED, org_slug="one")
+    b = dict(OAUTH_CRED, org_slug="two")
+    assert provider.identity_of(a) != provider.identity_of(b)
+
+
+# ── auth_type follows configuration ──────────────────────────────────
+
+
+def test_auth_type_is_token_until_oauth_app_configured(monkeypatch):
+    monkeypatch.setattr(ConfigStore, "_oauth", {})
+    monkeypatch.delenv("SUPABASE_SHARED_CLIENT_ID", raising=False)
+    monkeypatch.delenv("SUPABASE_SHARED_CLIENT_SECRET", raising=False)
+    assert SupabaseProvider().auth_type == "token"
+
+    monkeypatch.setattr(
+        ConfigStore,
+        "_oauth",
+        {"SUPABASE_SHARED_CLIENT_ID": "id", "SUPABASE_SHARED_CLIENT_SECRET": "secret"},
+    )
+    assert SupabaseProvider().auth_type == "both"
+
+
+def test_run_login_refuses_cleanly_without_oauth_app(monkeypatch):
+    monkeypatch.setattr(ConfigStore, "_oauth", {})
+    monkeypatch.delenv("SUPABASE_SHARED_CLIENT_ID", raising=False)
+    monkeypatch.delenv("SUPABASE_SHARED_CLIENT_SECRET", raising=False)
+    identity, credential, message = run(SupabaseProvider().run_login())
+    assert identity is None and credential is None
+    assert "personal access token" in message
+
+
+# ── verify_token ─────────────────────────────────────────────────────
+
+
+def _stub_http(monkeypatch, responses: Dict[str, Any]) -> List[str]:
+    calls: List[str] = []
+
+    def fake_request(method, url, **kwargs):
+        calls.append(url)
+        for suffix, payload in responses.items():
+            if url.endswith(suffix):
+                return payload
+        return {"error": "API error: 404", "details": "unexpected"}
+
+    monkeypatch.setattr(provider_mod, "http_request", fake_request)
+    return calls
+
+
+@pytest.mark.parametrize(
+    "token",
+    [
+        "sb_secret_abc123",
+        "sb_publishable_abc123",
+        "eyJhbGciOiJIUzI1NiJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIn0.sig",
+    ],
+)
+def test_verify_rejects_project_keys_without_a_request(monkeypatch, token):
+    calls = _stub_http(monkeypatch, {})
+    ok, message, credential = SupabaseProvider().verify_token({"access_token": token})
+    assert not ok and credential is None
+    assert "personal access token" in message
+    assert calls == []
+
+
+def test_verify_rejects_empty(monkeypatch):
+    calls = _stub_http(monkeypatch, {})
+    ok, message, _ = SupabaseProvider().verify_token({"access_token": "  "})
+    assert not ok and "Missing" in message
+    assert calls == []
+
+
+def test_verify_success_captures_identity(monkeypatch):
+    _stub_http(
+        monkeypatch,
+        {
+            "/v1/profile": {
+                "ok": True,
+                "result": {
+                    "gotrue_id": "abc-123",
+                    "primary_email": "dev@acme.com",
+                    "username": "dev",
+                },
+            },
+            "/v1/organizations": {
+                "ok": True,
+                "result": [{"slug": "acme", "name": "Acme"}],
+            },
+        },
+    )
+    ok, message, credential = SupabaseProvider().verify_token(
+        {"access_token": "sbp_good"}
+    )
+    assert ok
+    assert credential["auth_kind"] == "token"
+    assert credential["user_id"] == "abc-123"
+    assert SupabaseProvider().identity_of(credential) == "user:abc-123"
+    assert "dev@acme.com" in message and "Acme" in message
+
+
+def test_verify_succeeds_when_profile_is_forbidden(monkeypatch):
+    """Real behaviour, seen live 2026-10-05: /v1/profile answers 403 to a
+    valid personal access token. That must not fail the connect."""
+    _stub_http(
+        monkeypatch,
+        {
+            "/v1/profile": {"error": "API error: 403", "details": "forbidden"},
+            "/v1/organizations": {
+                "ok": True,
+                "result": [{"slug": "acme", "name": "Acme"}],
+            },
+        },
+    )
+    ok, message, credential = SupabaseProvider().verify_token(
+        {"access_token": "sbp_good"}
+    )
+    assert ok, message
+    assert credential["user_id"] == ""
+    assert credential["token_id"] == provider_mod.token_fingerprint("sbp_good")
+    identity = SupabaseProvider().identity_of(credential)
+    assert identity == f"token:{credential['token_id']}"
+    assert "sbp_good" not in identity
+    assert "Acme" in message
+
+
+def test_token_fingerprint_is_stable_and_distinct():
+    fp = provider_mod.token_fingerprint
+    assert fp("sbp_a") == fp("sbp_a")
+    assert fp("sbp_a") != fp("sbp_b")
+    assert len(fp("sbp_a")) == 16
+
+
+def test_verify_reports_revoked_token(monkeypatch):
+    _stub_http(
+        monkeypatch, {"/v1/organizations": {"error": "API error: 401", "details": ""}}
+    )
+    ok, message, credential = SupabaseProvider().verify_token(
+        {"access_token": "sbp_revoked"}
+    )
+    assert not ok and credential is None
+    assert "401" in message and "revoked" in message
+
+
+def test_verify_distinguishes_forbidden_from_invalid(monkeypatch):
+    _stub_http(
+        monkeypatch,
+        {"/v1/organizations": {"error": "API error: 403", "details": "no access"}},
+    )
+    ok, message, _ = SupabaseProvider().verify_token({"access_token": "sbp_x"})
+    assert not ok
+    assert "403" in message and "accepted the token" in message
+
+
+# ── client behaviour ─────────────────────────────────────────────────
+
+
+def _client(monkeypatch, **config) -> SupabaseClient:
+    client = SupabaseClient()
+    client.bind_credential(dict(PAT_CRED), lambda c: None)
+    cfg = SupabaseConfig(**{"default_project_ref": "abcdefghijklmnopqrst", **config})
+    monkeypatch.setattr(client, "_config", lambda: cfg)
+    return client
+
+
+def test_read_only_mode_blocks_writes_before_any_request(monkeypatch):
+    client = _client(monkeypatch, read_only=True)
+
+    async def boom(*a, **k):
+        raise AssertionError("no request may be sent in read-only mode")
+
+    monkeypatch.setattr(client, "_mgmt", boom)
+    monkeypatch.setattr(client, "_data", boom)
+    for call in (
+        lambda: client.run_sql("drop table x"),
+        lambda: client.apply_migration("create table x()"),
+        lambda: client.insert_rows("t", [{"a": 1}]),
+        lambda: client.delete_function("f"),
+        lambda: client.delete_project("abcdefghijklmnopqrst"),
+    ):
+        with pytest.raises(client_mod.ReadOnlyModeError):
+            run(call())
+
+
+def test_read_only_mode_allows_readonly_sql(monkeypatch):
+    client = _client(monkeypatch, read_only=True)
+    sent = {}
+
+    async def fake_mgmt(method, path, **kwargs):
+        sent["path"] = path
+        return {"ok": True, "result": [{"n": 1}]}
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    result = run(client.run_sql_readonly("select 1 as n"))
+    assert result["ok"]
+    assert sent["path"].endswith("/database/query/read-only")
+
+
+def test_row_writes_refuse_empty_filters(monkeypatch):
+    client = _client(monkeypatch)
+    assert "filters are required" in run(client.update_rows("t", {"a": 1}, {}))["error"]
+    assert "filters are required" in run(client.delete_rows("t", {}))["error"]
+
+
+def test_delete_project_never_uses_default_ref(monkeypatch):
+    client = _client(monkeypatch)
+    assert "required" in run(client.delete_project(""))["error"]
+
+
+def test_filter_params_support_repeats_and_logic_keys():
+    params = SupabaseClient._filter_params(
+        {"age": ["gte.18", "lt.65"], "or": "(a.eq.1,b.eq.2)"}
+    )
+    assert params == [("age", "gte.18"), ("age", "lt.65"), ("or", "(a.eq.1,b.eq.2)")]
+
+
+def test_list_secrets_strips_values(monkeypatch):
+    client = _client(monkeypatch)
+
+    async def fake_mgmt(method, path, **kwargs):
+        return {
+            "ok": True,
+            "result": [{"name": "STRIPE_KEY", "value": "sk_live_x", "updated_at": "t"}],
+        }
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    result = run(client.list_secrets())
+    assert result["result"] == [{"name": "STRIPE_KEY", "updated_at": "t"}]
+    assert "sk_live_x" not in repr(result)
+
+
+def test_service_config_redacts_secrets(monkeypatch):
+    client = _client(monkeypatch)
+
+    async def fake_mgmt(method, path, **kwargs):
+        return {"ok": True, "result": {"db_schema": "public", "jwt_secret": "s3cret"}}
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    result = run(client.get_service_config("postgrest"))
+    assert result["result"]["jwt_secret"] == "***redacted***"
+    assert "s3cret" not in repr(result)
+
+
+def _fake_keys(api_keys):
+    async def fake_mgmt(method, path, **kwargs):
+        assert path.endswith("/api-keys") and kwargs["params"] == {"reveal": "true"}
+        return {"ok": True, "result": api_keys}
+
+    return fake_mgmt
+
+
+def test_keys_prefer_new_secret_and_never_leak(monkeypatch):
+    client = _client(monkeypatch)
+    monkeypatch.setattr(
+        client,
+        "_mgmt",
+        _fake_keys(
+            [
+                {"type": "legacy", "name": "anon", "api_key": "eyJa.nn.on"},
+                {"type": "legacy", "name": "service_role", "api_key": "eyJs.rv.ce"},
+                {"type": "publishable", "name": "default", "api_key": "sb_publishable_p"},
+                {"type": "secret", "name": "default", "api_key": "sb_secret_s"},
+            ]
+        ),
+    )
+    keys = run(client._keys_for("abcdefghijklmnopqrst"))
+    assert keys["secret"] == "sb_secret_s"
+    assert keys["publishable"] == "sb_publishable_p"
+    assert keys["jwt"] == "eyJs.rv.ce"
+
+    public = run(client.get_project_keys())
+    assert public["result"]["publishable_key"] == "sb_publishable_p"
+    assert public["result"]["url"] == "https://abcdefghijklmnopqrst.supabase.co"
+    assert "sb_secret_s" not in repr(public) and "eyJs" not in repr(public)
+
+
+def test_keys_fall_back_to_legacy_service_role(monkeypatch):
+    client = _client(monkeypatch)
+    monkeypatch.setattr(
+        client,
+        "_mgmt",
+        _fake_keys(
+            [
+                {"type": "legacy", "name": "anon", "api_key": "eyJa.nn.on"},
+                {"type": "legacy", "name": "service_role", "api_key": "eyJs.rv.ce"},
+            ]
+        ),
+    )
+    keys = run(client._keys_for("abcdefghijklmnopqrst"))
+    assert keys["secret"] == "eyJs.rv.ce"
+    assert keys["publishable"] == "eyJa.nn.on"
+
+
+class _Resp:
+    def __init__(self, status=200, body=b"[]", headers=None):
+        self.status_code = status
+        self.content = body
+        self.text = body.decode()
+        self.headers = headers or {}
+
+    def json(self):
+        import json
+
+        return json.loads(self.content)
+
+
+def _capture_data_requests(monkeypatch, client, keys, responses=None):
+    client._project_keys["abcdefghijklmnopqrst"] = keys
+    sent: List[Dict[str, Any]] = []
+    queue = list(responses or [])
+
+    def fake_request(method, url, **kwargs):
+        sent.append({"method": method, "url": url, **kwargs})
+        return queue.pop(0) if queue else _Resp()
+
+    monkeypatch.setattr(client_mod.httpx, "request", fake_request)
+    return sent
+
+
+def test_new_secret_key_goes_in_apikey_header_only(monkeypatch):
+    client = _client(monkeypatch)
+    sent = _capture_data_requests(
+        monkeypatch, client, {"secret": "sb_secret_s", "publishable": None, "jwt": None}
+    )
+    run(client.select_rows("orders", filters={"status": "eq.open"}))
+    headers = sent[0]["headers"]
+    assert headers["apikey"] == "sb_secret_s"
+    assert "Authorization" not in headers
+    assert sent[0]["url"] == "https://abcdefghijklmnopqrst.supabase.co/rest/v1/orders"
+    assert ("status", "eq.open") in sent[0]["params"]
+
+
+def test_legacy_jwt_also_goes_in_authorization(monkeypatch):
+    client = _client(monkeypatch)
+    sent = _capture_data_requests(
+        monkeypatch, client, {"secret": "eyJs.rv.ce", "publishable": None, "jwt": "eyJs.rv.ce"}
+    )
+    run(client.list_buckets())
+    assert sent[0]["headers"]["Authorization"] == "Bearer eyJs.rv.ce"
+
+
+def test_select_rows_reports_total_and_next_offset(monkeypatch):
+    client = _client(monkeypatch)
+    _capture_data_requests(
+        monkeypatch,
+        client,
+        {"secret": "sb_secret_s", "publishable": None, "jwt": None},
+        [_Resp(206, b'[{"id":1},{"id":2}]', {"content-range": "0-1/57"})],
+    )
+    result = run(client.select_rows("orders", limit=2, count=True))
+    assert result["result"]["total"] == 57
+    assert result["result"]["next_offset"] == 2
+
+
+def test_data_plane_retries_once_with_fresh_keys_on_401(monkeypatch):
+    client = _client(monkeypatch)
+    client._project_keys["abcdefghijklmnopqrst"] = {
+        "secret": "sb_secret_stale", "publishable": None, "jwt": None,
+    }
+    monkeypatch.setattr(
+        client, "_mgmt",
+        _fake_keys([{"type": "secret", "name": "default", "api_key": "sb_secret_new"}]),
+    )
+    seen: List[str] = []
+
+    def fake_request(method, url, **kwargs):
+        seen.append(kwargs["headers"]["apikey"])
+        return _Resp(401, b"{}") if len(seen) == 1 else _Resp(200, b"[]")
+
+    monkeypatch.setattr(client_mod.httpx, "request", fake_request)
+    result = run(client.list_buckets())
+    assert result["ok"]
+    assert seen == ["sb_secret_stale", "sb_secret_new"]
+
+
+def test_deploy_function_builds_multipart(monkeypatch):
+    client = _client(monkeypatch)
+    sent = {}
+
+    async def fake_mgmt(method, path, **kwargs):
+        sent.update(kwargs, method=method, path=path)
+        return {"ok": True, "result": {"slug": "hello", "version": 1}}
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    result = run(
+        client.deploy_function(
+            "hello", files={"index.ts": "Deno.serve(() => new Response('hi'))"}
+        )
+    )
+    assert result["ok"]
+    assert sent["path"].endswith("/functions/deploy")
+    assert sent["params"] == {"slug": "hello"}
+    assert '"entrypoint_path": "index.ts"' in sent["data"]["metadata"]
+    assert sent["files"][0][0] == "file" and sent["files"][0][1][0] == "index.ts"
+
+
+def test_deploy_function_requires_entrypoint_in_files(monkeypatch):
+    client = _client(monkeypatch)
+    result = run(client.deploy_function("hello", files={"main.ts": "x"}))
+    assert "Entrypoint" in result["error"]
+
+
+def test_set_secrets_rejects_reserved_names(monkeypatch):
+    client = _client(monkeypatch)
+    result = run(client.set_secrets({"SUPABASE_URL": "x"}))
+    assert "reserved" in result["error"]
+
+
+def test_missing_project_ref_is_actionable(monkeypatch):
+    client = SupabaseClient()
+    client.bind_credential(dict(PAT_CRED), lambda c: None)
+    monkeypatch.setattr(client, "_config", lambda: SupabaseConfig())
+    with pytest.raises(ValueError, match="list_supabase_projects"):
+        run(client.list_tables())
+
+
+# ── operations wiring ────────────────────────────────────────────────
+
+
+def test_operation_count():
+    names = {op.name for op in SupabaseProvider().operations()}
+    assert len(names) == 71
+
+
+def test_operation_inputs_match_client_signatures():
+    """client_op passes input keys straight through as kwargs — a schema
+    key the method doesn't accept is a guaranteed runtime TypeError."""
+    import inspect
+
+    for op in SupabaseProvider().operations():
+        cells = dict(zip(op.fn.__code__.co_freevars, op.fn.__closure__ or ()))
+        method_name = cells["method"].cell_contents
+        method = getattr(SupabaseClient, method_name)
+        params = inspect.signature(method).parameters
+        accepted = {n for n in params if n != "self"}
+        extra = set(op.input_schema) - accepted
+        assert not extra, f"{op.name} → {method_name} rejects {sorted(extra)}"
+        required = {
+            n
+            for n, p in params.items()
+            if n != "self"
+            and p.default is inspect.Parameter.empty
+            and p.kind in (p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY)
+        }
+        missing = required - set(op.input_schema)
+        assert not missing, f"{op.name} can never supply {sorted(missing)}"
+
+
+# ── live findings (2026-10-05) ───────────────────────────────────────
+
+
+def test_verify_describes_reach_by_projects_when_orgs_are_empty(monkeypatch):
+    """Seen live: a valid token listed zero organizations but one project."""
+    _stub_http(
+        monkeypatch,
+        {
+            "/v1/organizations": {"ok": True, "result": []},
+            "/v1/profile": {"error": "API error: 403", "details": ""},
+            "/v1/projects": {"ok": True, "result": [{"name": "Test", "ref": "x"}]},
+        },
+    )
+    ok, message, _ = SupabaseProvider().verify_token({"access_token": "sbp_good"})
+    assert ok
+    assert "1 project(s): Test" in message
+    assert "no organizations" not in message
+
+
+def test_logs_error_inside_200_body_is_a_failure(monkeypatch):
+    """The analytics endpoint answers 200 with {"error": ...} on a failed
+    query — that must not reach the agent as success."""
+    client = _client(monkeypatch)
+
+    async def fake_mgmt(method, path, **kwargs):
+        return {"ok": True, "result": {"error": 'Table "postgres_logs" does not exist.'}}
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    result = run(client.get_logs(source="postgres"))
+    assert "error" in result
+    assert "does not exist" in result["details"]
+
+
+def test_logs_query_targets_unified_logs_table(monkeypatch):
+    client = _client(monkeypatch)
+    sent = {}
+
+    async def fake_mgmt(method, path, **kwargs):
+        sent.update(kwargs["params"])
+        return {"ok": True, "result": {"result": [{"event_message": "hi"}]}}
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    result = run(client.get_logs(source="postgres", search="it's"))
+    assert result == {"ok": True, "result": [{"event_message": "hi"}]}
+    assert "from logs where source_name = 'postgres_logs'" in sent["sql"]
+    assert r"match(event_message, '(?i)it\'s')" in sent["sql"]
+
+
+# ── second round of live findings ────────────────────────────────────
+
+
+def test_schema_change_via_run_sql_is_recorded_as_migration(monkeypatch):
+    client = _client(monkeypatch)
+    sent = {}
+
+    async def fake_mgmt(method, path, **kwargs):
+        sent["path"] = path
+        sent["body"] = kwargs.get("json_body")
+        return {"ok": True, "result": {}}
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    result = run(client.run_sql(
+        "create table public.e2e_tasks (id bigint primary key);"
+        " alter table public.e2e_tasks enable row level security;"
+    ))
+    assert sent["path"].endswith("/database/migrations")
+    assert sent["body"]["name"] == "create_table_e2e_tasks"
+    assert result["result"]["applied_as_migration"] == "create_table_e2e_tasks"
+
+
+def test_data_changes_and_parameterised_sql_stay_on_query(monkeypatch):
+    client = _client(monkeypatch)
+    paths = []
+
+    async def fake_mgmt(method, path, **kwargs):
+        paths.append(path)
+        return {"ok": True, "result": []}
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    run(client.run_sql("update public.t set done = true where id = 2"))
+    run(client.run_sql("create table x (a int)", parameters=[1]))
+    assert all(p.endswith("/database/query") for p in paths)
+
+
+@pytest.mark.parametrize("sql, expected", [
+    ("create table public.e2e_tasks (id int)", "create_table_e2e_tasks"),
+    ('create policy "read own" on public.t for select using (true)', "create_policy_read_own"),
+    ("-- note\ncreate index if not exists idx_a on t(a)", "create_index_idx_a"),
+    ("create or replace function f() returns int as $$ begin; return 1; end; $$ language plpgsql",
+     "create_or_replace_function_f"),
+    ("update t set a = 1; drop table if exists public.old_t", "drop_table_old_t"),
+    ("create extension if not exists pg_trgm", "create_extension_pg_trgm"),
+    ("create temp table scratch (a int)", None),
+    ("insert into t values (1)", None),
+    ("select 1", None),
+])
+def test_ddl_migration_name(sql, expected):
+    assert client_mod.ddl_migration_name(sql) == expected
+
+
+def test_list_organizations_recovers_from_projects_when_empty(monkeypatch):
+    client = _client(monkeypatch)
+
+    async def fake_mgmt(method, path, **kwargs):
+        if path == "organizations":
+            return {"ok": True, "result": []}
+        return {"ok": True, "result": [
+            {"name": "Test", "organization_slug": "agrnyy"},
+            {"name": "Prod", "organization_slug": "agrnyy"},
+        ]}
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    orgs = run(client.list_organizations())["result"]
+    assert [o["slug"] for o in orgs] == ["agrnyy"]
+    assert orgs[0]["projects"] == ["Test", "Prod"]
+
+
+def test_members_403_explains_itself(monkeypatch):
+    client = _client(monkeypatch)
+
+    async def fake_mgmt(method, path, **kwargs):
+        return {"error": "API error: 403", "details": '{"message":"Forbidden"}'}
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    result = run(client.list_organization_members("agrnyy"))
+    assert "403" in result["error"] and "Project operations are unaffected" in result["details"]
+
+
+def test_logs_backend_error_is_retried_then_explained(monkeypatch):
+    client = _client(monkeypatch)
+    calls = []
+
+    async def fake_mgmt(method, path, **kwargs):
+        calls.append(path)
+        return {"ok": True, "result": {"error": "Backend error! Retry your query."}}
+
+    async def no_sleep(_):
+        return None
+
+    monkeypatch.setattr(client, "_mgmt", fake_mgmt)
+    monkeypatch.setattr(client_mod.asyncio, "sleep", no_sleep)
+    result = run(client.get_logs(source="api"))
+    assert len(calls) == 2
+    assert "logs service is failing" in result["details"]
+
+
+def test_default_alias_prefers_what_the_user_knows():
+    provider = SupabaseProvider()
+    assert provider.default_alias({"email": "dev@acme.com", "display_name": "Test"}) == "dev@acme.com"
+    assert provider.default_alias({"org_name": "Acme", "display_name": "Test"}) == "Acme"
+    assert provider.default_alias({"display_name": "Test, Prod +1"}) == "Test, Prod +1"
+    assert provider.default_alias({}) is None
+
+
+def test_verify_sets_project_display_name(monkeypatch):
+    _stub_http(monkeypatch, {
+        "/v1/organizations": {"ok": True, "result": []},
+        "/v1/profile": {"error": "API error: 403", "details": ""},
+        "/v1/projects": {"ok": True, "result": [
+            {"name": "Test"}, {"name": "Prod"}, {"name": "Stage"}]},
+    })
+    ok, _, credential = SupabaseProvider().verify_token({"access_token": "sbp_good"})
+    assert ok and credential["display_name"] == "Test, Prod +1"
+
+
+def test_management_403_explains_itself(monkeypatch):
+    client = _client(monkeypatch)
+
+    async def fake_arequest(method, url, **kwargs):
+        return {"error": "API error: 403", "details": '{"message":"Forbidden"}'}
+
+    monkeypatch.setattr(client_mod, "arequest", fake_arequest)
+    result = run(client.create_project(name="x", organization_slug="org"))
+    assert result["error"] == "API error: 403"
+    assert "Retrying won't help" in result["details"]
+    assert "organization role" in result["details"]
diff --git a/tests/integrations/test_system.py b/tests/integrations/test_system.py
index 28279d030..63510e182 100644
--- a/tests/integrations/test_system.py
+++ b/tests/integrations/test_system.py
@@ -153,3 +153,59 @@ def test_apply_account_changes_end_to_end(system):
     assert by_id["b@y.com"].is_primary
     assert by_id["a@x.com"].alias == "personal"
     assert run(system.execute("gmail", "whoami", {}))["email"] == "b@y.com"
+
+
+# ── provider-suggested default alias ─────────────────────────────────
+
+
+class NamingProvider(FakeProvider):
+    """A provider whose identity is opaque, suggesting a readable name."""
+
+    def identity_of(self, credential):
+        return credential.get("token_id")
+
+    def default_alias(self, credential):
+        return credential.get("label")
+
+
+def _naming_system(tmp_path):
+    return IntegrationSystem(
+        store=FileCredentialStore(root=tmp_path),
+        providers=[NamingProvider("supa")],
+    )
+
+
+def _alias(sys, pid, identity):
+    return {a.identity: a.alias for a in sys.list_accounts(pid)}[identity]
+
+
+def test_new_account_gets_provider_default_alias(tmp_path):
+    sys = _naming_system(tmp_path)
+    sys.store_credential("supa", "token:abc", {"token_id": "abc", "label": "Test"})
+    assert _alias(sys, "supa", "token:abc") == "Test"
+    # the suggested name resolves like any alias
+    assert sys.resolve("supa", "Test") == "token:abc"
+
+
+def test_default_alias_never_overwrites_a_users_rename(tmp_path):
+    sys = _naming_system(tmp_path)
+    sys.store_credential("supa", "token:abc", {"token_id": "abc", "label": "Test"})
+    sys.set_alias("supa", "token:abc", "work")
+    # re-auth / credential refresh of the same account
+    sys.store_credential("supa", "token:abc", {"token_id": "abc", "label": "Other"})
+    assert _alias(sys, "supa", "token:abc") == "work"
+
+
+def test_taken_default_alias_is_skipped_not_fatal(tmp_path):
+    sys = _naming_system(tmp_path)
+    sys.store_credential("supa", "token:abc", {"token_id": "abc", "label": "Test"})
+    sys.store_credential("supa", "token:def", {"token_id": "def", "label": "Test"})
+    assert _alias(sys, "supa", "token:def") is None
+    assert len(sys.list_accounts("supa")) == 2
+
+
+def test_providers_without_default_alias_are_unchanged(system):
+    assert {a.identity: a.alias for a in system.list_accounts("gmail")} == {
+        "a@x.com": None,
+        "b@y.com": "school",
+    }
diff --git a/tests/test_action_set_catalog.py b/tests/test_action_set_catalog.py
new file mode 100644
index 000000000..b7becb30e
--- /dev/null
+++ b/tests/test_action_set_catalog.py
@@ -0,0 +1,60 @@
+"""Catalog descriptions for action sets with no hand-written description.
+
+The agent chooses which sets to load from this catalog. When every
+integration sub-set read "Custom action set: <name>" the agent loaded only
+the shortlist set and fell back to raw SQL for bucket/secret management
+(seen live testing Supabase, 2026-10-05). These tests pin the contract:
+the shortlist says it is a shortlist, and sub-sets name what is inside.
+"""
+
+from app.action.action_set import describe_set
+
+SETS = {
+    "supabase": ["list_supabase_projects", "run_supabase_sql", "delete_supabase_files"],
+    "supabase_storage": [
+        "list_supabase_buckets",
+        "create_supabase_bucket",
+        "delete_supabase_bucket",
+        "upload_supabase_file",
+        "list_supabase_files",
+        "create_supabase_signed_url",
+    ],
+    "supabase_secrets": ["list_supabase_secrets", "set_supabase_secrets"],
+    "supabase_branches": ["list_supabase_branches", "merge_supabase_branch"],
+    "google_drive": ["list_drive_files"],
+    "my_mcp_server": ["mcp_tool_one", "mcp_tool_two"],
+}
+
+
+def test_shortlist_set_says_it_is_not_everything():
+    text = describe_set("supabase", SETS["supabase"], SETS)
+    assert "shortlist" in text
+    assert "supabase_*" in text
+    assert "(3)" in text
+
+
+def test_sub_set_names_its_nouns_without_the_integration():
+    text = describe_set("supabase_storage", SETS["supabase_storage"], SETS)
+    assert text.startswith("6 actions:")
+    assert "buckets" in text and "files" in text and "signed_url" in text
+    assert "supabase" not in text
+    # singular and plural of one noun appear once
+    assert text.count("bucket") == 1
+
+
+def test_es_plurals_collapse():
+    text = describe_set("supabase_branches", SETS["supabase_branches"], SETS)
+    assert text == "2 actions: branches"
+
+
+def test_set_without_umbrella_still_describes_its_actions():
+    text = describe_set("my_mcp_server", SETS["my_mcp_server"], SETS)
+    assert text.startswith("2 actions:")
+    assert "Custom action set" not in text
+
+
+def test_long_noun_lists_are_capped():
+    many = {"x_big": [f"list_x_thing{i}" for i in range(10)], "x": ["list_x_a"]}
+    text = describe_set("x_big", many["x_big"], many)
+    assert text.endswith(", …")
+    assert text.count(",") == 6

From 077a2c1250583656dc839a6d18372e12116de16c Mon Sep 17 00:00:00 2001
From: CraftBot <craftbot@craftbot.dev>
Date: Tue, 6 Oct 2026 00:40:18 +0900
Subject: [PATCH 2/2] discard action sets umbrella of and describe set function

---
 app/action/action_set.py         | 67 +++++---------------------------
 tests/test_action_set_catalog.py | 60 ----------------------------
 2 files changed, 9 insertions(+), 118 deletions(-)
 delete mode 100644 tests/test_action_set_catalog.py

diff --git a/app/action/action_set.py b/app/action/action_set.py
index ac0745757..67430c067 100644
--- a/app/action/action_set.py
+++ b/app/action/action_set.py
@@ -27,56 +27,6 @@
 }
 
 
-_MAX_NOUNS = 6
-
-
-def _umbrella_of(set_name: str, all_sets: Dict[str, List[str]]) -> Optional[str]:
-    """Longest other set name that prefixes this one (``supabase`` for
-    ``supabase_storage``) — the integration's shortlist set."""
-    best = None
-    for other in all_sets:
-        if other != set_name and set_name.startswith(other + "_"):
-            if best is None or len(other) > len(best):
-                best = other
-    return best
-
-
-def describe_set(
-    set_name: str, actions: List[str], all_sets: Dict[str, List[str]]
-) -> str:
-    """Catalog line for a set with no hand-written description.
-
-    The agent picks sets from this catalog, so the line must say what is
-    inside. Integration sets are named by integration and noun
-    (``supabase_storage``) and their actions by verb + integration + noun
-    (``delete_supabase_bucket``); listing the nouns tells the agent where
-    an action lives without spending tokens on every action name.
-    """
-    sub_sets = sorted(s for s in all_sets if s.startswith(set_name + "_"))
-    if sub_sets:
-        return (
-            f"shortlist of the most-used {set_name} actions ({len(actions)}); "
-            f"not everything — load {set_name}_* sets for the rest"
-        )
-
-    umbrella = _umbrella_of(set_name, all_sets)
-    strip = set(umbrella.split("_")) if umbrella else set()
-    shown_as: Dict[str, str] = {}  # singular key -> display form, in order
-    for action in actions:
-        tokens = [t for t in action.split("_") if t not in strip]
-        noun = "_".join(tokens[1:]) if len(tokens) > 1 else action
-        key = noun[:-2] if noun.endswith(("ches", "shes", "xes", "sses")) else noun.rstrip("s")
-        if not key:
-            continue
-        # Keep first-seen order, but prefer the plural form for display.
-        if key not in shown_as or (noun.endswith("s") and not shown_as[key].endswith("s")):
-            shown_as[key] = noun
-    nouns = list(shown_as.values())
-    shown = ", ".join(nouns[:_MAX_NOUNS])
-    more = ", …" if len(nouns) > _MAX_NOUNS else ""
-    return f"{len(actions)} actions: {shown}{more}"
-
-
 class ActionSetManager:
     """
     Singleton managing action set compilation from the ActionRegistry.
@@ -184,7 +134,7 @@ def list_all_sets(self) -> Dict[str, str]:
         from agent_core import registry_instance, PLATFORM_ALL
 
         current_platform = platform_lib.system().lower()
-        members: Dict[str, List[str]] = {}
+        discovered_sets: Dict[str, str] = {}
 
         # Scan all registered actions to find unique set names
         for action_name, platform_impls in registry_instance._registry.items():
@@ -197,13 +147,14 @@ def list_all_sets(self) -> Dict[str, str]:
 
             action_sets = getattr(impl.metadata, "action_sets", [])
             for set_name in action_sets:
-                members.setdefault(set_name, []).append(action_name)
-
-        return {
-            set_name: DEFAULT_SET_DESCRIPTIONS.get(set_name)
-            or describe_set(set_name, actions, members)
-            for set_name, actions in members.items()
-        }
+                if set_name not in discovered_sets:
+                    # Use default description if known, otherwise generate one
+                    desc = DEFAULT_SET_DESCRIPTIONS.get(
+                        set_name, f"Custom action set: {set_name}"
+                    )
+                    discovered_sets[set_name] = desc
+
+        return discovered_sets
 
     def get_set_description(self, set_name: str) -> Optional[str]:
         """
diff --git a/tests/test_action_set_catalog.py b/tests/test_action_set_catalog.py
deleted file mode 100644
index b7becb30e..000000000
--- a/tests/test_action_set_catalog.py
+++ /dev/null
@@ -1,60 +0,0 @@
-"""Catalog descriptions for action sets with no hand-written description.
-
-The agent chooses which sets to load from this catalog. When every
-integration sub-set read "Custom action set: <name>" the agent loaded only
-the shortlist set and fell back to raw SQL for bucket/secret management
-(seen live testing Supabase, 2026-10-05). These tests pin the contract:
-the shortlist says it is a shortlist, and sub-sets name what is inside.
-"""
-
-from app.action.action_set import describe_set
-
-SETS = {
-    "supabase": ["list_supabase_projects", "run_supabase_sql", "delete_supabase_files"],
-    "supabase_storage": [
-        "list_supabase_buckets",
-        "create_supabase_bucket",
-        "delete_supabase_bucket",
-        "upload_supabase_file",
-        "list_supabase_files",
-        "create_supabase_signed_url",
-    ],
-    "supabase_secrets": ["list_supabase_secrets", "set_supabase_secrets"],
-    "supabase_branches": ["list_supabase_branches", "merge_supabase_branch"],
-    "google_drive": ["list_drive_files"],
-    "my_mcp_server": ["mcp_tool_one", "mcp_tool_two"],
-}
-
-
-def test_shortlist_set_says_it_is_not_everything():
-    text = describe_set("supabase", SETS["supabase"], SETS)
-    assert "shortlist" in text
-    assert "supabase_*" in text
-    assert "(3)" in text
-
-
-def test_sub_set_names_its_nouns_without_the_integration():
-    text = describe_set("supabase_storage", SETS["supabase_storage"], SETS)
-    assert text.startswith("6 actions:")
-    assert "buckets" in text and "files" in text and "signed_url" in text
-    assert "supabase" not in text
-    # singular and plural of one noun appear once
-    assert text.count("bucket") == 1
-
-
-def test_es_plurals_collapse():
-    text = describe_set("supabase_branches", SETS["supabase_branches"], SETS)
-    assert text == "2 actions: branches"
-
-
-def test_set_without_umbrella_still_describes_its_actions():
-    text = describe_set("my_mcp_server", SETS["my_mcp_server"], SETS)
-    assert text.startswith("2 actions:")
-    assert "Custom action set" not in text
-
-
-def test_long_noun_lists_are_capped():
-    many = {"x_big": [f"list_x_thing{i}" for i in range(10)], "x": ["list_x_a"]}
-    text = describe_set("x_big", many["x_big"], many)
-    assert text.endswith(", …")
-    assert text.count(",") == 6