diff --git a/skills/supabase-cli/AGENTS.md b/skills/supabase-cli/AGENTS.md
new file mode 100644
index 0000000..04005ac
--- /dev/null
+++ b/skills/supabase-cli/AGENTS.md
@@ -0,0 +1,52 @@
+# supabase-cli
+
+> **Note:** `CLAUDE.md` is a symlink to this file.
+
+## Overview
+
+Supabase CLI command reference and usage guide. Use this skill when running Supabase CLI commands, managing local development environments, deploying to Supabase projects, working with database migrations, edge functions, branches, secrets, storage, SSO, custom domains, network configuration, or any other Supabase CLI operation.
+
+## Structure
+
+```
+supabase-cli/
+  SKILL.md       # Main skill file - read this first
+  AGENTS.md      # This navigation guide
+  CLAUDE.md      # Symlink to AGENTS.md
+  references/    # Detailed reference files
+```
+
+## Usage
+
+1. Read `SKILL.md` for the main skill instructions
+2. Browse `references/` for detailed documentation on specific topics
+3. Reference files are loaded on-demand - read only what you need
+
+## Reference Categories
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Common Workflows | CRITICAL | `workflows-` |
+| 2 | Decision Guide | HIGH | `decision-` |
+| 3 | Gotchas and Pitfalls | HIGH | `gotchas-` |
+| 4 | Commands Overview | MEDIUM | `commands-` |
+
+Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md`).
+
+## Available References
+
+**Commands Overview** (`commands-`):
+- `references/commands-overview.md`
+
+**Decision Guide** (`decision-`):
+- `references/decision-guide.md`
+
+**Gotchas and Pitfalls** (`gotchas-`):
+- `references/gotchas-pitfalls.md`
+
+**Common Workflows** (`workflows-`):
+- `references/workflows-common.md`
+
+---
+
+*4 reference files across 4 categories*
\ No newline at end of file
diff --git a/skills/supabase-cli/CLAUDE.md b/skills/supabase-cli/CLAUDE.md
new file mode 100644
index 0000000..04005ac
--- /dev/null
+++ b/skills/supabase-cli/CLAUDE.md
@@ -0,0 +1,52 @@
+# supabase-cli
+
+> **Note:** `CLAUDE.md` is a symlink to this file.
+
+## Overview
+
+Supabase CLI command reference and usage guide. Use this skill when running Supabase CLI commands, managing local development environments, deploying to Supabase projects, working with database migrations, edge functions, branches, secrets, storage, SSO, custom domains, network configuration, or any other Supabase CLI operation.
+
+## Structure
+
+```
+supabase-cli/
+  SKILL.md       # Main skill file - read this first
+  AGENTS.md      # This navigation guide
+  CLAUDE.md      # Symlink to AGENTS.md
+  references/    # Detailed reference files
+```
+
+## Usage
+
+1. Read `SKILL.md` for the main skill instructions
+2. Browse `references/` for detailed documentation on specific topics
+3. Reference files are loaded on-demand - read only what you need
+
+## Reference Categories
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Common Workflows | CRITICAL | `workflows-` |
+| 2 | Decision Guide | HIGH | `decision-` |
+| 3 | Gotchas and Pitfalls | HIGH | `gotchas-` |
+| 4 | Commands Overview | MEDIUM | `commands-` |
+
+Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md`).
+
+## Available References
+
+**Commands Overview** (`commands-`):
+- `references/commands-overview.md`
+
+**Decision Guide** (`decision-`):
+- `references/decision-guide.md`
+
+**Gotchas and Pitfalls** (`gotchas-`):
+- `references/gotchas-pitfalls.md`
+
+**Common Workflows** (`workflows-`):
+- `references/workflows-common.md`
+
+---
+
+*4 reference files across 4 categories*
\ No newline at end of file
diff --git a/skills/supabase-cli/SKILL.md b/skills/supabase-cli/SKILL.md
new file mode 100644
index 0000000..29e8d30
--- /dev/null
+++ b/skills/supabase-cli/SKILL.md
@@ -0,0 +1,103 @@
+---
+name: supabase-cli
+description: Supabase CLI command reference and usage guide. Use this skill when running Supabase CLI commands, managing local development environments, deploying to Supabase projects, working with database migrations, edge functions, branches, secrets, storage, SSO, custom domains, network configuration, or any other Supabase CLI operation.
+license: MIT
+metadata:
+  author: supabase
+  version: "2.0.0"
+  organization: Supabase
+  date: January 2026
+  abstract: Supabase CLI skill focused on workflows, decision guidance, and common pitfalls. Covers local development, database management, migrations, edge functions, secrets, storage, authentication, custom domains, network configuration, and project management.
+---
+
+# Supabase CLI Reference
+
+Practical guide for using the Supabase CLI. Focuses on workflows, decision-making, and gotchas rather than exhaustive flag listings.
+
+## Important: Use `--help` for Flag Details
+
+For exact flag syntax on any command, run:
+
+```bash
+supabase <command> --help
+```
+
+The CLI's built-in help is always up to date. This skill focuses on what `--help` can't tell you: when to use which commands, common workflows, and pitfalls to avoid.
+
+## Installation
+
+```bash
+# npm
+npm install supabase --save-dev
+
+# Homebrew
+brew install supabase/tap/supabase
+
+# Scoop (Windows)
+scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
+scoop install supabase
+```
+
+## Global Flags
+
+Every command supports these flags:
+
+| Flag | Description |
+|------|-------------|
+| `--debug` | Output debug logs to stderr |
+| `--experimental` | Enable experimental features |
+| `-h, --help` | Help for the command |
+| `-o, --output <env\|pretty\|json\|toml\|yaml>` | Output format |
+| `--workdir <string>` | Path to a Supabase project directory |
+
+## Quick Reference
+
+### Local Development
+
+```bash
+supabase init                  # Initialize a new project
+supabase start                 # Start local containers
+supabase status                # Check running services
+supabase stop                  # Stop all containers
+```
+
+### Database & Migrations
+
+```bash
+supabase db diff -f <name>     # Generate migration from local changes
+supabase migration new <name>  # Create empty migration file
+supabase db reset              # Reset local database
+supabase db push               # Push migrations to remote
+supabase db pull               # Pull remote schema changes
+```
+
+### Edge Functions
+
+```bash
+supabase functions new <name>  # Create a new function
+supabase functions serve       # Serve locally for testing
+supabase functions deploy      # Deploy to remote project
+```
+
+### Project Setup
+
+```bash
+supabase login                 # Authenticate with Supabase
+supabase link --project-ref <ref>  # Link to remote project
+supabase projects list         # List all projects
+```
+
+## How to Use This Skill
+
+Read the reference files for guidance beyond what `--help` provides:
+
+- `references/workflows-common.md` — Multi-step workflows for common tasks
+- `references/decision-guide.md` — When to use which command or flag
+- `references/gotchas-pitfalls.md` — Common pitfalls and edge cases
+- `references/commands-overview.md` — Light listing of all available commands
+
+## References
+
+- https://supabase.com/docs/reference/cli/introduction
+- https://supabase.com/docs/guides/local-development
+- https://supabase.com/docs/guides/cli/getting-started
diff --git a/skills/supabase-cli/references/_sections.md b/skills/supabase-cli/references/_sections.md
new file mode 100644
index 0000000..26f0554
--- /dev/null
+++ b/skills/supabase-cli/references/_sections.md
@@ -0,0 +1,15 @@
+## 1. Common Workflows (workflows)
+**Impact:** CRITICAL
+**Description:** Multi-step workflows for common tasks including local development setup, migration lifecycle, edge functions, project setup, database dump/restore, type generation, branching, and CI/CD integration.
+
+## 2. Decision Guide (decision)
+**Impact:** HIGH
+**Description:** When to use which command or flag. Covers db pull vs diff, targeting patterns, diff engines, migration strategies, domain configuration choices, and experimental flag requirements.
+
+## 3. Gotchas and Pitfalls (gotchas)
+**Impact:** HIGH
+**Description:** Common pitfalls, edge cases, and things that catch people off guard when using the Supabase CLI.
+
+## 4. Commands Overview (commands)
+**Impact:** MEDIUM
+**Description:** Light listing of all available CLI commands grouped by category. Use `supabase <command> --help` for exact flag syntax.
diff --git a/skills/supabase-cli/references/commands-overview.md b/skills/supabase-cli/references/commands-overview.md
new file mode 100644
index 0000000..8f2fb60
--- /dev/null
+++ b/skills/supabase-cli/references/commands-overview.md
@@ -0,0 +1,160 @@
+---
+title: Commands Overview
+impact: MEDIUM
+impactDescription: Quick-scan listing of all available CLI commands by category
+tags: cli, supabase, commands, overview, reference
+---
+
+## Commands Overview
+
+Quick-scan reference for what commands are available. This is not a substitute for `--help` — always run `supabase <command> --help` for exact flag syntax.
+
+**Incorrect (guessing flags from memory):**
+
+```bash
+# Don't guess flag names — they change between versions
+supabase db push --force --remote
+```
+
+**Correct (checking help first):**
+
+```bash
+# Always check current flags
+supabase db push --help
+# Then run with the correct flags
+supabase db push --dry-run
+```
+
+### General
+
+`supabase init` — Initialize a new local project.
+`supabase login` — Authenticate with Supabase.
+`supabase link` — Link local project to a remote Supabase project.
+`supabase start` — Start local development stack.
+`supabase stop` — Stop local development stack.
+`supabase status` — Show status of local services.
+`supabase bootstrap` — Bootstrap a new project from a starter template.
+
+### Database
+
+`supabase db pull` — Pull remote schema changes into a new migration file.
+`supabase db push` — Push local migrations to remote database.
+`supabase db reset` — Reset database by re-applying all migrations.
+`supabase db dump` — Dump schema or data as SQL.
+`supabase db diff` — Diff local changes against migration files.
+`supabase db lint` — Lint database for schema errors.
+`supabase db start` — Start only the local Postgres container.
+
+### Migrations
+
+`supabase migration new` — Create a new empty migration file.
+`supabase migration list` — List migrations and their status.
+`supabase migration fetch` — Fetch migrations from remote history.
+`supabase migration repair` — Fix migration history.
+`supabase migration squash` — Squash multiple migrations into one.
+`supabase migration up` — Apply pending migrations.
+`supabase migration down` — Revert applied migrations.
+`supabase seed buckets` — Seed storage buckets from project config.
+
+### Edge Functions
+
+`supabase functions new` — Create a new edge function.
+`supabase functions serve` — Serve functions locally with hot reload.
+`supabase functions deploy` — Deploy functions to remote project.
+`supabase functions list` — List all deployed functions.
+`supabase functions download` — Download function source from remote.
+`supabase functions delete` — Delete a deployed function.
+
+### Projects and Organizations
+
+`supabase orgs list` — List organizations.
+`supabase orgs create` — Create an organization.
+`supabase projects list` — List projects.
+`supabase projects create` — Create a project.
+`supabase projects delete` — Delete a project.
+`supabase projects api-keys` — Show project API keys.
+
+### Branches
+
+`supabase branches create` — Create a preview branch.
+`supabase branches list` — List branches.
+`supabase branches get` — Get branch details.
+`supabase branches update` — Update branch configuration.
+`supabase branches delete` — Delete a branch.
+`supabase branches switch` — Switch to a branch.
+`supabase branches disable` — Disable branching.
+
+### Config
+
+`supabase config get` — Show current project config.
+`supabase config set` — Update project config.
+
+### Secrets
+
+`supabase secrets set` — Set secrets for edge functions.
+`supabase secrets list` — List secret names (not values).
+`supabase secrets unset` — Remove secrets.
+
+### Storage (requires `--experimental`)
+
+`supabase storage ls` — List objects in a bucket.
+`supabase storage cp` — Upload or download files (max 6MB).
+`supabase storage mv` — Move objects within a bucket.
+`supabase storage rm` — Delete objects.
+
+### SSO / Identity Providers
+
+`supabase sso add` — Add an SSO identity provider.
+`supabase sso list` — List identity providers.
+`supabase sso show` — Show provider details.
+`supabase sso update` — Update a provider.
+`supabase sso remove` — Remove a provider.
+
+### Domains
+
+`supabase domains create` — Set up a custom domain.
+`supabase domains get` — Get current domain config.
+`supabase domains activate` — Activate after DNS verification.
+`supabase domains reverify` — Re-verify DNS.
+`supabase domains delete` — Remove custom domain.
+
+### Vanity Subdomains (requires `--experimental`)
+
+`supabase vanity-subdomains activate` — Activate a vanity subdomain.
+`supabase vanity-subdomains get` — Get current subdomain.
+`supabase vanity-subdomains check-availability` — Check availability.
+`supabase vanity-subdomains delete` — Remove vanity subdomain.
+
+### Network and Security (requires `--experimental`)
+
+`supabase network-bans get` / `remove` — Manage IP bans.
+`supabase network-restrictions get` / `update` — Manage access rules.
+`supabase ssl-enforcement get` / `update` — Manage SSL enforcement.
+`supabase postgres-config get` / `update` / `delete` — Manage Postgres config overrides.
+
+### Utilities
+
+`supabase gen types` — Generate typed definitions from database schema.
+`supabase gen signing-key` — Generate a JWT signing key.
+`supabase test db` — Run pgTAP tests.
+`supabase test new` — Create a new test file.
+`supabase snippets list` / `download` — Manage saved SQL snippets.
+`supabase services` — Show versions of running services.
+`supabase completion` — Generate shell autocompletion scripts.
+
+### Inspect and Diagnostics
+
+`supabase inspect db bloat` — Table bloat estimation.
+`supabase inspect db blocking` — Queries holding locks.
+`supabase inspect db calls` — Most frequently called statements.
+`supabase inspect db db-stats` — General database statistics.
+`supabase inspect db index-stats` — Index usage statistics.
+`supabase inspect db locks` — Exclusive lock information.
+`supabase inspect db long-running-queries` — Queries running over 5 minutes.
+`supabase inspect db outliers` — Statements by total execution time.
+`supabase inspect db replication-slots` — Replication slot status.
+`supabase inspect db role-stats` — Per-role statistics.
+`supabase inspect db table-stats` — Table size and scan statistics.
+`supabase inspect db traffic-profile` — Read vs write distribution.
+`supabase inspect db vacuum-stats` — Vacuum and dead tuple info.
+`supabase inspect report` — Generate a full diagnostic report.
diff --git a/skills/supabase-cli/references/decision-guide.md b/skills/supabase-cli/references/decision-guide.md
new file mode 100644
index 0000000..4992e21
--- /dev/null
+++ b/skills/supabase-cli/references/decision-guide.md
@@ -0,0 +1,139 @@
+---
+title: Decision Guide - When to Use What
+impact: HIGH
+impactDescription: Guidance on choosing between similar commands and flags
+tags: cli, supabase, decision-guide, pull-vs-diff, targeting, migrations
+---
+
+## Decision Guide
+
+The Supabase CLI has several commands that seem similar but serve different purposes. This guide helps you pick the right one. For exact flag syntax, run `supabase <command> --help`.
+
+**Incorrect (using db pull when you meant db diff):**
+
+```bash
+# You made local changes via the dashboard and want a migration file.
+# db pull pulls from REMOTE — it won't capture your local changes.
+supabase db pull
+```
+
+**Correct (using db diff for local changes):**
+
+```bash
+# db diff compares your local database against migration files
+supabase db diff -f my_local_changes
+```
+
+### `db pull` vs `db diff`
+
+- **`db pull`** — Remote-to-local. Use when the remote database has changes made outside of migrations (e.g., someone edited the schema in the dashboard). Creates a migration file from the remote schema.
+- **`db diff`** — Captures local changes. Use when you've made changes via the local dashboard or psql and need to capture them as a migration file.
+
+### `db push` vs `migration up`
+
+**Incorrect (using migration up to deploy to remote):**
+
+```bash
+# migration up is for applying to a specific database
+# For standard remote deploys, use db push
+supabase migration up --linked
+```
+
+**Correct (deploying migrations to remote):**
+
+```bash
+# db push is the standard deploy command
+supabase db push
+```
+
+- **`db push`** — Standard deploy command. Pushes local migration files to the remote project.
+- **`migration up`** — More granular. Works with `--db-url` for arbitrary databases. Use when targeting a specific database outside the standard linked project.
+
+### `migration down` vs `db reset`
+
+**Incorrect (using db reset to revert one migration):**
+
+```bash
+# db reset drops EVERYTHING and re-applies from scratch
+# All local data is lost
+supabase db reset
+```
+
+**Correct (reverting specific migrations):**
+
+```bash
+# Revert just the last 2 migrations
+supabase migration down --last 2
+```
+
+- **`migration down`** — Targeted rollback. Reverts specific migrations in reverse order.
+- **`db reset`** — Nuclear option. Drops everything and re-applies all migrations. Destroys all local data.
+
+### Targeting: `--linked` vs `--local` vs `--db-url`
+
+Most database commands accept three targeting flags:
+
+**Correct (choosing the right target):**
+
+```bash
+# Day-to-day development
+supabase db diff --local
+
+# Deploying to your project
+supabase db push --linked
+
+# Self-hosted or CI database (connection string must be percent-encoded)
+supabase db push --db-url "postgresql://user:pass@host:5432/db"
+```
+
+### Diff engines
+
+`supabase db diff` supports multiple diffing backends. If the default misses something, try another engine.
+
+**Correct (switching diff engines):**
+
+```bash
+supabase db diff -f my_change --use-migra
+supabase db diff -f my_change --use-pgadmin
+supabase db diff -f my_change --use-pg-schema
+supabase db diff -f my_change --use-pg-delta
+```
+
+Known limitations across all engines: some can't capture changes to publications, materialized view contents, or certain extension-specific objects. Always review generated migration files before pushing.
+
+### Custom domains vs vanity subdomains
+
+These are **mutually exclusive** — you can use one or the other, not both.
+
+**Correct (custom domain setup):**
+
+```bash
+supabase domains create --custom-hostname api.yourdomain.com
+# Configure DNS, then:
+supabase domains reverify
+supabase domains activate
+```
+
+**Correct (vanity subdomain setup):**
+
+```bash
+supabase vanity-subdomains check-availability --desired-subdomain my-app --experimental
+supabase vanity-subdomains activate --desired-subdomain my-app --experimental
+```
+
+### When `--experimental` is required
+
+Several command groups require the `--experimental` flag: all `storage`, `vanity-subdomains`, `network-bans`, `network-restrictions`, `ssl-enforcement`, and `postgres-config` subcommands.
+
+**Incorrect (missing experimental flag):**
+
+```bash
+# This fails
+supabase storage ls
+```
+
+**Correct (with experimental flag):**
+
+```bash
+supabase storage ls --experimental
+```
diff --git a/skills/supabase-cli/references/gotchas-pitfalls.md b/skills/supabase-cli/references/gotchas-pitfalls.md
new file mode 100644
index 0000000..b6161cf
--- /dev/null
+++ b/skills/supabase-cli/references/gotchas-pitfalls.md
@@ -0,0 +1,167 @@
+---
+title: Gotchas and Common Pitfalls
+impact: HIGH
+impactDescription: Things that catch people off guard when using the Supabase CLI
+tags: cli, supabase, gotchas, pitfalls, troubleshooting, edge-cases
+---
+
+## Gotchas and Common Pitfalls
+
+Common mistakes and edge cases when using the Supabase CLI. These are things that `--help` won't warn you about.
+
+**Incorrect (running db reset without understanding the consequences):**
+
+```bash
+# This destroys ALL local data with no confirmation prompt
+supabase db reset
+```
+
+**Correct (backing up data before reset):**
+
+```bash
+# Dump data first if you need it
+supabase db dump --data-only -f backup.sql --local
+
+# Then reset
+supabase db reset
+```
+
+### `supabase stop` doesn't free disk space
+
+`supabase stop` stops containers but keeps Docker images cached. Over time this uses significant disk space.
+
+**Incorrect (expecting stop to clean up):**
+
+```bash
+supabase stop
+# Docker images still consuming gigabytes of disk
+```
+
+**Correct (freeing disk space):**
+
+```bash
+supabase stop --all
+```
+
+### `db pull` creates a migration file, not just a diff
+
+`supabase db pull` doesn't just show what changed — it creates a new migration file in `supabase/migrations/` and optionally updates the remote migration history table. If you just want to see the diff without creating files, use `db diff`.
+
+**Incorrect (using db pull to preview changes):**
+
+```bash
+# This creates a file and may update remote history
+supabase db pull
+```
+
+**Correct (previewing changes without side effects):**
+
+```bash
+# Just see the diff, no files created
+supabase db diff --linked
+```
+
+### `db diff` has known blind spots
+
+The diff engines can't capture everything. Known limitations: changes to publications, materialized view contents, some extension-specific objects, and RLS policies may sometimes diff incorrectly.
+
+**Correct (reviewing diffs before pushing):**
+
+```bash
+# Generate migration
+supabase db diff -f my_change
+
+# ALWAYS review the generated file
+cat supabase/migrations/*_my_change.sql
+
+# If the diff seems incomplete, try a different engine
+supabase db diff -f my_change --use-migra
+```
+
+### Storage commands require `--experimental`
+
+**Incorrect (storage without experimental):**
+
+```bash
+# This errors
+supabase storage ls
+```
+
+**Correct (storage with experimental):**
+
+```bash
+supabase storage ls --experimental
+```
+
+### `storage cp` has a 6MB upload limit
+
+Standard uploads via `supabase storage cp` are not suitable for files over 6MB. For larger files, use the Supabase client library's resumable upload API instead.
+
+### `--db-url` must be percent-encoded
+
+**Incorrect (special characters in connection string):**
+
+```bash
+# The @ and # in the password break parsing
+supabase db push --db-url "postgresql://user:p@ss#word@host:5432/db"
+```
+
+**Correct (percent-encoded connection string):**
+
+```bash
+supabase db push --db-url "postgresql://user:p%40ss%23word@host:5432/db"
+```
+
+### `migration squash` rewrites history
+
+Squashing combines multiple migration files into one and rewrites the migration history on the target database. If team members have un-pushed migrations based on the old history, they'll need to reconcile. Coordinate squashes with your team.
+
+### `db lint` defaults to exit 0 even on warnings
+
+**Incorrect (expecting lint to fail CI on warnings):**
+
+```bash
+# Always exits 0, even with warnings
+supabase db lint
+```
+
+**Correct (failing CI on warnings):**
+
+```bash
+supabase db lint --fail-on warning
+# Or fail only on errors:
+supabase db lint --fail-on error
+```
+
+### Auth and storage schemas are excluded from `db pull`
+
+**Incorrect (expecting db pull to capture auth schema changes):**
+
+```bash
+# This only pulls public schema changes
+supabase db pull
+```
+
+**Correct (explicitly pulling auth/storage schemas):**
+
+```bash
+supabase db pull --schema auth,storage
+```
+
+### `supabase link` doesn't require Docker, but `db pull` and `db diff` do
+
+While `supabase link` itself doesn't need Docker, subsequent operations like `db pull` and `db diff` start local Postgres containers for schema comparison. Make sure Docker is running before pulling or diffing.
+
+### Functions work locally but fail after deploy
+
+Locally served functions have access to all environment variables. Deployed functions only see secrets set via `supabase secrets set`. If a function works locally but fails after deploy, check that all required secrets are set.
+
+**Correct (verifying secrets before deploy):**
+
+```bash
+# List current secrets (names only, not values)
+supabase secrets list
+
+# Set any missing secrets
+supabase secrets set MY_KEY=value ANOTHER_KEY=value2
+```
diff --git a/skills/supabase-cli/references/workflows-common.md b/skills/supabase-cli/references/workflows-common.md
new file mode 100644
index 0000000..1202a50
--- /dev/null
+++ b/skills/supabase-cli/references/workflows-common.md
@@ -0,0 +1,175 @@
+---
+title: Common Workflows
+impact: CRITICAL
+impactDescription: Multi-step workflows for the most common Supabase CLI tasks
+tags: cli, supabase, workflows, local-dev, migrations, functions, deploy
+---
+
+## Common Workflows
+
+Follow these workflows for common Supabase CLI tasks. For exact flag syntax on any command, run `supabase <command> --help`. These workflows show the correct order of operations and decision points that `--help` doesn't cover.
+
+**Incorrect (skipping link before pull):**
+
+```bash
+# This fails — you must link before pulling
+supabase init
+supabase db pull
+```
+
+**Correct (local development setup):**
+
+```bash
+# 1. Initialize project (creates supabase/ directory)
+supabase init
+
+# 2. Link to your remote project
+supabase link --project-ref <your-project-ref>
+
+# 3. Pull current remote schema as your first migration
+supabase db pull
+
+# 4. Start local stack (Postgres, Auth, Storage, etc.)
+supabase start
+
+# 5. Check service URLs and credentials
+supabase status
+```
+
+After `start`, the local dashboard is at `http://localhost:54323`. The local API URL and anon key are printed by `status`. To stop: `supabase stop`. Add `--all` to also remove Docker images and free disk space.
+
+### Making schema changes
+
+There are two paths depending on where you make changes.
+
+**Correct (Path A — SQL migration files, recommended):**
+
+```bash
+# 1. Create a new migration
+supabase migration new add_profiles_table
+
+# 2. Edit the generated file in supabase/migrations/
+
+# 3. Apply it locally (re-runs all migrations from scratch)
+supabase db reset
+
+# 4. Push to remote when ready
+supabase db push
+```
+
+**Correct (Path B — changes via local dashboard or psql):**
+
+```bash
+# 1. Make changes in local dashboard or via psql
+
+# 2. Generate a migration from the diff
+supabase db diff -f add_profiles_table
+
+# 3. Verify by resetting
+supabase db reset
+
+# 4. Push to remote
+supabase db push
+```
+
+**Correct (pulling remote changes made outside migrations):**
+
+```bash
+# Pull creates a new migration file from remote schema diff
+supabase db pull
+
+# Verify locally
+supabase db reset
+```
+
+### Migration lifecycle
+
+**Correct (full migration lifecycle):**
+
+```bash
+# Create migration
+supabase migration new <name>
+
+# List migrations and their applied/pending status
+supabase migration list
+
+# Apply pending migrations
+supabase migration up
+
+# Revert last N migrations
+supabase migration down --last <N>
+
+# Squash multiple migrations into one
+supabase migration squash --version <target>
+
+# Fix out-of-sync history (mark as applied/reverted without running SQL)
+supabase migration repair <version> --status applied
+supabase migration repair <version> --status reverted
+```
+
+### Edge functions
+
+**Incorrect (deploying without setting secrets):**
+
+```bash
+supabase functions new my-function
+# Edit function to use Deno.env.get("MY_KEY")
+supabase functions deploy my-function
+# Function fails at runtime — MY_KEY is not set on remote
+```
+
+**Correct (edge functions workflow):**
+
+```bash
+# 1. Create a new function
+supabase functions new my-function
+
+# 2. Develop locally with hot reload
+supabase functions serve
+
+# 3. Set secrets before deploying
+supabase secrets set MY_KEY=value
+# Or from .env file:
+supabase secrets set --env-file .env
+
+# 4. Deploy to remote project
+supabase functions deploy my-function
+
+# Deploy all functions at once
+supabase functions deploy
+```
+
+### Type generation
+
+**Correct (generating types from database):**
+
+```bash
+# From local database
+supabase gen types --local --lang typescript > src/types/database.ts
+
+# From linked remote project
+supabase gen types --linked --lang typescript > src/types/database.ts
+
+# Specific schemas only
+supabase gen types --local --schema public,auth --lang typescript > src/types/database.ts
+```
+
+Supported languages: `typescript`, `go`, `swift`, `python`.
+
+### CI/CD integration
+
+**Correct (CI/CD pipeline):**
+
+```bash
+# Link project (use SUPABASE_ACCESS_TOKEN env var for non-interactive auth)
+supabase link --project-ref <ref>
+
+# Push migrations
+supabase db push
+
+# Deploy all functions
+supabase functions deploy
+
+# Lint database for errors (use --fail-on for CI exit codes)
+supabase db lint --fail-on warning
+```