> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getnao.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom stories

> Let the agent build interactive data apps, slide decks, and branded reports, and set up your story theme

A **custom story** is a small interactive app the agent writes, builds, and publishes from a chat. Where a [classic story](https://docs.getnao.io/nao-agent/chat/capabilities/stories.md) is a document of charts, tables, and text, a custom story can be a slide deck, a what-if simulator, a one-pager, or a dashboard with a layout of its own. It runs on the same SQL queries, so it can go [live](https://docs.getnao.io/nao-agent/chat/capabilities/stories.md#live-stories), be shared, and be refined in the chat like any other story.

## Examples

The same story, built and reworked in three messages.

**Dashboard**

*"Build a dashboard of revenue by country"*: filters, tabs, KPI tiles, and charts in one view.

![A revenue by country dashboard with filters, tabs, KPI tiles, and charts](https://mintcdn.com/naolabs/psTjh4h0MPmh-EWn/images/nao-agent/stories/custom-story-dashboard.png?fit=max\&auto=format\&n=psTjh4h0MPmh-EWn\&q=85\&s=dc5d08dab6cf4aae9b32557dde93fbb4)

**Slide deck**

*"Turn it into a slide deck for the board"*: five slides, one per insight, with slide navigation and full-screen mode.

![The same story turned into a slide deck](https://mintcdn.com/naolabs/psTjh4h0MPmh-EWn/images/nao-agent/stories/custom-story-slides.png?fit=max\&auto=format\&n=psTjh4h0MPmh-EWn\&q=85\&s=003ebcd81d100cab0e52f5cfa55906f3)

**Your brand**

*"Use our Kova brand design"*: the agent reads a brand file from the context and applies the fonts, colours, and logo to the whole story.

![The slide deck restyled with the Kova brand](https://mintcdn.com/naolabs/psTjh4h0MPmh-EWn/images/nao-agent/stories/custom-story-branded.png?fit=max\&auto=format\&n=psTjh4h0MPmh-EWn\&q=85\&s=3da6d45c0275333cd3a8163327fb30f3)

## When the agent builds a custom story

You don't need to choose the format yourself. The agent builds a custom story instead of a classic one when you ask for:

* a **custom story** or an **app**;
* a format with its own shape: **slides**, deck, presentation, one-pager, infographic, TV screen, scrollytelling;
* interaction beyond reading: **what-if** sliders or inputs, calculators, click-to-drill, cross-filtering between charts, toggles between metrics;
* a visual the [built-in chart types](https://docs.getnao.io/nao-agent/chat/capabilities/visualizations.md) don't have (funnel, cohort heatmap, gauge, timeline, calendar, flow) or a bespoke layout.

A report or dashboard of charts, tables, and text stays a classic story. Each request gets one story, in one format.

## Create and edit a custom story

1. Ask the agent in a chat, for example *"Build a what-if simulator for our pricing: let me change the price and churn and see the impact on ARR"*.
2. The agent runs the queries, writes the app, and publishes it. The story opens in the side panel, and a story card appears in the chat.
3. Keep asking in the same chat to change it: *"Add a country filter"*, *"Make it a 16:9 deck"*, *"Use a funnel instead of the bar chart"*. Each publish creates a new [version](https://docs.getnao.io/nao-agent/chat/capabilities/stories.md#versions).

Custom stories open in their own viewer and follow the same rules as classic stories for [sharing](https://docs.getnao.io/nao-agent/chat/capabilities/stories.md#sharing-a-story), [live refresh](https://docs.getnao.io/nao-agent/chat/capabilities/stories.md#live-stories), [scheduled delivery](https://docs.getnao.io/nao-agent/chat/capabilities/stories.md#scheduled-delivery), and the [library](https://docs.getnao.io/nao-agent/chat/capabilities/stories.md#stories-library), where they get light and dark thumbnails and can be found with the **Custom** type filter.

> [!TIP]
>
> Need a fixed-size layout, for example for a TV screen or a deck? Ask the agent for one: the story is then scaled to fit the screen instead of reflowing.

## Enable custom stories

> [!NOTE]
>
> Custom stories are a **beta** feature. They are on for nao Cloud. On a self-hosted deployment, they are **off by default**: set `BETA_CUSTOM_STORIES_ENABLED=true` to enable them.

Which members can create custom stories is controlled per [user group](https://docs.getnao.io/nao-agent/chat/admin/user-groups.md) with the **custom story creation** feature. Members without it can still view the custom stories shared with them.

## Story theme

The story theme is your project's design system for stories: logo, colours, fonts, header, and block styles. It applies to every story in the project, **classic and custom**, in both a **light** and a **dark** variant. Classic stories follow it in the viewer, the preview, shared pages, and HTML, PDF, and email exports.

Only admins can edit the theme.

### Set up the theme

1. Open **Settings** -> **Appearance** and select the **Stories** tab.
2. In the **Story theme** card, use **Start from a brand** to generate a first theme (see below), or edit the values by hand.
3. Turn on **Apply to stories**.

Turn **Apply to stories** off to go back to the default nao look without losing your saved theme.

### Generate a theme from your brand

**Start from a brand** proposes a full theme from:

* **Theme instructions**: describe what you want, for example *"Dark and premium, navy with an amber accent"*. Instructions take priority over the other sources, and a theme can be generated from instructions alone.
* **Sources** (optional): a website URL, an image (PNG, JPEG, or WebP), a PDF such as your brand guidelines, or a brand asset ZIP. You can also choose **Use the white-label branding** (name, primary colour, and logo). The story logo is read as a source too.

Generated themes always keep a chart palette of at least 6 distinct colours, adjust an accent that is too close to the background, and keep any colours you explicitly ask for as given.

### Edit the theme by hand

* **Story logo**: PNG, JPEG, WebP, or SVG, up to 512 KB. It is shown in every story header and kept when you regenerate the theme.
* **Brand header**: header style (logo, name, or coloured band), brand name, and band colour.
* **Typography**: font, weight, case, italic, spacing, and size for each text role.
* **Blocks**: KPI tile style (highlight or tinted) and corner radius.
* **Controls**: radius for buttons and filter chips (`999` gives pills).
* **Variants**: use **Derive from the light variant** (or dark) to build one variant from the other.

The version menu records each generation's sources, instructions, and notes, and whether the theme was **Set by hand** afterwards. **Show what the generation kept** lists what nao took from your sources.

> [!TIP]
>
> The theme is applied to every story automatically. To brand a single story differently, ask the agent in the chat, for example *"Use our Kova brand design"*, and point it to a brand file in your context.

## Saved state

Custom stories can remember what viewers do between visits, such as filters, selections, and inputs. The agent decides what to save when it builds the story. There are two scopes:

* **Personal**: each viewer gets their own values back.
* **Shared**: one value for every viewer. Anyone viewing the story can change it for everyone.

Saved state works for the owner, read-only viewers, and share links. When there is no viewer (for example a delivered PDF), the story renders with shared state only.

Limits: keys up to 100 characters (letters, digits, `.`, `:`, `-`, `_`), values up to 32 KB, and 50 keys per story per scope.

Older custom stories that keep their UI state locally show a banner: "Viewers start this story from scratch on every visit." The owner can click **Remember state** to ask the agent to convert the story and republish it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.