docs: data apps editor role, viz portability, theme size limit

Author: mintlify[bot]

guides/data-apps.mdx

@@ -257,7 +257,7 @@ lightdash download --apps-only --apps 8f2b1c4d-1111-2222-3333-444455556666
 
 Each app is written to `lightdash/apps/<slug>/`, where `<slug>` is derived from the app's name. Every folder is a locally buildable project:
 
-- `lightdash-app.yml` — the manifest, including the `appUuid` that identifies the app when you re-upload it, plus editable `name` and `description` fields.
+- `lightdash-app.yml` — the manifest, including the `appUuid` that identifies the app when you re-upload it, plus editable `name` and `description` fields. For [data app visualizations](/guides/data-apps/visualizations), the manifest also carries a `vizSchema` field describing the declared fields (dimensions, metrics, series) the viz needs — the schema is stored in the database, not the source tree, so the CLI persists it here to round-trip a viz through download and upload.
 - `src/` — the app's source tree (React components, styles, etc.). **This is the only directory you should edit.**
 - `package.json`, `README.md`, `.gitignore`, `AGENTS.md`, and `.claude/skills/` — a template that lets you install dependencies and run `pnpm build` locally to sanity-check that the source compiles. Editing these files has no effect on the deployed app — the server rebuilds against its own trusted template.
 - `.lightdash/context/` — a read-only, point-in-time snapshot of the source project so you (or an AI agent) have the context needed to edit the app: `semantic-layer.yml` (tables, dimensions, metrics you can query), `parameters.yml`, `prompt-history.md`, and `theme/` styling assets. Re-download to refresh.
@@ -274,6 +274,8 @@ Once an app is on disk you can iterate on it locally:
 
 The bundled `.claude/skills/` and `AGENTS.md` files describe the SDK surface and this workflow so coding agents (Claude Code and similar) can help you edit apps locally without extra prompting.
 
+Data app visualizations follow the same loop: the download writes the viz's declared field schema into `lightdash-app.yml`, and the upload sends it back so the viz shows up in the viz picker on the destination. If you edit the manifest's `vizSchema` directly, the upload validates it and rejects malformed schemas. Bundles downloaded before viz schemas round-tripped have no `vizSchema` field — re-download from the source project to pick it up before uploading elsewhere.
+
 ### Uploading an app
 
 Use `lightdash upload --apps` to send your local changes back:

guides/data-apps/themes.mdx

@@ -20,6 +20,21 @@ A theme is a bundle of resources the agent uses when it builds an app:
   The quality of a theme depends largely on the specificity of the instructions in `skill.md` and the extra instructions field. The more concretely you describe how the agent should use the CSS, fonts, and images - and what the app should feel like - the more consistent your results will be.
 </Tip>
 
+### Size limit
+
+A theme's files are streamed into the app sandbox on every generation, so an oversized theme times out on the copy before the agent runs. To keep applies fast and predictable, themes have a hard limit of **100 MB total across all uploaded assets** (fonts, images, and instruction files combined). Individual files are capped at 10 MB.
+
+The cap is on aggregate bytes, not file count — a theme with many small text files is cheap, but a handful of large images can blow past it. Compress or downscale image assets, or split them into a smaller curated set, if you're near the limit.
+
+The limit is enforced at four points, all of which fail fast with a specific error message:
+
+- When you upload a file to the theme.
+- Before the upload dialog submits, as a client-side pre-check.
+- Right before a build applies the theme.
+- As a final backstop inside the generation pipeline.
+
+If you try to apply a theme that has grown past 100 MB (for example, because assets were added over time), the app generator surfaces the specific limit error — for example, *`Theme "…" totals 128 MB of assets, above the limit of 100 MB. Remove some assets and try again.`* — instead of a generic build failure. Remove or shrink some assets on the theme, then retry the app build.
+
 ## Extra instructions
 
 Each theme has an **Extra instructions** field that you can edit directly from the theme detail panel in **Settings → Themes**. These instructions are passed to the agent alongside any uploaded instruction markdown files when an app is built with the theme.

references/lightdash-cli.mdx

@@ -668,7 +668,7 @@ You can make changes to the code and upload these changes back to your Lightdash
   - (default: false)
   - strip per-value pivot series config from chart YAML so it's portable across projects. Cartesian chart series that are tied to specific pivot field values are rewritten to reference only the underlying x/y fields, and duplicates collapsed into a single entry. Use this when the source project's pivot values don't exist in the target project (for example, when reusing chart YAML as a template), so the upload doesn't fail or render with the original project's hardcoded series. Only applies to regular charts; SQL charts and dashboards are unaffected.
 - `--apps <appUuids...>`
-  - opt-in flag to also download specific [data apps](/guides/data-apps#data-apps-as-code) as code (enterprise only). Pass one or more app UUIDs to download just those apps — this is the only way to download apps that haven't been added to a space. Each app is written to `lightdash/apps/<slug>/` as a locally buildable project: `lightdash-app.yml` manifest, the app's `src/` tree, `package.json`, a read-only `.lightdash/context/` snapshot of the project's semantic layer, and agent skill files. The built output is not included — the server rebuilds it on upload.
+  - opt-in flag to also download specific [data apps](/guides/data-apps#data-apps-as-code) as code (enterprise only). Pass one or more app UUIDs to download just those apps — this is the only way to download apps that haven't been added to a space. Each app is written to `lightdash/apps/<slug>/` as a locally buildable project: `lightdash-app.yml` manifest, the app's `src/` tree, `package.json`, a read-only `.lightdash/context/` snapshot of the project's semantic layer, and agent skill files. For [data app visualizations](/guides/data-apps/visualizations), the manifest also carries a `vizSchema` field with the viz's declared fields so the viz round-trips to the destination on upload. The built output is not included — the server rebuilds it on upload.
 - `--include-apps`
   - (default: false)
   - opt-in flag to download every [data app](/guides/data-apps#data-apps-as-code) in the project that has been added to a space (enterprise only), capped at the first 10. Use `--apps <appUuids...>` to reach apps that aren't in a space, or to download more than 10.
@@ -785,7 +785,7 @@ If there have been changes made to a chart or dashboard in the application that
   - (default: false)
   - expect content to be organized in sub-folders matching the spaces in your project (use this if content was downloaded with `--nested`)
 - `--apps [appUuids...]`
-  - opt-in flag to also upload [data apps](/guides/data-apps#data-apps-as-code) as code (enterprise only). Bare `--apps` uploads every app folder under `lightdash/apps/`. Pass one or more app UUIDs to upload just those apps. The CLI posts each app's `src/` tree and returns immediately — the destination rebuilds the app in its sandbox and publishes a new version. The app shows a `building` status in the UI until the build finishes. Uploading to the same project appends a new version and applies any edits to the manifest's `name` or `description`; uploading to a different project prompts for confirmation (in non-interactive shells the app is skipped with an error unless you also pass `--create-new`) and creates a new app in the target. After any create, the CLI prints the new app's URL and offers to retarget the local `lightdash-app.yml` (updating `appUuid`, `projectUuid`, and `version`) so future uploads update the new app.
+  - opt-in flag to also upload [data apps](/guides/data-apps#data-apps-as-code) as code (enterprise only). Bare `--apps` uploads every app folder under `lightdash/apps/`. Pass one or more app UUIDs to upload just those apps. The CLI posts each app's `src/` tree and returns immediately — the destination rebuilds the app in its sandbox and publishes a new version. The app shows a `building` status in the UI until the build finishes. Uploading to the same project appends a new version and applies any edits to the manifest's `name` or `description`; uploading to a different project prompts for confirmation (in non-interactive shells the app is skipped with an error unless you also pass `--create-new`) and creates a new app in the target. After any create, the CLI prints the new app's URL and offers to retarget the local `lightdash-app.yml` (updating `appUuid`, `projectUuid`, and `version`) so future uploads update the new app. For [data app visualizations](/guides/data-apps/visualizations), the manifest's `vizSchema` is sent alongside the source and persisted on the new version — so a downloaded viz appears in the destination project's viz picker after upload without needing to be regenerated. Uploading requires the [`create:DataApp` scope](/references/workspace/roles), which is granted to Editor, Developer, and Admin roles.
 - `--create-new`
   - (default: false)
   - always create a new data app from the uploaded source instead of appending a new version to the app referenced by `lightdash-app.yml`. Combine with `--apps` and `--project` when copying an app to a different project or instance in a non-interactive shell.

references/workspace/roles.mdx

@@ -194,7 +194,7 @@ Project Admins can invite users to their project and assign users or [groups](/r
 | View Data App | <Icon icon="xmark" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |
 | Manage Data App | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |
 | Manage Data App Space | <Icon icon="xmark" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |
-| Create Data App | <Icon icon="xmark" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |
+| Create Data App | <Icon icon="xmark" iconType="solid" /> | <Icon icon="xmark" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |
 | View Data App Self | <Icon icon="xmark" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |
 | Manage Data App Self | <Icon icon="xmark" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |
 | View External Connection | <Icon icon="xmark" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> | <Icon icon="square-check" iconType="solid" /> |