diff --git a/.claude/skills/build-plugin/SKILL.md b/.claude/skills/build-plugin/SKILL.md index 12a03dd2..51ff0c48 100644 --- a/.claude/skills/build-plugin/SKILL.md +++ b/.claude/skills/build-plugin/SKILL.md @@ -306,7 +306,7 @@ Pass in the prompt: - The versioned plugin dir, plus the `--plugin-id --datasource-id ` captured at Checkpoint A. - The planned dashboards from Phase 2 (top-level summary + one perspective per object type) and the object types. - The data stream names to build tiles from — the sub-agent reads the stream files itself for columns and parameters. -- Instructions: read `references/oob-content.md`, write `defaultContent/` (manifest, scopes, dashboards) and `scopes.json` (only scopes the dashboards actually use), run `squaredup validate --json` from the plugin dir, and return a compact report — dashboards written, scopes added, validation result, any assumptions or follow-ups. +- Instructions: read `references/oob-content.md` — including its SmartViz section, which has the sub-agent fetch current chart guidance with `squaredup skill visualize` — write `defaultContent/` (manifest, scopes, dashboards) and `scopes.json` (only scopes the dashboards actually use), run `squaredup validate --json` from the plugin dir, and return a compact report — dashboards written, scopes added, validation result, any assumptions or follow-ups. Resolve anything the report flags before Phase 8. @@ -324,6 +324,8 @@ Then invoke the `deploy-plugin` skill for the final validate, version bump, and **Conditional final re-index.** If `indexDefinitions/*.json` or any import stream changed since the last successful import (the Checkpoint B run, or any re-index triggered by the [re-indexing rule](#re-indexing-rule--a-definition-change-leaves-imported-objects-stale)), the deployed tenant's objects are **stale** — they still match the **old** definition and won't pick up the new shape until the next scheduled import, up to `frequencyMinutes` away (default `720` = 12 hours). So after the final deploy lands, trigger + poll one more import (the [Checkpoint B](#checkpoint-b-redeploy--run-the-first-import) trigger/wait steps) so the deployed objects match the shipped definition. Skip only if no import definition or import stream has changed since the last import. +**Check the SmartViz charts.** `squaredup validate` checks each `vizSpec` against the schema, but it cannot confirm that each `field` names a real column, and a wrong one leaves the chart empty. Once the final deploy and any re-index above have landed, ask the user to open each dashboard that has `vizSpec` tiles in the deployed plugin and confirm every chart shows data. For an empty chart, check its `field` names against the stream's columns (the post-group names when the tile groups — see [oob-content.md](references/oob-content.md#shaping-in-the-tile-group-filter-sort)), fix them, and redeploy. + --- ## Phase 10 (optional): Contribute the plugin back diff --git a/.claude/skills/build-plugin/references/oob-content.md b/.claude/skills/build-plugin/references/oob-content.md index d7ce525e..7c8d42cf 100644 --- a/.claude/skills/build-plugin/references/oob-content.md +++ b/.claude/skills/build-plugin/references/oob-content.md @@ -8,6 +8,7 @@ - [Auto-scoping a stream](#auto-scoping-a-stream-via-its-objects-filter) - [Shaping in the tile: group, filter, sort](#shaping-in-the-tile-group-filter-sort) - [Dashboard rules](#dashboard-rules) +- [SmartViz charts (`vizSpec`)](#smartviz-charts-vizspec) — fetch live guidance with `squaredup skill visualize` - [Visualisation types](#visualisation-types): table, line graph, bar chart, scalar, donut, blocks, gauge, text & image tiles - [Templating tokens](#templating-tokens) @@ -261,6 +262,26 @@ Common tiles, with the **exact** column names the visualisation must reference: --- +## SmartViz charts (`vizSpec`) + +SmartViz is the platform's chart engine. A tile opts in with a `vizSpec` — a JSON chart spec — at `config.vizSpec`, a sibling of `dataStream`, `scope` and `timeframe`. The spec format and its rules change with the platform, so **this file deliberately does not document them**. Fetch the current guidance from the platform instead: + +```sh +squaredup skill visualize # the spec format, the rules, and a chart chooser +squaredup skill visualize --file references/cartesian.md # one chart type's reference +squaredup skill visualize --all # everything in one go +``` + +This is the same `visualize` skill the SquaredUp MCP server serves, so it is written for an agent editing live tiles. When you apply it to plugin default content: + +- **Ignore the MCP tool steps.** The skill names tools such as `tile_create`, `tile_update`, `tile_query`, `data_stream_query` and `validate_visualization`. You write the `.dash.json` file directly; there is no tile to create or update. +- **Take column names from the stream.** Every `field` in the spec is a real column `name` — from the stream's `metadata` in `dataStreams/.json`, or the post-group names when the tile groups (see [Shaping in the tile](#shaping-in-the-tile-group-filter-sort)). Confirm them by running the stream with the ids from your brief: `squaredup test --plugin-id --datasource-id --json --silent`. For a scoped stream, first get an object id with `squaredup objects --plugin-id --datasource-id --json --silent`, then add `--object ` to the test. +- **Validate it.** `squaredup validate` checks each tile's `vizSpec` against the schema the app renders with, and reports a failure at its path in the `.dash.json` (for example `dashboard.contents[3].config.vizSpec.visualization.chartType`). Fix every one: the app silently ignores a spec that fails the schema, so the tile would not show your chart. Validation cannot check that each `field` is a real column, so get the names right from the stream; the charts are checked in the deployed plugin in Phase 9 of the build-plugin skill. + +If `squaredup skill` is not available (an older CLI — `npm i -g @squaredup/cli` to update — or a platform that does not serve skills yet), skip `vizSpec` and use only the classic [visualisation types](#visualisation-types) below. + +--- + ## Visualisation types > The types below are **`visualisation.type` values inside a `tile/data-stream` tile** — they sit at `config.visualisation = { "type": "", "config": { "": { … } } }` (see [Dashboard layout](#dashboard-layout)). Text and image tiles are **not** data-stream visualisations — they are their own tile `_type`; see [Text and image tiles](#text-and-image-tiles) at the end.