Investigation Storyboards

An Investigation Storyboard turns an investigation into a short sequence of scenes that explain what happened, what was checked, what was ruled out, and what is still open. Each scene has a one-sentence statement and its own interactive visual, and every number in it traces back to an evidence receipt: a record of the tool call that produced it.

Your investigating agent authors the view and the argument. Cardinal owns the runtime and the evidence. Claude decides which scenes to show and how to draw them, whether that is a timeline, a trace waterfall, or the pods of a Kubernetes cluster drawn inside their nodes. It cannot supply the numbers itself: every value it shows comes from a receipt, or from arithmetic Cardinal performs over receipts.

A storyboard is neither a dashboard nor a transcript. An investigation of 70 queries and three abandoned paths might become six scenes, and a wrong turn is kept only when a reader needs to see why it was ruled out. A storyboard may end on open when the evidence doesn’t support a root cause.

Live investigation, session-owned visualization

Connected agent sessions record findings, decisions, and cited evidence in the same private Investigation as work proceeds. Activity stays live. The visualization is authored by the agent in your session, using the context of the work and the evidence it collected.

Ask your agent to publish the storyboard when the investigation is ready. The storyboard skill first creates or updates the scenes from the latest findings and cited evidence, renders previews, inspects them, and refines the visualization. It then validates and publishes the completed act. The agent does not offer an update at the end of each turn or run a stop-hook prompt. You can request a visualization update without publishing; that leaves a draft private.

The UI displays the storyboard and its activity; it has no Generate or Update visualization controls. The server stores the authored scenes, resolves evidence bindings, and validates them. It does not run a second model to generate visuals. An ended session must be resumed in your agent to author further updates.

The storyboard viewer shows only the storyboard. To follow the work as it happens, open Investigation from the viewer header. The Investigation page is a live timeline of what each participant recorded, grouped by day and author: findings, hypotheses, experiments, decisions and open questions, each with the evidence it cites. Members can send the investigating agent a question, a challenge or a note from the box at the bottom of the timeline. The agent sees it at its next step, and its reply appears under the message.

Delegate supervision

A challenge needs an answer, not an acknowledgment. The investigating agent must accept a challenge (saying what it will change) or decline it (saying why). Each challenge in the timeline shows where it stands: awaiting a position, accepted, addressed, declined, withdrawn, a directive, or overruled.

You can hand the back-and-forth to a second agent session (a supervisor) instead of settling every disagreement yourself:

1. Open the investigation’s Investigation page while signed in as its author and select Delegate supervision.
2. Name the supervisor, pick how long the delegation lasts (1 to 24 hours), and select Create token.
3. Copy the export CARDINAL_INVESTIGATION_TOKEN=… line it shows and run it in the supervisor’s session. The token is shown once.

The header then reads Supervised by the supervisor’s name, how the delegation was granted (web or CLI), and when it expires. Select Revoke to end it at once. A delegation you made on the web can only be revoked from your signed-in web session, so the agent, which works with your plugin’s key, cannot remove its own supervisor. The author can also grant supervision from the Cardinal CLI (investigation grant --scope supervise); such a grant can only rule on its own challenges.

Once the agent has taken a position on one of the supervisor’s challenges (accepted or declined), the supervisor can rule on it once:

• Challenge withdrawn: the challenge is closed.
• Directive: the challenge is upheld and binds the agent. The agent complies, or it cites one of your Decisions that the directive conflicts with. Only Decisions you posted from the Investigation page count: if the directive conflicts with something you told the agent in its session, post a Decision to settle it.

Directives are labelled Delegated supervision in the timeline. A directive never widens what the agent may do without your approval (deploys, merges and other actions its rules reserve for you). To settle any challenge or directive yourself, post a Decision that answers it; a decision overrules the supervisor. A supervisor can only rule on its own challenges, and supervision applies to one investigation at a time.

Delegated supervision needs Conductor and the Cardinal agent plugin at releases that include it. An older plugin that answers a challenge with noted is told to take a position and retries.

Publishing and sharing remain explicit actions. A publish request to the agent includes updating and previewing the visualization before publication. The UI’s Publish button checks and freezes existing scenes; it does not generate them. Empty acts cannot be published, and failed checks leave the draft private. Later visualization work uses an open draft or a new act on the same storyboard; published acts remain immutable.

Draft-status storyboards are visible only to their author, including in lists, search, and direct links. Once published, the storyboard is visible to members of its org and contains its authored visualization. Publishing does not create a public link.

Upgrade both Conductor and the Cardinal agent plugin to releases containing session-owned visualization. Older plugins may still describe server generation; restart or resume with the updated plugin to load the new workflow. See self-hosted setup.

Where you can use them

Writing a storyboard needs an API key; reading one doesn’t. Sign up at app.cardinalhq.io , then connect your agent with its Cardinal plugin: the plugin’s connect command stores an API key for your org. Anyone can read a published storyboard through a public link, without a Cardinal account.

The data doesn’t have to be in Cardinal: results of your other tools (Datadog, GitHub, a database, …) can be cited as evidence too.

Results of Cardinal’s own tools are always witnessed: Cardinal ran the call and recorded the result itself. See Use with Claude for setup, and Evidence and receipts for what each evidence tier means. claude.ai and Claude Desktop can’t author storyboards on Cardinal Cloud today: their connectors sign in with OAuth, which Cardinal Cloud doesn’t accept for writes.

You don’t need Cardinal Data Lake, or any integration, to use storyboards. An org with no integrations still gets the storyboard__* tools and Cardinal’s built-in common__* helpers.

Scenes

Each scene has:

• a statement that stands on its own without the visual;
• a state: supported, ruled_out, open, or context;
• optional claims that type each relationship honestly, so that “A preceded B” (precedes) is never silently upgraded to “A caused B” (causes); and
• a Canvas: the visual, drawn by Claude with HTML, SVG, d3 and Cardinal’s built-in visualizations (timeline, trace waterfall, infrastructure graph, compare, diff).

Consecutive scenes can share one Canvas, so the same picture stays on screen and each scene highlights, reveals, or annotates a different part of it.

Create a storyboard

After investigating, ask Claude in plain words:

Publish a storyboard of this investigation for the team.

Update the visuals and publish how we found the checkout regression.

Claude reads Cardinal’s authoring guide from the MCP server itself (storyboard__describe_grammar), so the same guidance reaches every client, with or without a plugin. In Claude Code, the plugin’s /cardinal:storyboard and /cardinal:canvas skills add the local preview loop. For an explicit publish request, Claude drafts or refreshes the scenes, validates them with Cardinal, previews, revises, and publishes. A request only to create or update visuals stops at the private draft:

investigation (collects receipt ids)
  → storyboard__find: is there a storyboard to update? (see Acts below)
  → storyboard__create a draft, or storyboard__add_act to a published one
  → cite evidence: witnessed receipts as they are, other results captured or reported
  → draft scenes and Canvas visuals
  → storyboard__preview: Cardinal validates the draft deterministically
      Claude Code with a plugin: your local Chrome renders each scene; Claude reads the PNGs
      elsewhere: open the draft_url Claude hands you to look at the visuals
  → revise → preview again → … → storyboard__publish
  → view_url

The first preview of a draft that binds datasets can take a while, because Cardinal re-runs those queries. Later previews reuse the frozen datasets.

Previews

Cardinal never renders a storyboard’s scenes on its servers. (The one image it draws itself is the text-only summary card of a link preview.) Where Claude can render locally, in Claude Code with the cardinal plugin, each scene is rendered on your machine in your own Chrome or Chromium, and the images go back to Claude so it can judge the scene as a reader would. The preview browser runs headless, with its OS sandbox on, networking locked off, and a throwaway profile. Setup details are on the Claude Code plugin page.

Everywhere else, the preview result says that no image was rendered and includes a draft_url: the draft in Cardinal’s viewer, which you open while signed in to review the visuals yourself. A storyboard with Draft status is visible only to its author, even if another org member has its link.

The publishing skill includes a preview and refinement pass. The server itself uses deterministic checks rather than rendered pixels to decide whether an act can be published.

Publish

Publishing runs Cardinal’s evidence checks. They are deterministic, and none of them looks at the rendered pixels. Publishing fails when any of these fails:

• The storyboard is complete and valid, and has at least one scene.
• Every cited receipt exists and belongs to your org.
• Every binding resolves against its receipt or frozen dataset, and every dataset binding has been materialized.
• Derived values (ratios, differences, counts, percent changes) are computed by Cardinal from the approved set of operations.
• Causal claims (causes, contributes_to) cite at least one supporting receipt.
• No evidence value is written inline into the scene or the Canvas source.
• The Canvas source passes static checks and uses only approved libraries.

Cardinal also returns warnings that don’t block publishing, and Claude treats them as problems to fix or explain. For example: a number in a scene’s statement that doesn’t match its bound evidence, numbers from different populations composed on one scale, a frozen dataset that disagrees with what Claude saw, or claim_reported_only, a claim whose supporting evidence was all reported by the model.

Published acts are immutable. A storyboard is published one act at a time, and once an act is published, edits to its scenes and a second publish of it are refused with a conflict. To update a published storyboard, ask Claude to add an act: the update is appended to the same storyboard, at the same view_url and public links. Publishing an act is also what keeps the receipts it cites past the 14-day window.

Acts

A storyboard is a sequence of acts. The first act is the storyboard you create and publish. When the investigation moves on (a fix ships, a rollback is verified, a new symptom turns up), Claude adds the next act to the same storyboard instead of starting a new one, so the whole story stays at one view_url and one set of public links.

act 1 draft ─publish─► act 1 published ─add_act─► act 2 draft ─publish─► act 2 published ─add_act─► …

• One open act at a time. storyboard__add_act opens the next act, with a title and an optional summary. It needs every earlier act to be published; while an act is open it answers open_act_exists, and Claude continues that act instead.
• Append-only. Scenes are added to the open act only. A published act’s scenes can’t be edited or removed (scene_published), and a new scene can’t reuse a published scene’s id. A new act can use a published act’s Canvas surfaces as they are, or define new ones; it can’t change a published surface (surface_published).
• Publishing publishes the open act. storyboard__publish runs the checks above on that act’s scenes. An act with no scenes is refused with act_empty. Once every act is published, writes are refused with published, and the message tells Claude to call storyboard__add_act.
• Public links don’t follow new acts on their own. A link keeps showing the acts it covered, and publishing an act onto a storyboard with live links asks whether to extend them. See Public links and new acts.
• Discarding a draft act. Only the open act can be discarded, never a published one. Its author can discard it: Claude calls storyboard__discard_act, and only from the connection that opened the act. An organization owner can discard an open act of a published storyboard from the viewer with Discard draft act, then Discard act n. Discarding removes the act’s scenes, the surfaces it defined, and its citations; the published acts stay as they are. Discarding act 1 of a storyboard that was never published deletes the draft storyboard.
• The time window can only widen. storyboard__add_act can pass a window that contains the storyboard’s current one; a narrower one is refused with window_must_widen.
• Receipts. A receipt cited by a published act is kept as long as the storyboard exists. Receipts cited only by the open act still expire at 14 days, so publishing an act that cites an expired one fails with receipt_not_found, and Claude re-runs the call.

In Claude Code, the cardinal plugin checks for a storyboard to update before it creates one, and asks you first; see Update an existing storyboard. Every act also records where it was written (repository, branch, pull request, the files its session edited), and can declare what it is about; both are visible only to members of your org. See Associations.

View storyboards

There is no sidebar entry. You reach storyboards through:

• the view_url Claude returns when it creates, previews, or publishes a storyboard (and the draft_url a preview returns); or
• the Storyboards button in the header of the Dashboards page.

The viewer is available to org members with the Member or Owner role. A draft-status storyboard is visible at the same link only to its author while Claude works on it, and refreshes as it writes. Published storyboards remain visible to org members, including a later open draft act: its scenes follow the published ones under an Act n · title divider, with a Draft act badge, and the storyboards list marks the storyboard Act n draft.

To show a published storyboard to someone outside your org, create a public link: the Share button in the viewer’s header, or ask Claude to share it. Readers need no account. On Cardinal Cloud links open on share.cardinalhq.io. Whether members can create them is an org setting that an owner controls; it is on by default in personal workspaces.

Reading a storyboard

• The scene list shows the thread of the argument, with each scene’s state. Use the arrow keys (← →) to move between scenes.
• Each scene shows its statement, state, claims, and any open questions, beside its Canvas. When a scene reveals its argument in steps, use the step controls.
• The header tallies the receipts behind the storyboard by evidence tier, for example 4 witnessed · 2 captured · 1 reported.
• Numbers in the Canvas are linked to their evidence. Hover one to see where it came from, and select it to open the evidence drawer on that value.
• The evidence drawer lists the scene’s bound values and cited receipts: tool, evidence tier, time window, arguments, the result the investigation saw, completeness, and any dataset drift. You can sort, filter, and inspect the rows of a frozen dataset.

Exploration is scoped to the evidence the storyboard captured. Questions that need new queries go back to Claude.

Each Canvas runs in a sandboxed frame with no network access, cookies, storage, or access to the rest of the page. It can only draw the evidence Cardinal resolved for it.

Folders

Storyboards can be organized into folders. Folders belong to the org, not to one person: every member sees the same tree.

• Nestable. A folder can hold subfolders, up to 8 levels deep. Names are up to 120 characters, can’t contain /, and are unique within their parent folder, ignoring case.
• One folder per storyboard. A storyboard sits in at most one folder. One that isn’t in a folder is at the top level, which is where every storyboard created before folders starts.
• Who can change them. Any member who can write storyboards (Member or Owner) can create, rename and move folders, and move storyboards between them.
• Only empty folders can be deleted. Move or delete what is inside first; otherwise Cardinal answers folder_not_empty. A folder can’t be moved into itself or one of its subfolders (folder_cycle), or deeper than 8 levels (folder_too_deep).
• Moving isn’t editing. Moving a storyboard doesn’t change its content, its Modified time or its public links.

There are no MCP tools for folders: you organize them in the list. storyboard__find and storyboard__get tell Claude which folder a storyboard is in (folder_path, for example Incidents/2026-Q3).

The storyboards list

/storyboards works like a file browser. A breadcrumb at the top (Storyboards › Incidents › 2026-Q3) shows where you are; select a segment to go back up. Subfolders are listed first, then storyboards:

• Sort by selecting a column header; select it again to reverse the order. Folders always stay above storyboards. The default is Modified, newest first, and your browser remembers your choice.
• Open a folder or storyboard with a double-click, or with Enter on the focused row. ↑/↓, Home and End move between rows.
• Select with a click; Cmd-click (Ctrl-click) adds or removes a row, Shift-click selects a range.
• New folder adds a folder in the current one and lets you type its name; Enter saves, Esc cancels. To rename a folder, press F2 on it or choose Rename from its row menu (…).
• Move the selected rows by dragging them onto a folder row or onto a breadcrumb segment (Storyboards is the top level), or with Move to… in the toolbar or a row menu. Move to… opens a folder tree you can use with the keyboard: ↑/↓ to move, → to expand, ← to collapse, Enter to select, then Move. Folders you can’t move into are greyed out and can’t be selected.
• Delete folder is in a folder’s row menu.
• The All / Published / Drafts switch filters the storyboards.

Search and filters

The search box above the list reads Search, or paste a SHA, PR, issue key, URL or path. What you type is looked up two ways:

• A commit SHA (7 or more characters), a pull request (owner/repo#2048), an issue key (ENG-12), a URL or a file path finds the storyboards associated with it: declared in About or recorded in Written from, on any act.
• Anything else is a text search over the storyboards’ questions and published scenes. Text of 2 or more characters is searched; a few words work best.

Select an About chip on a row to filter by it (a pull request filters by its repository too). While any search or filter is on, the list becomes one flat list of matches across your whole org, with no folders or groups, and each active filter is a chip you can remove. Clear filters drops them all. A folder can’t be combined with a search or filter, so searching from inside a folder searches everywhere. The All / Published / Drafts switch still applies.

A filtered list shows the 100 most recent matches (a search shows up to 50: the SHA, pull request, issue, URL and path matches, plus at most 20 text matches), and says so; it doesn’t page. A text search needs a Cardinal with storyboard search set up; without it the list says search isn’t available, while SHA, pull request, issue, URL and path lookups keep working.

A folder lists its 1,000 most recently modified storyboards; above that, the list says so.

When you open a storyboard, the back link at the top of the viewer is the same breadcrumb, for example Storyboards › Incidents › 2026-Q3.

Badges

Badges show where and how a storyboard was made. The viewer’s header shows two labeled panels, About first and then Written from, for the storyboard’s latest act; the list shows repository, branch and pull request under each storyboard, and the first About chip.

Written from also shows the session that wrote the act as a short chip with a copy button, a Commit badge that links to the commit on GitHub when the pull request URL is a GitHub one, and 3 edited files (a count, with the paths in a popover).

About shows what the author declared: chips for pull requests, issues, commits, files and links (and branches and repositories), each linked when it has an https URL. Select a chip to filter the list by it. Hover the heading for Declared by the author’s agent; not verified; the Written from heading says The checkout and session this was written in, reported by the author’s client; not verified. See Associations.

Status (Draft, Published, Act n draft) is shown beside them, as before. Repository, branch, pull request, commit and client come from the context each act records; a storyboard created before context was recorded has none of them.

• Created by is the Cardinal user who created the storyboard, by display name or email. When Cardinal doesn’t know which user wrote it, as with the org API key /cardinal:connect stores, it is the email Claude’s client reported for act 1, shown with a dotted underline: hover it for Self-reported by the author’s client; not verified. Without either, it is the API key’s name. A key’s id is never shown.
• Context by act. A storyboard with more than one act has a Context by act menu beside its badges, with one row per act (Act n · title) and that act’s own About and Written from badges, so you can see what each act explains and where it was written.

Folders and badges are visible only to org members. A public link never shows them.

Limits

• Datasets can be frozen only from witnessed Cardinal Data Lake metrics, logs, and spans queries. Other receipts, including every captured and reported one, can be cited and bound as the result Claude saw, but are never re-run.
• Preview, publish and evidence uploads are rate-limited per org. When Cardinal is busy, Claude waits and retries.
• Local previews run on macOS and Linux only. On Linux, Chromium needs unprivileged user namespaces to start with its sandbox on.
• The storyboard skills ship in the Claude Code plugin. Other clients connected to Cardinal’s MCP server get the same tools and the authoring guide from storyboard__describe_grammar, without local previews.

Personal workspaces

A personal workspace is the one-person org Cardinal creates when you sign up without an invitation, named after you (for example Ada’s workspace). It has these daily limits, which reset at 00:00 UTC. Team orgs have none of them.

Publishing each act counts as one publish; opening an act with storyboard__add_act doesn’t count.

Over a limit, Cardinal answers quota_exceeded with the time it resets, and Claude tells you. Inviting anyone into a personal workspace converts it into a team org as the invitation is sent. That can’t be undone; the org keeps its settings, including its public-links setting, and has no quotas from then on.