Document Enterprise navbar/favicon branding on the Appearance page (+17 more)

agents/lightdash-mcp.mdx

@@ -267,7 +267,7 @@ When the header is set:
 - The `list_projects` tool is hidden from `tools/list`, so the AI assistant isn't steered toward another project.
 - Access to the project is still enforced by your user, API key, or service account's permissions — the header can't be used to access projects the caller can't already see.
 
-This is useful when you want each integration, workspace, or environment to be locked to one project (for example, a separate connector per project) without relying on the AI assistant to pick the right project.
+This is useful when you want each integration, workspace, or environment to be locked to one project (for example, a separate connector per project) without relying on the AI assistant to pick the right project. A user chooses this for their own integration; it isn't an admin-enforced restriction. To restrict which projects MCP clients can reach for everyone in your organization, see [Restrict MCP to specific projects](#restrict-mcp-to-specific-projects).
 
 The header value must be a valid project UUID. You can find the project UUID in the Lightdash URL when viewing a project (`/projects/<projectUuid>/...`).
 
@@ -398,6 +398,15 @@ Organization admins can turn MCP on or off for the whole organization with **All
 
 **Settings → MCP → Connect** always shows. **General** and **Analytics** show only when [AI features are enabled](/agents/set-up-agents#enable-ai-features) for your organization (on a self-hosted instance, [enable AI Analyst](/self-host/enterprise-features/ai-agents#enable-ai-analyst)). **General** needs an organization admin or developer role. **Analytics** also shows to people who can manage agents in at least one project.
 
+### Restrict MCP to specific projects
+
+The **Project access** card in **Settings → MCP → General** lets organization admins choose which projects MCP clients can reach, separately from each user's project access in the Lightdash app. It's disabled while **Allow MCP access** is off.
+
+- **All projects** (the default): MCP clients can reach any project the connecting user, API key, or service account already has access to in Lightdash.
+- **Only selected projects**: MCP clients can only reach the projects you add to **Allowed projects**. Picking this mode requires selecting at least one project before it applies. A new project stays unavailable to MCP clients until an admin adds it here, even if users already have access to it in the app. If you remove every project from the list, MCP clients can't access any project — the card shows a "No projects allowed" warning until you add one back.
+
+This setting only limits what MCP clients can reach; it doesn't change a user's access in the Lightdash app, and it doesn't grant access either — a caller still needs its own permissions on a project to use it over MCP. It's the admin-enforced counterpart to a user [pinning a project with the `X-Lightdash-Project` header](#pin-a-project-with-the-x-lightdash-project-header) on their own integration.
+
 ## What it can do
 
 ### Core capabilities
@@ -424,7 +433,7 @@ An active project must be set before MCP can retrieve any data. Your AI assistan
 
 #### Query execution
 
-- **Run metric query** - Execute queries using your semantic layer's metrics and dimensions. Completed results include a best-effort `exploreUrl` so you can open the query in Lightdash to keep exploring.
+- **Run metric query** - Execute queries using your semantic layer's metrics and dimensions. Returns up to 5,000 rows by default; a requested limit above that is clamped to the cap without the response saying so. Completed results include a best-effort `exploreUrl` so you can open the query in Lightdash to keep exploring. MCP has no export or download tool — for a larger or complete extract, open the `exploreUrl` and [download the results](/explore/share-charts#download-results-or-a-chart-image) with **All results** (bounded by the instance's [export limits](/workspace-admin/export-limits)), or set up a [scheduled delivery](/explore/create-scheduled-deliveries) as CSV or Excel.
 - **Render chart** - Render a visualization (tables, bar charts, line charts, pie charts, and more) for a completed metric query result in MCP App-capable clients (e.g., Claude). Call this after a metric query finishes when you want a visual chart; the query is not re-executed. It can also render with one of the project's [custom chart types](#chart-types). SQL Runner results are not supported by `render_chart`.
 - **Run SQL** - Execute arbitrary SQL queries directly against the project's data warehouse. Useful for ad-hoc analysis or queries that don't fit the explore-based model. Returns up to 500 rows by default (configurable up to 5,000). Completed results include a best-effort `sqlRunnerUrl` so you can open the compiled SQL in [SQL Runner](/explore/sql-runner).
 - **Get query result** - Poll for the result of a long-running query. `run_metric_query` and `run_sql` each wait about 50 seconds for the query to finish; if it hasn't, the response has no `exploreUrl` (or `sqlRunnerUrl`) yet — just a `queryUuid` to poll. Call `get_query_result` with that `queryUuid` until the warehouse completes the query — so long queries don't time out the session. The completed (`done`) response includes the same best-effort `exploreUrl` (or `sqlRunnerUrl` for `run_sql` queries) as a synchronously-completed call.

agents/set-up-agents.mdx

@@ -151,16 +151,18 @@ To run Ask AI on Claude models in your own AWS account and keep inference in one
 
 - **Name** — how projects refer to the credential, for example `Europe (Frankfurt)`.
 - **AWS region** — Tokyo, Osaka, Frankfurt, Ireland, N. Virginia or Oregon. Enable the models you want in that region of your AWS account first.
-- **Inference geography** — where Bedrock may process requests. It defaults to the narrowest choice for the region (Japan, United States or Europe); **Global** widens it.
+- **Inference geography** — where Bedrock may process requests; the AWS region above only decides which endpoint receives them. It defaults to the narrowest choice for the region: a Tokyo or Osaka credential can keep requests inside Japan (the Tokyo and Osaka inference profiles only), and a US or EU credential keeps requests inside that geography. **Global** widens it to any supported region worldwide. Pick the narrowest geography your data-residency or compliance review requires.
 - **Bedrock API key** — a Bedrock API key, not an AWS access key pair.
 - **Allowed models** — the Claude models users can pick.
 
-You can add several credentials. The organization default serves everything without its own selection, including Slack routing and thread titles. Organization admins and developers can point a project at another credential in **Project settings** → **AI region**, and, when there's more than one credential, an agent under **AI provider credential** in its settings.
+You can add several credentials. The first one you create becomes the organization default unless you clear **Set as organization default** in the Add credential dialog, so you can register a credential without putting it into use. The default serves everything without its own project-level selection, including Slack routing and thread titles. Organization admins and developers can point a project at another credential in **Project settings** → **AI region**, and, when there's more than one credential, an agent under **AI provider credential** in its settings.
 
 If custom AI providers aren't enabled for your organization, **Project settings** → **AI region** shows *Custom AI providers are not enabled for this organization.* A project already pointed at another credential then has no AI features until you clear the selection or custom providers are turned on.
 
 While a default Bedrock credential is set, Bedrock is the only provider Ask AI uses and nothing falls back to other providers. Agents set to another provider's model stop working until you change their model, and verified-answer search and [AI writeback](/agents/ai-writeback) are unavailable.
 
+You can also list, create, update and delete Bedrock credentials through the API, under `/api/v1/ai/provider-credentials`, authenticated with a [personal access token](/personal-settings/create-personal-tokens). See the [API reference](/api-reference/v1/introduction) — this is the route to manage credentials from Terraform or another IaC tool.
+
 #### Key-gated models
 
 Some models are hidden by default and only become selectable once your BYO key can access them. Currently this applies to **Claude Opus 4.8** — after you save an Anthropic key, Lightdash verifies access against Anthropic's models API and unlocks the preset automatically.

data-apps.mdx

@@ -154,7 +154,7 @@ To duplicate, you need **view** access on the source app and **create** permissi
 
 The inspector is a tabbed network panel that captures everything the running app talks to. Open it from **View network** in the preview header.
 
-- **Queries** - every metric query the app runs against your semantic layer, including the underlying query definition, the fields it's pulling, and the rows it gets back. Live-linked charts show up here too. Use it to verify the app is asking for the right data, debug unexpected numbers, or sanity-check performance.
+- **Queries** - every metric query the app runs against your semantic layer, including the underlying query definition, the fields it's pulling, and the rows it gets back. Live-linked charts show up here too. Use it to verify the app is asking for the right data, debug unexpected numbers, sanity-check performance, or spot a query returning far more rows than the app needs (see [App is slow to load](#app-is-slow-to-load)).
 - **Requests** - every external fetch the app makes at runtime through a linked external connection, with the method, path, status, response, and round-trip duration. Use it to confirm the app is calling the right endpoint and that the response shape matches what the UI expects. The inspector only ever sees the connection alias and path - credentials are injected server-side, so they're never displayed here.
 
 Both tabs are always visible so you can see at a glance whether the app has run any queries or external requests yet. Entries are held in-memory and cleared when you refresh the preview or load a new version unless you turn on the **Persist** toggle in the panel.
@@ -357,6 +357,7 @@ On self-hosted instances, `LIGHTDASH_APP_CAPTURES_ENABLED=false` turns this off
 - **Describe drill-downs in full.** Say what a click opens, what it shows, and what data it needs - for example, "clicking a month opens a dialog with that month's daily order count".
 - **Use the network inspector early.** If something looks off, check the queries and external requests the app is running before tweaking the prompt.
 - **Build what-if inputs on existing metrics.** The app gets each query's rows in its own code, so a slider or input that scales a result (for example, a growth rate applied to revenue) can work on any metric you already have, with no dbt changes. You only need [parameters](/semantic-layer/parameters) when the input should change the query's SQL itself; the app then passes the value with the query.
+- **Keep query results small.** An app tile loads a query's results from the backend 500 rows at a time, so a query returning tens of thousands of rows makes hundreds of sequential requests before the app can render - even when the warehouse query itself runs in seconds. Aggregate, filter, or lower the query's row limit so it returns hundreds of rows rather than tens of thousands. If you need full row-level detail, show a summary first and load the detailed rows on demand, for example filtered to whatever the user clicks.
 
 ## Troubleshooting
 
@@ -373,6 +374,19 @@ To fix it, allowlist Lightdash in Malwarebytes Browser Guard:
 3. Add the Lightdash domain you're using (for example, your Lightdash Cloud subdomain or your self-hosted Lightdash URL).
 4. Reload the page.
 
+### App is slow to load
+
+A data app loads every row a query returns before it renders anything. Results come back in pages of 500 rows, fetched one after another, so load time grows with how many rows the query returns - not with how long the warehouse takes to run it. A query that returns around 91,000 rows takes roughly 180 sequential page requests to finish loading, which can take minutes even when the warehouse answers the query itself in about 15 seconds.
+
+Open the [network inspector](#network-inspector)'s Queries tab and check each query's row count to find the one that's slowing the app down.
+
+To fix it, return fewer rows from the query itself:
+
+- Ask the agent to aggregate or filter the data in the query, rather than fetching everything and filtering in the app.
+- Lower the query's `.limit()` so it returns hundreds of rows, not tens of thousands.
+
+If the app needs row-level detail, ask the agent to show a summary first and load the detailed rows separately - for example, only the rows for whatever the user clicks on.
+
 ## Self-hosting
 
 Data apps are enabled by default on Lightdash Cloud. If you're running a self-hosted enterprise instance, see [data apps on self-hosted Lightdash](/self-host/enterprise-features/data-apps) for the configuration you'll need to add — a [sandbox provider](/self-host/customize-deployment/sandboxes), a Claude provider, and an S3 bucket for the built artifacts.

embed/reference.mdx

@@ -864,6 +864,14 @@ Configure embed scopes in the **Embedding** section of a [custom role](/workspac
 
 Permissions from the actor's organization and project roles are additive. Removing a scope from one role does not revoke a grant from another role. When testing a restrictive custom role, make sure the actor has no other role that still grants the capability.
 
+### Supporting many embedded end users
+
+The actor doesn't have to be one Lightdash user per embedded end user. When your app has a handful of permission profiles shared by many end users, create one service account per profile — for example `viewer`, `analyst`, `admin` — give each a custom role with the embed scopes for that profile, and have your backend pick the matching `serviceAccountUserUuid` when it signs each end user's token. A new end user reuses an existing profile's service account: there's no Lightdash user to create and no code change.
+
+If your embedded end users are themselves Lightdash users, look up the signed-in user's Lightdash user UUID instead and set it as `writeActions.userUuid` when you sign their token.
+
+Either pattern depends on signing the JWT per session or request, with a short `expiresIn`, rather than generating one token once and reusing it — that's what lets your backend resolve each request to the matching actor as end users and profiles change. The viewer's [`user.externalId`](#user-metadata) can still carry your own user identifier for tracking; it isn't the role-bearing actor.
+
 ### Dashboard capabilities
 
 In `'roles'` mode, only the actor's embed scopes grant capabilities. JWT interactivity flags are ignored whether they are `true`, `false`, or omitted. For example, CSV export requires `view:EmbedCsvExport` even when the token contains `canExportCsv: true`. In `'default'` mode, the scope is ignored and the JWT flag decides.

explore/metrics-catalog/curate-the-catalog.mdx

@@ -4,7 +4,7 @@ description: "Browse, explore, and curate your metrics in the Metrics Catalog"
 doc-type: tutorial
 ---
 
-## Browsing the catalog
+## Browsing the catalog (test)
 
 Browse all the project metrics you have access to (based on permissions and user-attributes) in the **Metrics Catalog**.