[pull] master from supabase:master

apps/docs/CONTRIBUTING.md

@@ -191,8 +191,7 @@ Choose the appropriate `type` for your admonition:
 - `danger`: Warn about actions or conditions that could cause data loss, expose sensitive data, or create another severe and difficult-to-reverse outcome. State the consequence first, and then explain how to avoid it.
 - `deprecation`: Identify a deprecated feature or behavior. State how the change affects the reader, and then provide the supported alternative or migration path.
 - `caution`: Warn about behavior that could cause bugs, failed operations, unexpected results, or serious inconvenience but doesn't rise to the severity of `danger`.
-- `tip`: Share an optional shortcut, optimization, or best practice that helps the reader complete the task more effectively. The main procedure must still work without it.
-- `note`: Highlight an important prerequisite, constraint, or clarification that doesn't represent a risk. If the information is essential to completing a step, include it in the procedure instead.
+- `note`: Highlight an important prerequisite, constraint, clarification, or optional shortcut that doesn't represent a risk. If the information is essential to completing a step, include it in the procedure instead.
 
 ```
 <Admonition type="note" title="Optional title">

apps/docs/app/contributing/content.mdx

@@ -75,12 +75,11 @@ For content that requires progressive disclosure:
 
 ### Admonition
 
-For extra information that doesn't fit into the main flow. There are 5 supported types of admonitions:
+For extra information that doesn't fit into the main flow, you can use the following types of admonitions:
 
 - `danger` to warn the user about any missteps that could cause data loss or data leaks
 - `deprecation` to notify the user about features that are (or will soon be) deprecated
 - `caution` to warn about anything that could cause a bug or serious user inconvenience
-- `tip` to point out helpful but optional actions
 - `note` for anything else
 
 Leave a blank line between the admonition tag and the contained content. This will prevent Prettier from trying to break the lines within the content.
@@ -104,15 +103,9 @@ You should make sure you don't set this up wrong.
 
 </Admonition>
 
-<Admonition type="tip">
-
-In certain cases, you may want to do this.
-
-</Admonition>
-
 <Admonition type="note">
 
-Additional helpful information.
+In certain cases, you may want to do this.
 
 </Admonition>
 ```
@@ -135,15 +128,9 @@ You should make sure you don't set this up wrong.
 
 </Admonition>
 
-<Admonition type="tip">
-
-In certain cases, you may want to do this.
-
-</Admonition>
-
 <Admonition type="note">
 
-Additional helpful information.
+In certain cases, you may want to do this.
 
 </Admonition>
 

apps/docs/app/guides/getting-started/ai-skills/AiSkills.utils.test.ts

@@ -0,0 +1,54 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { getAiSkillsImpl } from './AiSkills.utils'
+
+const { readFileMock } = vi.hoisted(() => ({
+  readFileMock: vi.fn(),
+}))
+
+vi.mock('node:fs/promises', () => ({
+  readFile: readFileMock,
+}))
+
+describe('getAiSkillsImpl', () => {
+  beforeEach(() => {
+    readFileMock.mockReset()
+  })
+
+  it('parses the generated skills JSON', async () => {
+    const skills = [
+      {
+        name: 'supabase',
+        description: 'Work with Supabase',
+        installCommand: 'npx skills add supabase/agent-skills --skill supabase',
+      },
+      {
+        name: 'supabase-postgres-best-practices',
+        description: 'Postgres best practices',
+        installCommand:
+          'npx skills add supabase/agent-skills --skill supabase-postgres-best-practices',
+      },
+    ]
+    readFileMock.mockResolvedValue(JSON.stringify(skills))
+
+    await expect(getAiSkillsImpl()).resolves.toEqual(skills)
+  })
+
+  it('propagates errors reading the generated file', async () => {
+    readFileMock.mockRejectedValue(new Error('ENOENT'))
+
+    await expect(getAiSkillsImpl()).rejects.toThrow('ENOENT')
+  })
+
+  it('throws when the generated JSON is not an array', async () => {
+    readFileMock.mockResolvedValue(JSON.stringify({ name: 'supabase' }))
+
+    await expect(getAiSkillsImpl()).rejects.toThrow('Malformed ai-skills.json')
+  })
+
+  it('throws when an entry is missing required string fields', async () => {
+    readFileMock.mockResolvedValue(JSON.stringify([{ name: 'supabase', description: 'x' }]))
+
+    await expect(getAiSkillsImpl()).rejects.toThrow('Malformed ai-skills.json')
+  })
+})

apps/docs/app/guides/getting-started/ai-skills/AiSkills.utils.ts

@@ -9,9 +9,25 @@ interface SkillSummary {
   installCommand: string
 }
 
-async function getAiSkillsImpl(): Promise<SkillSummary[]> {
+function isSkillSummary(value: unknown): value is SkillSummary {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as SkillSummary).name === 'string' &&
+    typeof (value as SkillSummary).description === 'string' &&
+    typeof (value as SkillSummary).installCommand === 'string'
+  )
+}
+
+export async function getAiSkillsImpl(): Promise<SkillSummary[]> {
   const raw = await readFile(join(GENERATED_DIRECTORY, 'ai-skills.json'), 'utf-8')
-  return JSON.parse(raw)
+  const parsed: unknown = JSON.parse(raw)
+
+  if (!Array.isArray(parsed) || !parsed.every(isSkillSummary)) {
+    throw new Error('Malformed ai-skills.json: expected an array of SkillSummary objects')
+  }
+
+  return parsed
 }
 
 export const getAiSkills = cache(getAiSkillsImpl)

apps/docs/app/guides/getting-started/ai-skills/AiSkillsIndex.smoke.test.ts

@@ -0,0 +1,31 @@
+// Guards against the docs GitHub App losing access to supabase/agent-skills,
+// which 404s silently and renders an empty table.
+import { load } from 'cheerio'
+import { describe, expect, it } from 'vitest'
+
+// Override to target a preview deploy or localhost; defaults to production.
+const DOCS_BASE_URL = process.env.DOCS_SMOKE_URL ?? 'https://supabase.com'
+const AI_SKILLS_URL = `${DOCS_BASE_URL.replace(/\/$/, '')}/docs/guides/ai-tools/ai-skills`
+
+describe('prod smoke test: agent skills load on the AI Skills page', () => {
+  it('renders the skills table with at least one skill and no fallback', async () => {
+    const result = await fetch(AI_SKILLS_URL, { signal: AbortSignal.timeout(30_000) })
+    expect(result.status).toBe(200)
+
+    const html = await result.text()
+    expect(html).not.toContain('Unable to load AI skills at the moment.')
+
+    // The install command only appears on real skill rows.
+    const $ = load(html)
+    const installCommands = $('code')
+      .map(function () {
+        return $(this).text()
+      })
+      .get()
+      .filter((text) => text.startsWith('npx skills add supabase/agent-skills --skill '))
+
+    expect(installCommands.length).toBeGreaterThan(0)
+    // Test timeout must outlive the fetch abort so the network error surfaces
+    // instead of a generic vitest timeout.
+  }, 45_000)
+})

apps/docs/components/WrapperDashboardIntegration.tsx

@@ -4,7 +4,7 @@ import { Admonition } from 'ui-patterns/Admonition'
 
 export function WrapperDashboardIntegration({ title, path }: { title: string; path: string }) {
   return (
-    <Admonition type="tip" className="mb-4">
+    <Admonition type="note" className="mb-4">
       <p>You can enable the {title} wrapper right from the Supabase dashboard.</p>
 
       <Button asChild>

apps/docs/content/_partials/api_settings.mdx

@@ -5,7 +5,7 @@ To interact with data in database tables, you use the client libraries that wrap
 <ProjectConfigVariables variable="url" />
 <ProjectConfigVariables variable="publishable" />
 
-<Admonition type="tip">
+<Admonition type="note">
 
 [Read the API keys docs](/docs/guides/getting-started/api-keys) for a full explanation of all key types, their uses, and where to find them.
 

apps/docs/content/_partials/cost_warning.mdx

@@ -1,6 +1,6 @@
 <Admonition type="caution">
 
-To keep SMS sending costs under control, make sure you adjust your project's rate limits and [configure CAPTCHA](/docs/guides/auth/auth-captcha). See the [Production Checklist](/docs/guides/platform/going-into-prod) to learn more.
+To keep SMS sending costs under control, make sure you adjust your project's rate limits and [configure CAPTCHA](/docs/guides/auth/auth-captcha). See the [Production Checklist](/docs/guides/deployment/going-into-prod) to learn more.
 
 Some countries have special regulations for services that send SMS messages to users, (e.g India's TRAI DLT regulations). Remember to look up and follow the regulations of countries where you operate.
 

apps/docs/content/_partials/create_client_snippet.mdx

@@ -1,4 +1,4 @@
-<Admonition type="tip">
+<Admonition type="note">
 
 Make sure you're using the right `supabase` client in the following code.
 

apps/docs/content/_partials/postgres_installation.mdx

@@ -47,7 +47,7 @@
     psql --version
     ```
 
-    <Admonition type="tip">
+    <Admonition type="note">
 
     If you get an error that psql is not available or cannot be found, check that you have correctly added the binary to your system PATH. Also try restarting your terminal.
 

apps/docs/content/_partials/project_setup.mdx

@@ -27,7 +27,7 @@ Now set up the database schema. You can use the "User Management Starter" quicks
 
 <Admonition type="note">
 
-You can pull the database schema down to your local project by running the `db pull` command. Read the [local development docs](/docs/guides/cli/local-development#link-your-project) for detailed instructions.
+You can pull the database schema down to your local project by running the `db pull` command. Read the [local development docs](/docs/guides/local-development/database-migrations#link-your-project) for detailed instructions.
 
 ```bash
 supabase link --project-ref <project-id>

apps/docs/content/_partials/providers.mdx

@@ -6,7 +6,7 @@ Supabase Auth works with many popular Auth methods, including Social and Phone A
 
 <AuthProviders type="social" />
 
-<Admonition type="tip">
+<Admonition type="note">
 
 You can also add any OAuth2 or OIDC-compatible identity provider using [Custom OAuth/OIDC Providers](/docs/guides/auth/custom-oauth-providers).
 

apps/docs/content/_partials/quickstart_db_setup.mdx

@@ -29,7 +29,7 @@ To start, you need a Supabase project.
 
 Create a new Supabase project from [the Dashboard of any organization](/dashboard/new/_) you belong to.
 
-<Admonition type="tip" title="Want to create a project programmatically?">
+<Admonition type="note" title="Want to create a project programmatically?">
 
 Use [the Management API](/docs/reference/api/v1-create-a-project) or ask [the MCP server](/docs/guides/ai-tools/mcp#account-management) to create a new Supabase project.
 
@@ -41,13 +41,13 @@ When your Supabase project is up and running, create an `instruments` table with
 
 Do these steps within your project's dashboard by copying and running the snippet in your project's [SQL Editor](/dashboard/project/_/sql/new).
 
-<Admonition type="tip">
+<Admonition type="note">
 
 Save some steps by <a href={`/dashboard/project/_/sql/new?content=${encodeURIComponent(sqlSetup)}`}>clicking here to prefill the SQL</a> in the SQL Editor, and then clicking **Run**.
 
 </Admonition>
 
-<Admonition type="tip" title="Want to setup the database programmatically?">
+<Admonition type="note" title="Want to setup the database programmatically?">
 
 You can use [the Management API](/docs/reference/api/v1-run-a-query) or ask [the MCP server](/docs/guides/ai-tools/mcp#database) to execute SQL queries.
 

apps/docs/content/_partials/quickstart_intro.mdx

@@ -1,5 +1,5 @@
 This tutorial demonstrates how to build a basic user management app. The app authenticates and identifies the user, stores their profile information in the database, and allows the user to log in, update their profile details, and upload a profile photo. The app uses:
 
-- [Supabase Database](/docs/guides/database) - a Postgres database for storing your user data and [Row Level Security](/docs/guides/auth#row-level-security) so data is protected and users can only access their own information.
+- [Supabase Database](/docs/guides/database/overview) - a Postgres database for storing your user data and [Row Level Security](/docs/guides/auth#row-level-security) so data is protected and users can only access their own information.
 - [Supabase Auth](/docs/guides/auth) - allow users to sign up and log in.
 - [Supabase Storage](/docs/guides/storage) - allow users to upload a profile photo.

apps/docs/content/_partials/uiLibCta.mdx

@@ -1,4 +1,4 @@
-<Admonition type="tip" title="Explore drop-in UI components for your Supabase app.">
+<Admonition type="note" title="Explore drop-in UI components for your Supabase app.">
 
 UI components built on shadcn/ui that connect to Supabase via a single command.
 

apps/docs/content/guides/ai-tools/ai-skills.mdx

@@ -22,7 +22,7 @@ Skills are installed at project scope by default, placing them in your repositor
 
 Add skills for all detected agents at the same time by passing `--all`. See the [skills package](https://github.com/vercel-labs/skills) for more options.
 
-You can also install the agent skills together with the Supabase MCP server using the [Supabase Plugin for AI Coding Agents](/docs/guides/getting-started/plugins) for a combined one-step setup.
+You can also install the agent skills together with the Supabase MCP server using the [Supabase Plugin for AI Coding Agents](/docs/guides/ai-tools/plugins) for a combined one-step setup.
 
 ## Available skills
 

apps/docs/content/guides/ai-tools/byo-mcp.mdx

@@ -49,7 +49,7 @@ Create a new Edge Function for your MCP server:
 supabase functions new mcp
 ```
 
-<Admonition type="tip">
+<Admonition type="note">
 
 This tutorial uses the [official MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) with the `WebStandardStreamableHTTPServerTransport`, but you can use any MCP framework that's compatible with the [Edge Runtime](/docs/guides/functions), such as [mcp-lite](https://github.com/fiberplane/mcp-lite) or [mcp-handler](https://github.com/vercel/mcp-handler).
 

apps/docs/content/guides/ai-tools/mcp.mdx

@@ -32,13 +32,13 @@ To verify the client has access to the MCP server tools, try asking it to query
 
 <$Show if="docs:prompts">
 
-For curated, ready-to-use prompts that work well with IDEs and AI agents, see our [AI Prompts](/docs/guides/getting-started/ai-prompts) collection.
+For curated, ready-to-use prompts that work well with IDEs and AI agents, see our [AI Prompts](/docs/guides/ai-tools/ai-prompts) collection.
 
 </$Show>
 
 <$Show if="docs:agent_skills">
 
-Additionally, you can install Supabase agent skills alongside the MCP server, use the [Supabase Plugin for AI Coding Agents](/docs/guides/getting-started/plugins) for a combined one-step setup.
+Additionally, you can install Supabase agent skills alongside the MCP server, use the [Supabase Plugin for AI Coding Agents](/docs/guides/ai-tools/plugins) for a combined one-step setup.
 
 </$Show>
 
@@ -116,9 +116,9 @@ The [configuration panel above](#configure-your-ai-tool) can set these options f
 
 Parameters can be combined: <code><CustomContent data="mcp:servers">remote</CustomContent>?project_ref=abc123&read_only=true</code>
 
-<Admonition type="tip">
+<Admonition type="note">
 
-When using [Supabase CLI](/docs/guides/cli) for local development, the MCP server is available at <code><CustomContent data="mcp:servers">local</CustomContent></code>.
+When using [Supabase CLI](/docs/guides/local-development) for local development, the MCP server is available at <code><CustomContent data="mcp:servers">local</CustomContent></code>.
 
 </Admonition>
 

apps/docs/content/guides/ai-tools/plugins.mdx

@@ -6,7 +6,7 @@ description: 'The Supabase plugin for AI coding agents bundles the MCP server an
 sidebar_label: 'Supabase Plugin for AI Coding Agents'
 ---
 
-The Supabase Plugin for AI Coding Agents gives your AI coding agent everything it needs to work with Supabase. It bundles the [Supabase MCP server](/docs/guides/getting-started/mcp) and [Supabase agent skills](/docs/guides/getting-started/ai-skills) so your agent can query your database, manage migrations, deploy Edge Functions, and follow Supabase and Postgres best practices — without manual configuration.
+The Supabase Plugin for AI Coding Agents gives your AI coding agent everything it needs to work with Supabase. It bundles the [Supabase MCP server](/docs/guides/ai-tools/mcp) and [Supabase agent skills](/docs/guides/ai-tools/ai-skills) so your agent can query your database, manage migrations, deploy Edge Functions, and follow Supabase and Postgres best practices — without manual configuration.
 
 ## Quick installation
 
@@ -28,13 +28,13 @@ Plugins for AI coding agents are packages of AI agent extensions. A single plugi
 - **Agents** — specialized sub-agents with specific personas and tool configurations
 - **Slash commands** — custom commands you can invoke directly in chat
 
-Bundling the [MCP server](/docs/guides/getting-started/mcp) and [agent skills](/docs/guides/getting-started/ai-skills) into a single plugin means you can set up both in one step. You can also install them separately if you prefer. You can install the plugin globally to use it across all your projects, or per project to keep it isolated.
+Bundling the [MCP server](/docs/guides/ai-tools/mcp) and [agent skills](/docs/guides/ai-tools/ai-skills) into a single plugin means you can set up both in one step. You can also install them separately if you prefer. You can install the plugin globally to use it across all your projects, or per project to keep it isolated.
 
 ## What's included
 
 ### Supabase MCP server
 
-The [Supabase MCP server](/docs/guides/getting-started/mcp) connects your AI coding agent directly to your Supabase projects. Once authenticated, your agent can query your database, manage migrations, deploy Edge Functions, and more — see the [full list of available tools](/docs/guides/getting-started/mcp#available-tools).
+The [Supabase MCP server](/docs/guides/ai-tools/mcp) connects your AI coding agent directly to your Supabase projects. Once authenticated, your agent can query your database, manage migrations, deploy Edge Functions, and more — see the [full list of available tools](/docs/guides/ai-tools/mcp#available-tools).
 
 ### Supabase agent skills
 
@@ -43,7 +43,7 @@ Skills provide your agent with Supabase-specific procedural knowledge:
 - **`supabase`** — Core guidance for working with Supabase products (Database, Auth, Edge Functions, Storage, Realtime)
 - **`supabase-postgres-best-practices`** — Postgres query optimization, schema design, connection management, and RLS patterns
 
-For a full list of available skills and supported agents, see [Agent Skills](/docs/guides/getting-started/ai-skills).
+For a full list of available skills and supported agents, see [Agent Skills](/docs/guides/ai-tools/ai-skills).
 
 ## Manual installation
 

apps/docs/content/guides/ai/examples/image-search-openai-clip.mdx

@@ -30,7 +30,7 @@ poetry new image-search
 
 ## Setup Supabase project
 
-If you haven't already, [install the Supabase CLI](/docs/guides/cli), then initialize Supabase in the root of your newly created poetry project:
+If you haven't already, [install the Supabase CLI](/docs/guides/local-development), then initialize Supabase in the root of your newly created poetry project:
 
 ```shell
 supabase init

apps/docs/content/guides/ai/examples/mixpeek-video-search.mdx

@@ -28,7 +28,7 @@ poetry new video-search
 
 ## Setup Supabase project
 
-If you haven't already, [install the Supabase CLI](/docs/guides/cli), then initialize Supabase in the root of your newly created poetry project:
+If you haven't already, [install the Supabase CLI](/docs/guides/local-development), then initialize Supabase in the root of your newly created poetry project:
 
 ```shell
 supabase init

apps/docs/content/guides/ai/examples/nextjs-vector-search.mdx

@@ -48,7 +48,7 @@ Prepare the database schema. We can use the "OpenAI Vector Search" quickstart in
 
     <StepHikeCompact.Details title="Set up Supabase locally">
 
-    Make sure you have the latest version of the [Supabase CLI installed](/docs/guides/cli/getting-started).
+    Make sure you have the latest version of the [Supabase CLI installed](/docs/guides/local-development/cli/getting-started).
 
     Initialize Supabase in the root directory of your app.
 

apps/docs/content/guides/ai/examples/openai.mdx

@@ -13,7 +13,7 @@ OpenAI's API is intended to be used from the server-side. Supabase offers Edge F
 
 ## Setup Supabase project
 
-If you haven't already, [install the Supabase CLI](/docs/guides/cli) and initialize your project:
+If you haven't already, [install the Supabase CLI](/docs/guides/local-development) and initialize your project:
 
 ```shell
 supabase init

apps/docs/content/guides/ai/going-to-prod.mdx

@@ -113,7 +113,7 @@ First, a few generic tips which you can pick and choose from:
 
 ## Useful links
 
-Don't forget to check out the general [Production Checklist](/docs/guides/platform/going-into-prod) to ensure your project is secure, performant, and will remain available for your users.
+Don't forget to check out the general [Production Checklist](/docs/guides/deployment/going-into-prod) to ensure your project is secure, performant, and will remain available for your users.
 
 You can look at our [Choosing Compute Add-on](/docs/guides/ai/choosing-compute-addon) guide to get a basic understanding of how much compute you might need for your workload.