chartwright 0.1.0__tar.gz → 0.2.0__tar.gz

{chartwright-0.1.0/chartwright.egg-info → chartwright-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chartwright
-Version: 0.1.0
+Version: 0.2.0
 Summary: Build, verify, and maintain Apache Superset dashboards from small spec files.
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/debabsah/chartwright
@@ -24,14 +24,16 @@ Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0; extra == "mcp"
+Requires-Dist: mcp<3,>=1.0; extra == "mcp"
 Dynamic: license-file
 
 # Chartwright
 
-A dashboard compiler for Apache Superset. Describe the dashboard once, in a
-small text file called a spec, and the `chartwright` command line creates it,
-verifies it, and keeps it that way.
+A dashboard compiler for Apache Superset. The `chartwright` command line builds
+a dashboard from a small deterministic file, updates it from that file later,
+and decompiles an existing dashboard back into one. Every dataset, column, and
+metric is checked against your own Superset first. An AI can write the file for
+you, or revise it, from a request in plain words.
 
 ![An operations dashboard over NYC yellow-taxi data: KPI cards with unit subtitles, daily trend charts, an hour-by-weekday demand heatmap, a payment donut, borough and zone rankings, and a trip-distance histogram, behind a three-filter bar](https://raw.githubusercontent.com/debabsah/chartwright/main/docs/images/nyc-taxi-operations.png)
 
@@ -41,14 +43,20 @@ charts, three filters, one `chartwright apply`. An AI wrote
 [the request and rebuild steps](https://github.com/debabsah/chartwright/blob/main/examples/README.md).*
 
 A dashboard that lives in a file gets the workflow code already has: review it
-in a pull request, rebuild it identically, diff it against what is live, and
-bring it back after a bad change. Write the spec yourself or ask an AI for one;
-either way, every dataset, column, and metric the spec names is confirmed to
-exist before anything is built, and every chart is checked to load with data
-after.
+in a pull request, rebuild it identically, and bring it back after a bad
+change. `chartwright plan` diffs the file against the live dashboard and exits
+non-zero when they differ, so drift fails a CI check. `chartwright decompile`
+covers the other direction, and lists anything it could not carry over.
+
+Write the file yourself, or describe the dashboard you want and have an AI
+write it. The same checks run either way. After the build, each chart's query
+runs once (an error fails the build, an empty chart is named), and
+`chartwright advise` reviews the layout for readability.
 
 ## What a spec looks like
 
+The file is called a spec:
+
 ```json
 {
   "spec_version": "1",
@@ -75,8 +83,24 @@ after.
 `chartwright apply` on this file signs in to your Superset, confirms the
 `cleaned_sales_data` table and the `sales` and `order_date` columns exist,
 builds a KPI card above a line chart, and finishes by running each chart's
-query once to prove it shows data. A misspelled column or a missing table is a
-clear error naming the problem, before anything is created.
+query once. A misspelled column or a missing table is a clear error naming the
+problem, with the closest real names suggested, before anything is created.
+
+## Creating dashboards with AI
+
+The spec is typed, and every reference in it is checked before anything is
+created. Whatever a model proposes has to survive the same verification your
+own specs do.
+
+- **Claude Code skill**: from a clone of this repo, run
+  `python install-skill.py`; the model writes the spec from your request, and
+  the tool verifies and builds it.
+- **MCP server**: `chartwright-mcp` (installed with `pip install "chartwright[mcp]"`)
+  exposes ten tools covering the whole lifecycle, usable from any MCP client.
+- **Open contract**: `chartwright schema` prints the spec's JSON Schema, so any LLM or
+  tool can generate valid specs.
+- **Guardrails**: the AI proposes; the tool verifies, using your own Superset
+  login. Verification reads names (datasets, columns, metrics), not rows.
 
 ## Quick start
 
@@ -113,35 +137,47 @@ as-is.
 - **Deterministic dashboards**: the same spec always produces the identical
   dashboard. Diff it in git, review it in a PR.
 - **Verified at every step**: every reference is checked before anything is
-  written, and every chart's query runs once to prove it shows data; failures
-  say what went wrong and where.
+  written, and every chart's query runs once (an error fails the build, an
+  empty chart is named); failures say what went wrong and where.
 - **Dashboards as code, in both directions**: `chartwright decompile` turns any live
   dashboard into a spec; `chartwright plan` shows what differs between the spec and
   the live dashboard, ready as a CI gate; `chartwright compile` builds the import
   bundle offline, no server needed.
-- **Safety built in**: every apply backs up the previous state first; a failed
-  apply restores it automatically; the tool only ever overwrites dashboards it
-  created, and a hand-built dashboard is adopted by decompiling it into a spec
-  first.
-- **The full design surface**: 14 chart types, metrics as you write them,
-  per-chart filters, a native filter bar, tabs, markdown notes, and layouts
-  you can draw as ASCII sketches.
+- **Recoverable by default**: every apply backs up the previous state first,
+  and an apply that fails while importing or updating charts restores it
+  automatically. Dashboards Chartwright did not create are never overwritten;
+  to bring a hand-built one under a spec, decompile it and build it at a new
+  slug.
+- **What a spec can express**: 15 chart types, metrics as you write them,
+  per-chart filters, a native filter bar, tabs, markdown notes, a footer shown
+  under every tab, and layouts you can draw as ASCII sketches.
 - **Environment promotion**: specs name their data (connection, schema,
-  table), so the same file applies to dev, staging, and production unchanged.
+  table), so the same file applies to dev, staging, and production when they
+  share connection names.
 
 Every capability, with the CLI verb reference: [docs/FEATURES.md](https://github.com/debabsah/chartwright/blob/main/docs/FEATURES.md).
 
-## Creating dashboards with AI
+## The design brain
 
-- **Claude Code skill**: from a clone of this repo, `python install-skill.py`,
-  then ask for a dashboard in plain words; the AI writes the spec, and the
-  tool verifies and builds it.
-- **MCP server**: `chartwright-mcp` (installed with `pip install "chartwright[mcp]"`)
-  exposes six tools covering the whole lifecycle, usable from any MCP client.
-- **Open contract**: `chartwright schema` prints the spec's JSON Schema, so any LLM or
-  tool can generate valid specs.
-- **Guardrails**: the AI proposes; the tool verifies, using your own Superset
-  login. Verification reads names (datasets, columns, metrics), not rows.
+A spec can import perfectly and still produce a dashboard nobody can read: a
+pie squeezed into two columns, a KPI buried under three tables, a bar chart
+with forty category labels Superset silently drops. The design brain covers
+size and scroll budgets, chart-choice limits, and layout composition. It
+arrives as a brief the AI reads before authoring, and a critic that reviews
+the result:
+
+```bash
+chartwright brief --audience executive        # the guidance, before writing a spec
+chartwright advise spec.json --fix            # the critique, with safe auto-repairs
+chartwright redesign old-dash --profile prod  # audit + repair a live dashboard
+```
+
+You stay in charge of it: suppress any rule for one chart in the spec, tune
+the thresholds per audience or per deployment in `design.yaml`, and feed the
+heights you drag in the UI back into the recommendations with `chartwright
+calibrate`. Pass `--design off` and the output is byte-identical to a build
+that never had it. The full rulebook and architecture:
+[docs/DESIGN-BRAIN.md](https://github.com/debabsah/chartwright/blob/main/docs/DESIGN-BRAIN.md).
 
 ## Drawing layouts as text
 
@@ -162,15 +198,19 @@ space under `K` deliberately empty. Every rule, drawn and explained:
 
 ## Testing and evidence
 
-Every push runs 125 tests on Linux and Windows, plus the full pipeline (apply,
-lifecycle soak, stale-tab adversary, fault injection) against real Superset
-4.1.4, 5.0.0, and 6.1.0 containers. Chart options are checked against
-Superset's own source for every supported version, so a Superset change is
-caught in our tests before it reaches your dashboards.
+Every pull request and every push to main runs the full offline suite on Linux and
+Windows, plus the full pipeline (apply, lifecycle soak, stale-tab adversary,
+fault injection) against real Superset 4.1.4, 5.0.0, and 6.1.0 containers.
+Chart options are checked against Superset's own source for every supported
+version, so a Superset change surfaces here before it reaches your dashboards.
+
+Full evidence: [docs/VERIFICATION.md](https://github.com/debabsah/chartwright/blob/main/docs/VERIFICATION.md).
 
-Full evidence: [docs/VERIFICATION.md](https://github.com/debabsah/chartwright/blob/main/docs/VERIFICATION.md). Source citations
-for every Superset behavior the tool relies on:
-[docs/CONTRACTS.md](https://github.com/debabsah/chartwright/blob/main/docs/CONTRACTS.md).
+[docs/CONTRACTS.md](https://github.com/debabsah/chartwright/blob/main/docs/CONTRACTS.md) records how Superset itself behaves: what its
+importer accepts, how dashboard settings are stored, what its chart plugins
+expect. Every behavior is cited to its source line at 4.1.4, 5.0.0, and 6.1.0.
+Release tags are immutable, so any line of it can be checked against a fresh
+checkout of that tag.
 
 ## Documentation
 
@@ -178,10 +218,15 @@ for every Superset behavior the tool relies on:
   reference
 - [docs/LAYOUT-GUIDE.md](https://github.com/debabsah/chartwright/blob/main/docs/LAYOUT-GUIDE.md): drawing layouts as text,
   every rule illustrated
+- [docs/DESIGN-BRAIN.md](https://github.com/debabsah/chartwright/blob/main/docs/DESIGN-BRAIN.md): the design rulebook, every
+  rule and threshold, and how to tune or switch them off
 - [docs/VERIFICATION.md](https://github.com/debabsah/chartwright/blob/main/docs/VERIFICATION.md): what is tested, what it
   caught, and how to reproduce it
-- [docs/CONTRACTS.md](https://github.com/debabsah/chartwright/blob/main/docs/CONTRACTS.md): the Superset behaviors the tool
-  depends on, cited to source at each supported version
+- [docs/CONTRACTS.md](https://github.com/debabsah/chartwright/blob/main/docs/CONTRACTS.md): how Superset behaves on import,
+  on dashboard storage, and in chart options, cited to its source line at
+  each supported release
+- [docs/COMPARISON.md](https://github.com/debabsah/chartwright/blob/main/docs/COMPARISON.md): what Chartwright, preset-cli,
+  sup, and the Terraform provider each automate, so you can pick by the job
 
 ---
 

{chartwright-0.1.0 → chartwright-0.2.0}/README.md

@@ -1,8 +1,10 @@
 # Chartwright
 
-A dashboard compiler for Apache Superset. Describe the dashboard once, in a
-small text file called a spec, and the `chartwright` command line creates it,
-verifies it, and keeps it that way.
+A dashboard compiler for Apache Superset. The `chartwright` command line builds
+a dashboard from a small deterministic file, updates it from that file later,
+and decompiles an existing dashboard back into one. Every dataset, column, and
+metric is checked against your own Superset first. An AI can write the file for
+you, or revise it, from a request in plain words.
 
 ![An operations dashboard over NYC yellow-taxi data: KPI cards with unit subtitles, daily trend charts, an hour-by-weekday demand heatmap, a payment donut, borough and zone rankings, and a trip-distance histogram, behind a three-filter bar](https://raw.githubusercontent.com/debabsah/chartwright/main/docs/images/nyc-taxi-operations.png)
 
@@ -12,14 +14,20 @@ charts, three filters, one `chartwright apply`. An AI wrote
 [the request and rebuild steps](https://github.com/debabsah/chartwright/blob/main/examples/README.md).*
 
 A dashboard that lives in a file gets the workflow code already has: review it
-in a pull request, rebuild it identically, diff it against what is live, and
-bring it back after a bad change. Write the spec yourself or ask an AI for one;
-either way, every dataset, column, and metric the spec names is confirmed to
-exist before anything is built, and every chart is checked to load with data
-after.
+in a pull request, rebuild it identically, and bring it back after a bad
+change. `chartwright plan` diffs the file against the live dashboard and exits
+non-zero when they differ, so drift fails a CI check. `chartwright decompile`
+covers the other direction, and lists anything it could not carry over.
+
+Write the file yourself, or describe the dashboard you want and have an AI
+write it. The same checks run either way. After the build, each chart's query
+runs once (an error fails the build, an empty chart is named), and
+`chartwright advise` reviews the layout for readability.
 
 ## What a spec looks like
 
+The file is called a spec:
+
 ```json
 {
   "spec_version": "1",
@@ -46,8 +54,24 @@ after.
 `chartwright apply` on this file signs in to your Superset, confirms the
 `cleaned_sales_data` table and the `sales` and `order_date` columns exist,
 builds a KPI card above a line chart, and finishes by running each chart's
-query once to prove it shows data. A misspelled column or a missing table is a
-clear error naming the problem, before anything is created.
+query once. A misspelled column or a missing table is a clear error naming the
+problem, with the closest real names suggested, before anything is created.
+
+## Creating dashboards with AI
+
+The spec is typed, and every reference in it is checked before anything is
+created. Whatever a model proposes has to survive the same verification your
+own specs do.
+
+- **Claude Code skill**: from a clone of this repo, run
+  `python install-skill.py`; the model writes the spec from your request, and
+  the tool verifies and builds it.
+- **MCP server**: `chartwright-mcp` (installed with `pip install "chartwright[mcp]"`)
+  exposes ten tools covering the whole lifecycle, usable from any MCP client.
+- **Open contract**: `chartwright schema` prints the spec's JSON Schema, so any LLM or
+  tool can generate valid specs.
+- **Guardrails**: the AI proposes; the tool verifies, using your own Superset
+  login. Verification reads names (datasets, columns, metrics), not rows.
 
 ## Quick start
 
@@ -84,35 +108,47 @@ as-is.
 - **Deterministic dashboards**: the same spec always produces the identical
   dashboard. Diff it in git, review it in a PR.
 - **Verified at every step**: every reference is checked before anything is
-  written, and every chart's query runs once to prove it shows data; failures
-  say what went wrong and where.
+  written, and every chart's query runs once (an error fails the build, an
+  empty chart is named); failures say what went wrong and where.
 - **Dashboards as code, in both directions**: `chartwright decompile` turns any live
   dashboard into a spec; `chartwright plan` shows what differs between the spec and
   the live dashboard, ready as a CI gate; `chartwright compile` builds the import
   bundle offline, no server needed.
-- **Safety built in**: every apply backs up the previous state first; a failed
-  apply restores it automatically; the tool only ever overwrites dashboards it
-  created, and a hand-built dashboard is adopted by decompiling it into a spec
-  first.
-- **The full design surface**: 14 chart types, metrics as you write them,
-  per-chart filters, a native filter bar, tabs, markdown notes, and layouts
-  you can draw as ASCII sketches.
+- **Recoverable by default**: every apply backs up the previous state first,
+  and an apply that fails while importing or updating charts restores it
+  automatically. Dashboards Chartwright did not create are never overwritten;
+  to bring a hand-built one under a spec, decompile it and build it at a new
+  slug.
+- **What a spec can express**: 15 chart types, metrics as you write them,
+  per-chart filters, a native filter bar, tabs, markdown notes, a footer shown
+  under every tab, and layouts you can draw as ASCII sketches.
 - **Environment promotion**: specs name their data (connection, schema,
-  table), so the same file applies to dev, staging, and production unchanged.
+  table), so the same file applies to dev, staging, and production when they
+  share connection names.
 
 Every capability, with the CLI verb reference: [docs/FEATURES.md](https://github.com/debabsah/chartwright/blob/main/docs/FEATURES.md).
 
-## Creating dashboards with AI
+## The design brain
 
-- **Claude Code skill**: from a clone of this repo, `python install-skill.py`,
-  then ask for a dashboard in plain words; the AI writes the spec, and the
-  tool verifies and builds it.
-- **MCP server**: `chartwright-mcp` (installed with `pip install "chartwright[mcp]"`)
-  exposes six tools covering the whole lifecycle, usable from any MCP client.
-- **Open contract**: `chartwright schema` prints the spec's JSON Schema, so any LLM or
-  tool can generate valid specs.
-- **Guardrails**: the AI proposes; the tool verifies, using your own Superset
-  login. Verification reads names (datasets, columns, metrics), not rows.
+A spec can import perfectly and still produce a dashboard nobody can read: a
+pie squeezed into two columns, a KPI buried under three tables, a bar chart
+with forty category labels Superset silently drops. The design brain covers
+size and scroll budgets, chart-choice limits, and layout composition. It
+arrives as a brief the AI reads before authoring, and a critic that reviews
+the result:
+
+```bash
+chartwright brief --audience executive        # the guidance, before writing a spec
+chartwright advise spec.json --fix            # the critique, with safe auto-repairs
+chartwright redesign old-dash --profile prod  # audit + repair a live dashboard
+```
+
+You stay in charge of it: suppress any rule for one chart in the spec, tune
+the thresholds per audience or per deployment in `design.yaml`, and feed the
+heights you drag in the UI back into the recommendations with `chartwright
+calibrate`. Pass `--design off` and the output is byte-identical to a build
+that never had it. The full rulebook and architecture:
+[docs/DESIGN-BRAIN.md](https://github.com/debabsah/chartwright/blob/main/docs/DESIGN-BRAIN.md).
 
 ## Drawing layouts as text
 
@@ -133,15 +169,19 @@ space under `K` deliberately empty. Every rule, drawn and explained:
 
 ## Testing and evidence
 
-Every push runs 125 tests on Linux and Windows, plus the full pipeline (apply,
-lifecycle soak, stale-tab adversary, fault injection) against real Superset
-4.1.4, 5.0.0, and 6.1.0 containers. Chart options are checked against
-Superset's own source for every supported version, so a Superset change is
-caught in our tests before it reaches your dashboards.
+Every pull request and every push to main runs the full offline suite on Linux and
+Windows, plus the full pipeline (apply, lifecycle soak, stale-tab adversary,
+fault injection) against real Superset 4.1.4, 5.0.0, and 6.1.0 containers.
+Chart options are checked against Superset's own source for every supported
+version, so a Superset change surfaces here before it reaches your dashboards.
+
+Full evidence: [docs/VERIFICATION.md](https://github.com/debabsah/chartwright/blob/main/docs/VERIFICATION.md).
 
-Full evidence: [docs/VERIFICATION.md](https://github.com/debabsah/chartwright/blob/main/docs/VERIFICATION.md). Source citations
-for every Superset behavior the tool relies on:
-[docs/CONTRACTS.md](https://github.com/debabsah/chartwright/blob/main/docs/CONTRACTS.md).
+[docs/CONTRACTS.md](https://github.com/debabsah/chartwright/blob/main/docs/CONTRACTS.md) records how Superset itself behaves: what its
+importer accepts, how dashboard settings are stored, what its chart plugins
+expect. Every behavior is cited to its source line at 4.1.4, 5.0.0, and 6.1.0.
+Release tags are immutable, so any line of it can be checked against a fresh
+checkout of that tag.
 
 ## Documentation
 
@@ -149,10 +189,15 @@ for every Superset behavior the tool relies on:
   reference
 - [docs/LAYOUT-GUIDE.md](https://github.com/debabsah/chartwright/blob/main/docs/LAYOUT-GUIDE.md): drawing layouts as text,
   every rule illustrated
+- [docs/DESIGN-BRAIN.md](https://github.com/debabsah/chartwright/blob/main/docs/DESIGN-BRAIN.md): the design rulebook, every
+  rule and threshold, and how to tune or switch them off
 - [docs/VERIFICATION.md](https://github.com/debabsah/chartwright/blob/main/docs/VERIFICATION.md): what is tested, what it
   caught, and how to reproduce it
-- [docs/CONTRACTS.md](https://github.com/debabsah/chartwright/blob/main/docs/CONTRACTS.md): the Superset behaviors the tool
-  depends on, cited to source at each supported version
+- [docs/CONTRACTS.md](https://github.com/debabsah/chartwright/blob/main/docs/CONTRACTS.md): how Superset behaves on import,
+  on dashboard storage, and in chart options, cited to its source line at
+  each supported release
+- [docs/COMPARISON.md](https://github.com/debabsah/chartwright/blob/main/docs/COMPARISON.md): what Chartwright, preset-cli,
+  sup, and the Terraform provider each automate, so you can pick by the job
 
 ---
 

{chartwright-0.1.0 → chartwright-0.2.0}/chartwright/__init__.py

@@ -4,4 +4,4 @@ Typed spec -> deterministic compiler -> guaranteed-correct Superset dashboard.
 The LLM is an untrusted parser at the edge; the guarantee lives in typed code.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{chartwright-0.1.0 → chartwright-0.2.0}/chartwright/absorb.py

@@ -19,6 +19,7 @@ polished geometry round-trips EXACTLY through the next apply.
 from __future__ import annotations
 
 import copy
+import json
 from dataclasses import asdict, dataclass, field
 
 from . import ids

{chartwright-0.1.0 → chartwright-0.2.0}/chartwright/apply.py

@@ -151,9 +151,14 @@ def _roundtrip_dataset_files(resolution: Resolution, client: SupersetClient) ->
     return extra
 
 
-def chart_payloads_from_bundle(bundle: bytes) -> dict[str, dict]:
+def chart_payloads_from_bundle(bundle: bytes, dataset_ids: dict[str, int] | None = None) -> dict[str, dict]:
     """uuid -> ChartRestApi.put payload, from the compiled bundle's chart yamls.
 
+    With ``dataset_ids`` (dataset uuid -> id on the target), the payload also moves the
+    chart onto its spec dataset: params alone carry the new datasource, but the chart's
+    own datasource_id would stay on the old one (observed live 2026-09-25: a chart moved
+    from dataset 5 to 10 kept datasource_id 5).
+
     Used to update pre-existing owned charts IN PLACE. Slice ids must stay
     stable across re-applies: delete+reimport mints new ids, which invalidates
     native-filter scopes the moment any open browser tab writes its (stale,
@@ -164,24 +169,48 @@ def chart_payloads_from_bundle(bundle: bytes) -> dict[str, dict]:
     for n in zf.namelist():
         if "/charts/" in n and n.endswith(".yaml"):
             cy = yaml.safe_load(zf.read(n))
-            out[str(cy.get("uuid"))] = {
+            payload = {
                 "slice_name": cy.get("slice_name"),
                 "viz_type": cy.get("viz_type"),
                 "params": json.dumps(cy.get("params") or {}),
                 # params changed -> any stored query context is stale
                 "query_context": None,
             }
+            ds_id = (dataset_ids or {}).get(str(cy.get("dataset_uuid")))
+            if ds_id is not None:
+                payload["datasource_id"] = ds_id
+                payload["datasource_type"] = "table"
+            out[str(cy.get("uuid"))] = payload
     return out
 
 
+def bundle_dataset_ids(bundle: bytes, client: SupersetClient) -> dict[str, int]:
+    """Dataset uuid -> id on the target, for each dataset the bundle ships. Looked
+    up per table name (indexed server-side) and matched by uuid, as charts are."""
+    zf = zipfile.ZipFile(io.BytesIO(bundle))
+    wanted: dict[str, str] = {}
+    for n in zf.namelist():
+        if "/datasets/" in n and n.endswith(".yaml"):
+            dy = yaml.safe_load(zf.read(n)) or {}
+            if dy.get("uuid") and dy.get("table_name"):
+                wanted[str(dy["uuid"])] = dy["table_name"]
+    found: dict[str, int] = {}
+    for table in set(wanted.values()):
+        for d in client.find_datasets(table):
+            if str(d.get("uuid")) in wanted:
+                found[str(d["uuid"])] = d["id"]
+    return found
+
+
 def _update_owned_charts_in_place(
     spec: DashboardSpec, client: SupersetClient, bundle: bytes,
-    existing_by_uuid: dict[str, dict],
+    existing_by_uuid: dict[str, dict], resolution: Resolution | None = None,
 ) -> tuple[list[str], list[str]]:
-    """PUT compiled params onto pre-existing owned charts (ids stay stable).
-    Returns (updated chart names, errors)."""
+    """PUT compiled params (and the spec dataset) onto pre-existing owned charts (ids
+    stay stable). Returns (updated chart names, errors)."""
     owned = {str(ids.chart_uuid(spec.dashboard.slug, c.name)): c.name for c in spec.charts}
-    payloads = chart_payloads_from_bundle(bundle)
+    dataset_ids = {str(d.uuid): d.id for d in resolution.datasets.values()} if resolution else None
+    payloads = chart_payloads_from_bundle(bundle, dataset_ids)
     updated, errors = [], []
     for u, summary in existing_by_uuid.items():
         payload = payloads.get(u)
@@ -209,6 +238,26 @@ def backup_dir_for(profile: str, slug: str) -> "Path":
     return base / profile / slug
 
 
+def write_backup(backup_dir: "Path", data: bytes) -> "Path":
+    """Write a backup zip under a new name; never overwrite an earlier one.
+
+    Names are local time to the microsecond (``20261003T141502.123456.zip``),
+    fixed width, so they sort oldest to newest. Two applies within one second
+    used to share a name and the second overwrote the first. Exclusive create
+    makes a collision a retry, never a silent overwrite."""
+    import datetime
+
+    while True:
+        stamp = datetime.datetime.now().strftime("%Y%m%dT%H%M%S.%f")
+        path = backup_dir / f"{stamp}.zip"
+        try:
+            with open(path, "xb") as fh:
+                fh.write(data)
+            return path
+        except FileExistsError:
+            continue
+
+
 def restore_bundle(zip_bytes: bytes, slug: str, client: SupersetClient) -> ApplyReport:
     """Restore a backup bundle COMPLETELY, not just import it. The importer
     never overwrites existing charts (docs/CONTRACTS.md), so surviving
@@ -223,7 +272,15 @@ def restore_bundle(zip_bytes: bytes, slug: str, client: SupersetClient) -> Apply
             report.import_detail = r.text[:2000]
             return report
 
-        payloads = chart_payloads_from_bundle(zip_bytes)
+        # With the dataset ids, a restore also moves each chart back onto its
+        # backed-up dataset, so its datasource_id matches the params it gets.
+        # Best effort: a failed lookup must not stop the restore itself.
+        try:
+            dataset_ids = bundle_dataset_ids(zip_bytes, client)
+        except SupersetAPIError as e:
+            dataset_ids = {}
+            report.warnings.append(f"chart datasets not restored (dataset lookup failed: {e})")
+        payloads = chart_payloads_from_bundle(zip_bytes, dataset_ids)
         existing = client.charts_by_uuids(
             {u: p["slice_name"] for u, p in payloads.items()})
         restored = []
@@ -284,7 +341,6 @@ def apply(spec: DashboardSpec, client: SupersetClient, profile: str = "default")
     if existing is not None:
         # Last-known-good insurance before we mutate anything: the previous
         # owned state, restorable with `chartwright restore <zip> --profile ...`.
-        import datetime
         import os
 
         backup_dir = backup_dir_for(profile, spec.dashboard.slug)
@@ -293,11 +349,8 @@ def apply(spec: DashboardSpec, client: SupersetClient, profile: str = "default")
             # Zips hold dashboard/dataset metadata; gate the default tree to
             # the owner. (No-op on Windows; custom dirs are the user's to manage.)
             os.chmod(backup_dir.parent.parent, 0o700)
-        stamp = datetime.datetime.now().strftime("%Y%m%dT%H%M%S")
-        backup_path = backup_dir / f"{stamp}.zip"
         backup_bytes = client.export_dashboard(existing["id"])
-        backup_path.write_bytes(backup_bytes)
-        report.backup = str(backup_path)
+        report.backup = str(write_backup(backup_dir, backup_bytes))
 
     def _auto_restore(reason: str) -> None:
         """Import failed mid-mutation: put the previous state back rather
@@ -312,11 +365,11 @@ def apply(spec: DashboardSpec, client: SupersetClient, profile: str = "default")
             else:
                 report.warnings.append(
                     f"{reason}; auto-restore also failed ({rr.import_detail}); "
-                    f"restore manually: chartwright restore {report.backup}"
+                    f"restore manually: chartwright restore {report.backup} --profile {profile}"
                 )
         except Exception as e:  # noqa: BLE001 - restore is best-effort recovery
             report.warnings.append(
-                f"{reason}; auto-restore errored ({e}); restore manually: chartwright restore {report.backup}"
+                f"{reason}; auto-restore errored ({e}); restore manually: chartwright restore {report.backup} --profile {profile}"
             )
 
     # Everything below mutates the instance; any failure must still return a
@@ -359,9 +412,14 @@ def apply(spec: DashboardSpec, client: SupersetClient, profile: str = "default")
             return report
 
         if existing_by_uuid:
-            updated, update_errors = _update_owned_charts_in_place(spec, client, bundle, existing_by_uuid)
+            updated, update_errors = _update_owned_charts_in_place(
+                spec, client, bundle, existing_by_uuid, resolution)
             if update_errors:
+                # Still the import step: some charts may carry the new params
+                # and others the old. Same outcome as a connection drop here,
+                # which already restored (SupersetAPIError while stage is import).
                 report.import_detail = "; ".join(update_errors)
+                _auto_restore("updating charts in place failed after the import")
                 return report
             if updated:
                 report.warnings.append(
@@ -403,6 +461,13 @@ def apply(spec: DashboardSpec, client: SupersetClient, profile: str = "default")
         if report.stage in ("prepare", "import"):
             _auto_restore(f"apply failed during {report.stage}: {e}")
         return report
+    except Exception as e:  # noqa: BLE001 - a bug mid-mutation must still restore and report
+        # Not a Superset error: most likely a bug here. Same rule as above, and
+        # the report keeps the backup path, which a traceback would lose.
+        report.import_detail = f"unexpected error during {report.stage}: {type(e).__name__}: {e}"
+        if report.stage in ("prepare", "import"):
+            _auto_restore(f"apply failed during {report.stage}: {type(e).__name__}: {e}")
+        return report
 
     report.stage = "done"
     report.ok = True