derive_dashboard_spec

Reconstruct a draft spec from an existing refreshable dashboard. A read-only migration aid that stores nothing. Parameters and refusals.

Reconstructs a draft Dashies spec from an existing refreshable dashboard that predates specs, by reading its stored refresh manifest plus its published body. It is a migration aid and it stores nothing: the response is a draft plus a fidelity report you review before republishing.

Republishing that draft to the same slug is what converts the dashboard to spec-backed. That step is reversible: restore the pre-publish version to undo it.

Behaviour hints for clients: read-only, not open-world.

Parameters

Parameter	Type	Required	Notes
`slug`	string	yes	Canonical slug of the refreshable dashboard to reconstruct a spec from.
`workspace`	string	no	Workspace slug.

Returns

Derived a DRAFT spec for "revenue-overview" (https://mickey.dashies.xyz/revenue-overview).
Fidelity: look mode, 3 datasets reconstructed, 0 lossy.
Look body: 51204 bytes, 1 data islands, sha256 6f1c9d2a4b8e0c31... (referenced by look.from; resolved at publish - not included in this response).
Recognized tiles: 6 (a ready-to-paste tiles: block is included below).
Notes:
- unit.scale derived as units to preserve the currently displayed values.

Review the draft below, then publish it to the SAME slug via publish_dashboard({ spec }) to convert this dashboard to spec-backed (reversible: restore the pre-publish version to undo).

BEGIN_JSON
{"slug":"revenue-overview","url":"https://mickey.dashies.xyz/revenue-overview","spec":"dash: 1\n...","fidelity":{}}
END_JSON

The draft's look: field references the current body by slug rather than inlining it, so the response stays small and the stored spec stays kilobyte-sized. Publishing resolves that body from storage and changes zero pixels.

The numbers are preserved, but they are re-seeded

Aggregates are inverted with the same classifier the publish validator uses, so the draft cannot disagree with itself on republish, and display units are derived to keep the currently displayed values rather than guessing at cents. What the derivation does not freeze is the data: republishing re-seeds every dataset live like any refresh, so displayed numbers update if the source moved.

To hand-edit the markup instead, read the body with get_dashboard and publish a spec with the inline look: { html } form.

Errors

The shared slug rules, plus:

Condition	Text
The spec read failed	`spec lookup failed: <err>`
The manifest read failed	`source_config lookup failed: <err>`
No such dashboard	`No dashboard named "<slug>" in your account.`
The body read failed	`could not read the dashboard body: <err>`
The body is unreadable	`The dashboard body for "<slug>" could not be read from storage, so a look-mode spec cannot be built.`

Three refusals that derive nothing

"<slug>" already has a stored Dashies spec; deriving would create a second source of truth. Use get_dashboard_spec to read and edit the existing spec.

"<slug>" is not refreshable (it has no source_config manifest), so there is nothing to derive. derive_dashboard_spec reconstructs a spec from a refreshable dashboard's manifest + body.

"<slug>" stores its data as Parquet, and republishing a derived spec would reset that dataset to its not-yet-extracted state until the next refresh. Deriving it is not supported yet, so it stays on the legacy path. Nothing was derived.

The Parquet refusal is a deliberate limit, not a bug: a spec can declare Parquet, but a derived republish would reset a materialized dataset to a pending pointer, so those dashboards stay on the legacy path for now.

Scope

Workspace-capable. Any member of the workspace may derive from its dashboards.

Check it worked

Compare the fidelity report's Notes: list against what you expect to lose; anything listed there is a difference you are accepting. After republishing the draft, load the dashboard and confirm it looks identical, then read it back with get_dashboard_spec to confirm it is now spec-backed.