Update from code changes: document metrics catalog embedding

docs.json

@@ -315,6 +315,7 @@
                   "guides/embedding/dashboards",
                   "guides/embedding/charts",
                   "guides/embedding/ai-agents",
+                  "guides/embedding/metrics-catalog",
                   "guides/embedding/data-apps"
                 ]
               },

guides/embedding/how-to-embed-content.mdx

@@ -12,7 +12,7 @@ import EmbedAvailability from '/snippets/embedding-availability.mdx';
 
 ## What can you embed?
 
-Lightdash supports embedding three types of content, each designed for different use cases:
+Lightdash supports embedding several types of content, each designed for different use cases:
 
 ### Dashboards
 
@@ -55,6 +55,21 @@ AI agent embedding requires the React SDK. iframe embedding is not supported for
 
 [Learn more about embedding AI agents →](/guides/embedding/ai-agents)
 
+### Metrics catalog
+
+Embed the project's metrics catalog so users can browse the metrics and dimensions in your semantic layer, preview them, and — if you allow it — jump into Explore from any metric. Great for surfacing "what can I measure?" inside your product without exposing a full Lightdash workspace.
+
+**Use cases:**
+- A self-serve metric browser inside a customer-facing app
+- A discovery surface next to your own charts so users can find related metrics
+- Guided exploration where users start from a metric and continue into Explore
+
+<Info>
+Metrics catalog embedding requires the React SDK. iframe embedding is not supported for the metrics catalog.
+</Info>
+
+[Learn more about embedding the metrics catalog →](/guides/embedding/metrics-catalog)
+
 ### Data apps
 
 Embed a [data app](/guides/data-apps) as standalone content in an iframe — the full app, no dashboard or surrounding chrome. Useful when you want to surface an entire AI-generated app as a feature in your product.
@@ -85,6 +100,7 @@ All three methods use the same JWT-based authentication and security model.
 | Dashboards | ✓ | ✓ | ✓ |
 | Individual charts | ✗ | ✗ | ✓ |
 | AI agents | ✗ | ✗ | ✓ |
+| Metrics catalog | ✗ | ✗ | ✓ |
 | Data apps (standalone) | ✓ | ✓ | ✗ |
 | Requires embedding in an app | No | Yes | Yes |
 | Setup complexity | Low | Low | Medium |
@@ -186,6 +202,10 @@ Lightdash provides code snippets you can copy and use in your app to generate va
     Let customers chat with their data inside your application
   </Card>
 
+  <Card title="Embedding the metrics catalog" icon="list" href="/guides/embedding/metrics-catalog">
+    Let customers browse and explore project metrics from your app
+  </Card>
+
   <Card title="Embedding data apps" icon="sparkles" href="/guides/embedding/data-apps">
     Embed a standalone data app in an iframe, no dashboard required
   </Card>

guides/embedding/metrics-catalog.mdx

@@ -0,0 +1,146 @@
+---
+title: "How to embed the metrics catalog"
+sidebarTitle: "Metrics catalog"
+description: "Embed the Lightdash metrics catalog so your users can browse the metrics and dimensions in a project without a Lightdash login."
+---
+
+import EmbedAvailability from '/snippets/embedding-availability.mdx';
+
+<EmbedAvailability />
+
+## Overview
+
+Metrics catalog embedding lets you drop the Lightdash metrics catalog directly into your application. Embedded users can browse the metrics defined in a project, search by name or category, preview a metric on a small chart, and — if you allow it — jump into Explore to slice the metric by any dimension in the model.
+
+Metrics catalog embeds use the same JWT-based security model as other embed types, with a dedicated `content.type: "metricsCatalog"` token. Dashboard, chart, and AI agent tokens cannot access the metrics catalog, and a metrics catalog token cannot render other embed surfaces.
+
+### When to use metrics catalog embedding
+
+- Give customers a self-serve "what can I measure?" view of your semantic layer inside your product.
+- Surface a metric browser next to your own charts so users can discover related metrics.
+- Let embedded users start a new exploration from any metric without exposing your full Lightdash workspace.
+
+### Available features
+
+Embedded metrics catalog supports:
+
+- Browsing all metrics in the project the JWT is scoped to
+- Searching and filtering by category
+- Previewing a metric with its default time-series chart
+- Continuing into an embedded Explore from any metric when `content.canExplore` is `true`
+- Saving Explore results into a fixed destination space via [write actions](/references/embedding#write-actions)
+- Row- and column-level filtering via [user attributes](/references/workspace/user-attributes)
+
+## Prerequisites
+
+Before you embed the metrics catalog, you need:
+
+- An embed secret for the project. See [Embedding quickstart](/guides/embedding/how-to-embed-content).
+- At least one metric defined in the project's semantic layer. See [How to create metrics](/get-started/develop-in-lightdash/how-to-create-metrics).
+- A React or Next.js host application — metrics catalog embedding is only available through the React SDK.
+- If you want embedded users to save charts from Explore, a destination space and a write actor. See [Write actions](/references/embedding#write-actions).
+
+## Embed the metrics catalog with the React SDK
+
+The React SDK ships a `Lightdash.MetricsCatalog` component that renders the catalog inside an iframe. When the embedded viewer clicks **Explore from here** on a metric, the same component swaps in an embedded Explore view — the host page never has to change route.
+
+```tsx
+import Lightdash from '@lightdash/sdk';
+
+function MyMetricsCatalog() {
+  return (
+    <Lightdash.MetricsCatalog
+      instanceUrl="https://app.lightdash.cloud"
+      token={generateMetricsCatalogToken()} // Server-side function
+    />
+  );
+}
+```
+
+See [`Lightdash.MetricsCatalog`](/references/react-sdk#lightdashmetricscatalog) for the full prop list and styling options.
+
+## Generate a metrics catalog embed token
+
+Metrics catalog embeds require a JWT with `content.type: "metricsCatalog"`. Generate it server-side using your embed secret.
+
+```javascript
+import jwt from 'jsonwebtoken';
+
+const token = jwt.sign({
+  content: {
+    type: 'metricsCatalog',
+    projectUuid: 'your-project-uuid',
+    canExplore: true,
+  },
+  writeActions: {
+    serviceAccountUserUuid: 'service-account-user-uuid',
+    spaceUuid: 'destination-space-uuid',
+  },
+  userAttributes: {
+    tenant_id: 'tenant-abc', // Row-level filtering for the embedded viewer
+  },
+  user: {
+    email: 'customer@example.com',
+  },
+}, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });
+```
+
+**Required fields:**
+
+- `content.type` — must be `"metricsCatalog"`.
+- `content.projectUuid` — pins the embed to a specific project. The catalog only lists metrics from this project.
+
+**Optional fields:**
+
+- `content.canExplore` — when `true`, embedded users can click **Explore from here** on any metric to open the embedded Explore view. Omit or set to `false` to keep the embed read-only.
+- `writeActions` — needed only when `canExplore` is `true` and you want embedded users to save charts they build from Explore. See [Write actions](/references/embedding#write-actions).
+- `userAttributes` — applies row- and column-level filters to catalog previews and Explore queries, identical to other embed types.
+- `user.email` / `user.externalId` — surfaced in audit and analytics for the embedded viewer.
+
+## Controlling access
+
+Metrics catalog embeds honor the same access controls as other embed surfaces:
+
+- The catalog only shows metrics from the project named in `content.projectUuid`.
+- [User attributes](/references/workspace/user-attributes) applied to the JWT hide metrics and dimensions whose `required_attributes` rules the embedded viewer does not satisfy, both in the catalog listing and in any Explore session launched from it.
+- Metric previews and Explore queries run with the write actor's permissions (when `writeActions` is set) plus any `userAttributes` filters, so embedded viewers only see rows and columns they are entitled to.
+- When `canExplore` is not set to `true`, the catalog is read-only — the **Explore from here** action is hidden and Explore routes reject the token.
+- Metrics catalog tokens are rejected by dashboard, chart, AI agent, and data app routes, and vice versa.
+
+## Example: read-only metrics catalog
+
+To publish a browse-only catalog without Explore or chart saving, mint a token with just `type` and `projectUuid`:
+
+```javascript
+const token = jwt.sign({
+  content: {
+    type: 'metricsCatalog',
+    projectUuid: 'your-project-uuid',
+  },
+  userAttributes: {
+    tenant_id: 'tenant-abc',
+  },
+}, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });
+```
+
+Embedded users can search and preview metrics, but the **Explore from here** action is hidden and Explore routes reject the token.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="React SDK reference" icon="react" href="/references/react-sdk#lightdashmetricscatalog">
+    Full prop reference for the Lightdash.MetricsCatalog component
+  </Card>
+
+  <Card title="Embedding reference" icon="book" href="/references/embedding#metrics-catalog-token">
+    Complete JWT structure for metrics catalog embed tokens
+  </Card>
+
+  <Card title="Write actions" icon="pen-to-square" href="/references/embedding#write-actions">
+    Configure the actor and destination space for embedded writes
+  </Card>
+
+  <Card title="User attributes" icon="shield-check" href="/references/workspace/user-attributes">
+    Implement row- and column-level security in embedded content
+  </Card>
+</CardGroup>

references/embedding.mdx

@@ -31,7 +31,7 @@ Embedded Lightdash content is available to view by anyone (not just folks with a
 
 ## Known limitations
 
-- Embedding works for dashboards, charts, and [data apps](/guides/data-apps). To embed explores, use the `canExplore` flag in a dashboard.
+- Embedding works for dashboards, charts, [AI agents](/guides/embedding/ai-agents), the [metrics catalog](/guides/embedding/metrics-catalog), and [data apps](/guides/data-apps). To embed explores, use the `canExplore` flag in a dashboard or metrics catalog token.
 - The **Filter dashboard to** option when clicking on individual chart segments will not work on embedded dashboards.
 
 If you're interested in embedding and one or more of these items are blockers, please reach out.
@@ -62,7 +62,7 @@ All tokens share these fields:
 {
   content: {
     // Content configuration (required)
-    type: 'dashboard' | 'chart' | 'aiAgent' | 'apiAccess',
+    type: 'dashboard' | 'chart' | 'aiAgent' | 'metricsCatalog' | 'dataApp' | 'apiAccess',
     projectUuid?: string,
     // ... type-specific fields
   },
@@ -304,6 +304,71 @@ const token = jwt.sign({
 }, SECRET, { expiresIn: '1h' });
 ```
 
+### Metrics catalog token
+
+For embedding the project [metrics catalog](/get-started/develop-in-lightdash/how-to-create-metrics) so embedded users can browse metrics and, optionally, continue into Explore. See [Embedding the metrics catalog](/guides/embedding/metrics-catalog) for the full walkthrough.
+
+```typescript
+{
+  content: {
+    type: 'metricsCatalog',
+
+    // Project identifier (required — pins the catalog to a single project)
+    projectUuid: string,
+
+    // Allow embedded users to open Explore from a metric (optional)
+    canExplore?: boolean,
+  },
+
+  // Optional: enable saving charts from the embedded Explore. Required only
+  // when canExplore is true and you want embedded users to save results.
+  writeActions?: {
+    spaceUuid: string,
+    serviceAccountUserUuid?: string,
+    userUuid?: string,
+  },
+
+  // Optional: row- and column-level filtering for the embedded viewer
+  userAttributes?: {
+    [attributeName: string]: string,
+  },
+
+  // Optional: user information surfaced in audit/analytics
+  user?: {
+    externalId?: string,
+    email?: string,
+  },
+}
+```
+
+<Info>
+Metrics catalog tokens only authorize the metrics catalog surface (and, when `canExplore` is `true`, the embedded Explore launched from a metric). Dashboard, chart, AI agent, and data app tokens are rejected by the metrics catalog routes, and metrics catalog tokens are rejected on other embed routes.
+</Info>
+
+**Example:**
+
+```javascript
+import jwt from 'jsonwebtoken';
+
+const token = jwt.sign({
+  content: {
+    type: 'metricsCatalog',
+    projectUuid: 'your-project-uuid',
+    canExplore: true,
+  },
+  writeActions: {
+    serviceAccountUserUuid: 'service-account-user-uuid',
+    spaceUuid: 'destination-space-uuid',
+  },
+  userAttributes: {
+    tenant_id: 'tenant-abc',
+  },
+  user: {
+    email: 'customer@example.com',
+  },
+}, SECRET, { expiresIn: '1h' });
+```
+
 ### Data app token
 
 For embedding a [data app](/guides/data-apps) as standalone content in an iframe (no dashboard). See [How to embed data apps](/guides/embedding/data-apps) for the full guide.

references/react-sdk.mdx

@@ -90,6 +90,7 @@ The Lightdash SDK exports components for embedding Lightdash content and hooks f
 - `Lightdash.Chart` - Embed individual saved charts
 - `Lightdash.Explore` - Embed interactive data exploration interface
 - `Lightdash.AiAgent` - Embed an AI agent so users can chat with their data
+- `Lightdash.MetricsCatalog` - Embed the project metrics catalog so users can browse and explore metrics
 - `Lightdash.useLightdashContent` - List spaces, dashboards, charts, and data apps for a custom content catalog
 - `Lightdash.useLightdashAiAgentThreads` - List an embed user's previous AI agent threads to build a thread history UI
 
@@ -567,6 +568,76 @@ export function generateAiAgentToken() {
 
 See [Embedding AI agents](/guides/embedding/ai-agents) for the full guide and [AI agent token](/references/embedding#ai-agent-token) for the complete JWT structure.
 
+### Lightdash.MetricsCatalog
+
+Embed the Lightdash [metrics catalog](/get-started/develop-in-lightdash/how-to-create-metrics) so embedded users can browse the metrics defined in a project, preview them, and — when the JWT allows it — continue into Explore without leaving your app.
+
+The component renders the catalog inside an iframe. When a viewer clicks **Explore from here** on a metric, the SDK swaps in an embedded Explore view; a **Back** action returns them to the catalog.
+
+#### Props
+
+```typescript
+type MetricsCatalogProps = {
+  // Required
+  instanceUrl: string;              // Your Lightdash instance URL
+  token: string | Promise<string>;  // JWT with content.type: 'metricsCatalog'
+
+  // Optional
+  theme?: 'light' | 'dark';         // Force light or dark color scheme
+  styles?: {
+    backgroundColor?: string;       // Background color or 'transparent'
+    fontFamily?: string;            // Font family for all text
+  };
+};
+```
+
+<Info>
+`Lightdash.MetricsCatalog` does not accept `filters`, `contentOverrides`, or `onExplore`. The catalog and the embedded Explore it launches are managed inside the component.
+</Info>
+
+#### Basic usage
+
+```tsx
+import Lightdash from '@lightdash/sdk';
+
+function MyMetricsCatalog() {
+  return (
+    <Lightdash.MetricsCatalog
+      instanceUrl="https://app.lightdash.cloud"
+      token={generateMetricsCatalogToken()} // Server-side function
+    />
+  );
+}
+```
+
+#### Token generation for the metrics catalog
+
+Metrics catalog embeds require a JWT with `content.type: 'metricsCatalog'` and a `projectUuid`. Set `content.canExplore` to `true` to let embedded users open Explore from a metric, and include a `writeActions` claim if you want them to save the resulting charts back to Lightdash.
+
+```javascript
+// Backend API endpoint
+import jwt from 'jsonwebtoken';
+
+export function generateMetricsCatalogToken() {
+  return jwt.sign({
+    content: {
+      type: 'metricsCatalog',
+      projectUuid: 'your-project-uuid',
+      canExplore: true,
+    },
+    writeActions: {
+      serviceAccountUserUuid: 'service-account-user-uuid',
+      spaceUuid: 'destination-space-uuid',
+    },
+    userAttributes: {
+      tenant_id: 'tenant-abc',
+    },
+  }, process.env.LIGHTDASH_EMBED_SECRET, { expiresIn: '1h' });
+}
+```
+
+Omit `canExplore` (or set it to `false`) to publish a read-only browse experience. See [Embedding the metrics catalog](/guides/embedding/metrics-catalog) for the full guide and [Metrics catalog token](/references/embedding#metrics-catalog-token) for the complete JWT structure.
+
 ## API hooks
 
 ### Lightdash.useLightdashContent