Presentations

A presentation is a curated collection of key results drawn from across sessions and projects. Presentations let users assemble findings into a coherent narrative without duplicating data — each key result in a presentation references the original source, and any updates to the source are automatically reflected.

Creating a Presentation

From the Presentations list (accessible via the sidebar), click New Presentation. Provide:

• Name — A descriptive title for the presentation.
• Description — Optional context about what the presentation covers.
• Tags — Optional tags for categorization. Users can select from existing tags or create new ones. Tags are displayed as pills on the presentation list and detail views.
• Visibility — Who can see the presentation.
• Shared Users — Specific users granted access (when visibility is not Private).

Adding Key Results

Key results can be added to presentations in two ways:

1. From the key result menu — Each key result has a menu button that includes an Add to Presentation option. This lets you quickly add the key result to a presentation without navigating to the edit page.
2. From the key result edit panel — When editing a key result, a Presentations section lists all presentations owned by the current user. Check a presentation to add the key result; uncheck to remove it.

A single key result can belong to multiple presentations.

Adding a key result to a presentation creates a lightweight reference — the presentation stores only the link, not a copy of the data. When the presentation is viewed, each key result's title, description, SQL, results, chart configuration, and display type are pulled from the source record.

Viewing a Presentation

The presentation detail page displays key results organized into slides. Navigation controls (Prev / Next) let you step through slides one at a time, with a counter showing the current position (e.g., "Slide 2 of 5").

Each slide renders its key results according to the slide's layout (see Slide Layouts below). If no layout has been set, the slide falls back to a simple list of result titles.

If a presentation has no slides yet, an empty state message is shown with a link to the builder for the presentation owner.

Data Coalescing

Presentations use a coalescing strategy for key result data. Each presentation-to-key-result link can optionally store overrides for any field (SQL, results, title, description, display type, chart instructions). When rendering, the presentation uses the override if present, falling back to the source key result's value. Currently, overrides are not set through the UI — all fields coalesce to the source — but the architecture supports per-presentation customization in the future.

If a source key result is removed from its session (via the session's key result edit panel), the presentation link is retained but the key result will no longer appear in the presentation detail view, since all coalesced fields will be null.

Visibility and Sharing

Presentations have two visibility levels:

• Private — Only the presentation owner can see it.
• Visible — Shared users can see the presentation and its key results.

When visibility is set to Visible, you can select specific users to share with.

Slide Layouts

Each slide has a layout that controls how its key results are rendered. All layouts render each key result's description as annotation text below its content.

The supported layouts are:

• chart — A single result displayed as a chart. Best used with one result per slide.
• chart-plus-single-values — The slide is split into two areas. Non-single-value results (bar, column, timeseries, or scatter charts) appear in the main chart area. Results with singleValue chart type appear in a side column as key metrics.
• data-table — Each result on the slide is rendered as a data table.
• chart-with-associated-table — A single result is displayed as both a chart and a data table below it. Best used with one result per slide.
• side-by-side-charts — Two charts rendered in a 50/50 horizontal split. Expects exactly 2 results, both chart types (bar, column, timeseries, or scatter).
• single-value-grid — A grid of single-value KPIs. Expects 2–6 results, all with singleValue chart type. Automatically arranges into 2 or 3 columns based on the number of results.
• stacked-charts — Two charts stacked vertically (top/bottom). Expects exactly 2 results, both chart types (bar, column, timeseries, or scatter).

If a slide has no layout set, it falls back to displaying result titles only.

Presentation Builder

Presentation owners can use the Build button on the presentation detail page to open an AI-powered workspace for organizing slides. The builder helps arrange key results into slides with appropriate layouts.

How It Works

The builder interface has two panels:

• Left panel — A conversation with the AI, focused on presentation layout rather than database queries.
• Right panel — A live preview of the current slide layout, updated in real time as the AI makes changes. Each slide is shown with a skeleton rendering of its layout so you can see the structure before viewing the full presentation.

Available Tools

The AI has access to the following presentation-specific tools:

• LIST_RESULTS — Lists key results available for the presentation. By default shows all results with their UUID, title, chart type, and whether they are assigned or unused. Accepts an optional --unused-only flag to show only results not yet assigned to a slide.
• GET_RESULT_DETAILS — Returns the full details of a specific key result given its UUID, including its description, SQL query, and all data rows.
• ADD_RESULTS_TO_SLIDE — Assigns key results to a slide by number (1-based). If a result is already on a different slide, it is automatically moved. Moving a result that leaves its previous slide empty causes that empty slide to be automatically removed and remaining slides to be renumbered. Supports a --insert flag to insert a new slide at a given index (pushing existing slides down) instead of replacing the slide at that index.
• DELETE_SLIDE — Removes a slide by number (1-based). The key results on the deleted slide are moved back to the unused results pool. Remaining slides are renumbered.
• SET_SLIDE_LAYOUT — Sets the layout type for a slide. See Slide Layouts above for the supported options. The tool validates that the assigned results are a good fit for the chosen layout and returns warnings if the result chart types don't match what the layout expects (e.g., non-single-value results in the metrics column of chart-plus-single-values).
• STYLE_RESULT — Updates the title, description, or chart rendering instructions for a specific result within the presentation. Uses CLI-style flags: --uuid (required), --title, --description, --chart_instructions (at least one of the latter three must be provided). Pass an empty string to clear a field (e.g. --description ""). Supported chart types:
  • bar — requires non-empty categoryFields and 1–2 numeric measureFields.
  • timeseries — requires categoryFields where the first field is a date, and exactly 1 numeric measureFields.
  • scatter — categoryFields optional, exactly 2 numeric measureFields.
  • singleValue — categoryFields omitted or empty, exactly 1 measureFields, query must return exactly 1 row.
• PROMPT_USER — Communicates findings or asks for clarification.

Interrupting the Builder

While the AI is working (making tool calls and updating slides), the presentation owner can click the Interrupt button to stop the AI mid-build. The button appears next to the "Thinking..." indicator whenever the builder is actively running.

When interrupted, the AI stops at its next tool call boundary, acknowledges the interruption, and asks how you would like to proceed. Any layout changes already made before the interruption are preserved.

Persistence

Conversation history is persisted automatically. If you leave the builder and return later, the conversation resumes where you left off. Layout changes made by the AI are saved to the presentation immediately.

Editing and Deleting

Presentation owners can edit the name, description, tags, visibility, and shared users from the presentation detail page via the Edit Presentation button. The edit form also provides a Delete Presentation option, which soft-deletes the presentation. Deleting a presentation does not affect the source key results.

Access Control

• Authenticated users can view presentation lists and presentation details (subject to visibility settings).
• Architects can create, edit, and delete presentations, and add or remove key results.