dataface 0.2.1.dev323__py3-none-any.whl → 0.2.1.dev377__py3-none-any.whl

dataface/agent_api/_link_scan.py

@@ -0,0 +1,125 @@
+"""Host-agnostic inbound-link scanning for move_file.
+
+Scans the faces tree for references to a dashboard slug -- ``link:`` chart
+fields and markdown link targets -- so a move can rewrite what it can prove
+is a reference and report the rest. A first-class internal-link graph is out
+of scope here (a likely-separate dft-core initiative); this is a narrow,
+best-effort heuristic: exact syntactic matches are rewritten, everything else
+(the slug's basename appearing in prose, without recognized link syntax) is
+reported as a fuzzy hit and never touched.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from dataface.core.project import FACES_SUBDIR, Project
+
+_FACES_GLOB = f"{FACES_SUBDIR}/**/*"
+
+
+def face_slug(relpath: str) -> str | None:
+    """Return the dashboard slug for a ``faces/`` path (no prefix, no suffix).
+
+    ``faces/finance/rev.yml`` -> ``finance/rev``. Returns None for a path
+    outside ``faces/`` -- link scanning only has meaning for dashboard slugs.
+    """
+    prefix = f"{FACES_SUBDIR}/"
+    if not relpath.startswith(prefix):
+        return None
+    tail = relpath[len(prefix) :]
+    slug, dot, _suffix = tail.rpartition(".")
+    return slug if dot else tail
+
+
+def _link_field_pattern(slug: str) -> re.Pattern[str]:
+    escaped = re.escape(slug)
+    return re.compile(rf'(link:\s*["\']?/?){escaped}(?=[\s"\'/?]|$)')
+
+
+def _markdown_link_pattern(slug: str) -> re.Pattern[str]:
+    escaped = re.escape(slug)
+    return re.compile(rf"(\]\(/?){escaped}(?=[?)])")
+
+
+class LinkHit(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    path: str
+    line_number: int
+    line: str
+
+
+class LinkScanResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    exact: list[LinkHit] = Field(default_factory=list)
+    fuzzy: list[LinkHit] = Field(default_factory=list)
+
+
+def scan_links(project: Project, slug: str) -> LinkScanResult:
+    """Scan the faces tree for references to *slug* (e.g. ``finance/rev``).
+
+    Greps for the slug's basename (the last path segment), so a same-folder
+    relative reference (``link: rev`` inside another face already under
+    ``finance/``) is picked up by the grep too -- but the exact-match regexes
+    below only recognize the *full* slug, so a bare relative reference is
+    always classified FUZZY (reported, never rewritten), never EXACT. Full
+    relative-link resolution is out of scope here (see the module docstring);
+    only a full-slug ``link:`` chart field or markdown link target classifies
+    as EXACT.
+    """
+    basename = slug.rsplit("/", 1)[-1]
+    link_re = _link_field_pattern(slug)
+    md_re = _markdown_link_pattern(slug)
+    exact: list[LinkHit] = []
+    fuzzy: list[LinkHit] = []
+    for hit in project.files.grep(basename, glob=_FACES_GLOB):
+        bucket = (
+            exact if (link_re.search(hit.line) or md_re.search(hit.line)) else fuzzy
+        )
+        bucket.append(
+            LinkHit(path=hit.relpath, line_number=hit.line_number, line=hit.line)
+        )
+    return LinkScanResult(exact=exact, fuzzy=fuzzy)
+
+
+def plan_link_rewrites(
+    project: Project, old_slug: str, new_slug: str
+) -> tuple[LinkScanResult, dict[str, str]]:
+    """Compute exact-match link rewrites *old_slug* -> *new_slug* without writing.
+
+    Returns the scan (so the caller can report ``exact`` vs ``fuzzy``)
+    alongside a ``{path: rewritten_content}`` mapping for every file with an
+    exact hit. The caller commits it however it needs to: one file at a time
+    (``rewrite_links``, below) or batched into a single commit (Cloud's
+    governed dashboard move).
+    """
+    result = scan_links(project, old_slug)
+    if not result.exact:
+        return result, {}
+    link_re = _link_field_pattern(old_slug)
+    md_re = _markdown_link_pattern(old_slug)
+    replacement = new_slug.replace("\\", "\\\\")
+    rewrites: dict[str, str] = {}
+    for path in dict.fromkeys(hit.path for hit in result.exact):
+        content = project.read_text(path)
+        content = link_re.sub(rf"\g<1>{replacement}", content)
+        content = md_re.sub(rf"\g<1>{replacement}", content)
+        rewrites[path] = content
+    return result, rewrites
+
+
+def rewrite_links(project: Project, old_slug: str, new_slug: str) -> LinkScanResult:
+    """Rewrite exact ``link:``/markdown references to *old_slug* -> *new_slug*
+    in place; fuzzy prose hits are left untouched.
+
+    Returns the scan computed before rewriting, so the caller can report
+    exactly what changed (``exact``) vs what needs a human look (``fuzzy``).
+    """
+    result, rewrites = plan_link_rewrites(project, old_slug, new_slug)
+    for path, content in rewrites.items():
+        project.write_text(path, content)
+    return result

dataface/agent_api/cache.py

@@ -4,9 +4,13 @@ from collections.abc import Generator
 from contextlib import contextmanager
 from pathlib import Path
 
-from dataface.core.execute.trivial_local_cache import TrivialDuckDBCache
+# Re-exported: TrivialDuckDBCache is the declared return type of open_cache,
+# so embedders annotating a held cache reach it here without a core import.
+from dataface.core.execute.trivial_local_cache import (
+    TrivialDuckDBCache as TrivialDuckDBCache,
+)
 
-__all__ = ["open_cache", "cache_ctx"]
+__all__ = ["TrivialDuckDBCache", "open_cache", "cache_ctx"]
 
 
 def open_cache(path: Path | None) -> TrivialDuckDBCache:

dataface/agent_api/dashboards.py

@@ -93,6 +93,16 @@ class RenderDashboardArgs(BaseModel):
     yaml_content: str | None = Field(
         None, description="YAML content to render directly (use this OR path)"
     )
+    chart: str | None = Field(
+        None,
+        description=(
+            "Render only this chart (by chart id) from the dashboard, with its "
+            "dependent variables. Use to show one existing chart that answers "
+            "a question instead of re-deriving its query — the rendered chart "
+            "keeps the dashboard's canonical definition. Unknown ids fail with "
+            "the list of available chart ids."
+        ),
+    )
     variables: dict[str, Any] | None = Field(
         None, description="Variable values to apply to the dashboard"
     )

dataface/agent_api/docs/yaml-reference.md

@@ -26,7 +26,7 @@ AuthoredFace (dataface) definition from YAML.
 | `details` | [FaceDetails](#facedetails) | ✓ | Collapsible section metadata. String shorthand: details: 'text' → FaceDetails(summary='text'). Block form: details: {summary: ..., expanded_title: ..., expanded: false}. |
 | `id` | str | ✓ | Explicit ID for this face. Auto-generated from filename if omitted. |
 | `style` | [Style](#style) | ✓ | Style patch (background, padding, border, etc.). Background and semantic color tokens (accent, muted) cascade to nested child faces. |
-| `width` | str \| int | ✓ | Width when nested (e.g., '50%', '400px', or an integer in pixels). |
+| `width` | str \| int | ✓ | Width when nested (e.g., '50%', '400px', or an integer in pixels). On the root face there is no parent to place it into, so it instead sets the board's own width (equivalent to 'style.board.width') — percentages are rejected there since there's nothing to size relative to. |
 | `height` | str \| int | ✓ | Height when nested (e.g., '300px' or an integer in pixels). |
 | `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Controls whether this layout item is rendered. Accepts a bool, variable name, Jinja expression, or {query, column} probe. |
 | `extends` | str \| list[str] | ✓ | Face name(s) or relative path(s) this face inherits from, low to high priority. |
@@ -188,8 +188,8 @@ Authored patch for bar and histogram charts.
 | `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: column to sort by and direction (asc/desc). |
 | `multiples` | [MultiplesConfig](#multiplesconfig) | ✓ | Partition this chart into small multiples by a `rows` column (vertical stack), a `columns` column (side by side), or both (grid). Panels share one measure scale by default. |
 | `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
-| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
-| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
 | `style` | [BarChartStyle](#barchartstyle) | ✓ | Chart-local style overrides. |
 | `layers` | list[[BarLayer](#barlayer) \| [LineLayer](#linelayer) \| [AreaLayer](#arealayer) \| [ScatterLayer](#scatterlayer)] | ✓ | Typed overlay layers on this chart. |
 
@@ -217,8 +217,8 @@ Authored patch for line charts.
 | `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: column to sort by and direction (asc/desc). |
 | `multiples` | [MultiplesConfig](#multiplesconfig) | ✓ | Partition this chart into small multiples by a `rows` column (vertical stack), a `columns` column (side by side), or both (grid). Panels share one measure scale by default. |
 | `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
-| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
-| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
 | `style` | [LineChartStyle](#linechartstyle) | ✓ | Chart-local style overrides. |
 | `layers` | list[[BarLayer](#barlayer) \| [LineLayer](#linelayer) \| [AreaLayer](#arealayer) \| [ScatterLayer](#scatterlayer)] | ✓ | Typed overlay layers on this chart. |
 
@@ -246,8 +246,8 @@ Authored patch for area charts.
 | `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: column to sort by and direction (asc/desc). |
 | `multiples` | [MultiplesConfig](#multiplesconfig) | ✓ | Partition this chart into small multiples by a `rows` column (vertical stack), a `columns` column (side by side), or both (grid). Panels share one measure scale by default. |
 | `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
-| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
-| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
 | `style` | [AreaChartStyle](#areachartstyle) | ✓ | Chart-local style overrides. |
 | `layers` | list[[BarLayer](#barlayer) \| [LineLayer](#linelayer) \| [AreaLayer](#arealayer) \| [ScatterLayer](#scatterlayer)] | ✓ | Typed overlay layers on this chart. |
 
@@ -275,8 +275,8 @@ Authored patch for scatter charts.
 | `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: column to sort by and direction (asc/desc). |
 | `multiples` | [MultiplesConfig](#multiplesconfig) | ✓ | Partition this chart into small multiples by a `rows` column (vertical stack), a `columns` column (side by side), or both (grid). Panels share one measure scale by default. |
 | `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
-| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
-| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
 | `size` | str | ✓ | Column used to size-encode data points (quantitative). |
 | `shape` | str | ✓ | Column used to shape-encode data points (categorical). |
 | `style` | [ScatterChartStyle](#scatterchartstyle) | ✓ | Chart-local style overrides. |
@@ -305,8 +305,8 @@ Authored patch for heatmap charts.
 | `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: column to sort by and direction (asc/desc). |
 | `multiples` | [MultiplesConfig](#multiplesconfig) | ✓ | Partition this chart into small multiples by a `rows` column (vertical stack), a `columns` column (side by side), or both (grid). Panels share one measure scale by default. |
 | `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
-| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
-| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. Valid on cartesian chart families (area, bar, heatmap, histogram, line, scatter), pie/donut, and geo families (geoshape, map, point_map, bubble_map). Other chart families use renderer-owned or layout-owned sizing contracts. |
 | `style` | [HeatmapChartStyle](#heatmapchartstyle) | ✓ | Chart-local style overrides. |
 
 <a id="piechart"></a>
@@ -328,6 +328,8 @@ Authored patch for pie and donut charts.
 | `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
 | `color` | str | ✓ | Color data channel: bare column name only. |
 | `total` | [ChartTotal](#charttotal) | ✓ | Donut center total. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. |
+| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. |
 | `style` | [PieChartStyle](#piechartstyle) | ✓ | Chart-local style overrides. |
 
 <a id="kpichart"></a>
@@ -394,6 +396,8 @@ Authored patch for point_map and bubble_map charts.
 | `geo_source` | str | ✓ | Named geographic data source for loading GeoJSON boundaries. |
 | `lookup` | str | ✓ | Data column to join against geographic data (map join key). |
 | `value` | str | ✓ | Data column mapped to the fill color. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. |
+| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. |
 | `latitude` | str | ✓ | Column containing latitude values for point/bubble maps. |
 | `longitude` | str | ✓ | Column containing longitude values for point/bubble maps. |
 | `size` | str | ✓ | Data column used to scale bubble radius (quantitative). Only meaningful on bubble_map. |
@@ -422,8 +426,8 @@ Authored patch for map and geoshape charts.
 | `geo_source` | str | ✓ | Named geographic data source for loading GeoJSON boundaries. |
 | `lookup` | str | ✓ | Data column to join against geographic data (map join key). |
 | `value` | str | ✓ | Data column mapped to the fill color. |
-| `latitude` | str | ✓ | Column containing latitude values for point/bubble maps. |
-| `longitude` | str | ✓ | Column containing longitude values for point/bubble maps. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. |
+| `width` | int \| float | ✓ | Preferred chart width in pixels. Positive number only. Contributes to the dashboard's intrinsic width without overriding the final layout slot — the chart still fills its allocated container. |
 | `style` | [GeoshapeChartStyle](#geoshapechartstyle) | ✓ | Chart-local style overrides. |
 
 <a id="calloutchart"></a>
@@ -1172,9 +1176,9 @@ Authored overlay for ChartsStyle. Registry of all chart-type styles plus shared
 | `default_table_height` | float | ✓ | Placeholder table height in pixels; replaced by data-aware row-count sizing at render time. |
 | `label_usable_ratio` | float | ✓ | Fraction of chart width usable for axis labels (0–1); labels are tilted when full labels exceed this width. |
 | `axis` | [AxisStyle](#axisstyle) | ✓ | Shared axis style applied to all axes before per-axis overrides. |
-| `axis_x` | [AxisStyle](#axisstyle) | ✓ | X-axis style overrides applied after the shared axis. Unset fields fall back to `style.charts.axis`. |
-| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Y-axis style overrides applied after the shared axis. Unset fields fall back to `style.charts.axis`. |
-| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Quantitative axis style overrides applied after axis_x/axis_y. Unset fields fall back to `style.charts.axis`. |
+| `axis_x` | [AxisStyle](#axisstyle) | ✓ | X-axis style overrides applied after the shared axis. Unset fields fall back to style.charts.axis. |
+| `axis_y` | [AxisStyle](#axisstyle) | ✓ | Y-axis style overrides applied after the shared axis. Unset fields fall back to style.charts.axis. |
+| `axis_quantitative` | [AxisStyle](#axisstyle) | ✓ | Quantitative axis style overrides applied after axis_x/axis_y. Unset fields fall back to style.charts.axis. |
 | `view` | [ViewStyle](#viewstyle) | ✓ | Vega-Lite view dimensions and border. |
 | `autosize` | [AutosizeStyle](#autosizestyle) | ✓ | Vega-Lite autosize configuration. |
 | `marks` | [GlobalMarksStyle](#globalmarksstyle) | ✓ | Global mark defaults (tier-1 of the marks cascade). |
@@ -1391,6 +1395,8 @@ Authored overlay for TooltipStyle. Tooltip box style — all cascade keys for th
 | `value` | [TooltipSlotStyle](#tooltipslotstyle) | ✓ | Value-column font overrides (color, weight). |
 | `border` | [TooltipBorderStyle](#tooltipborderstyle) | ✓ | Tooltip border style; theme always provides this. |
 | `shadow` | [TooltipShadowStyle](#tooltipshadowstyle) | ✓ | Tooltip drop-shadow config; theme always provides this. |
+| `swatch` | [TooltipSwatchStyle](#tooltipswatchstyle) | ✓ | Series colour swatch size/shape; theme always provides this. |
+| `active_marker` | enum: "fill", "triangle" | ✓ | How the hovered row is marked in a multi-row (x-unified) tooltip: 'fill' tints the row background (default); 'triangle' draws an edge-flush wedge in the box's left padding instead. Theme always provides this. |
 
 <a id="stylecolorconfig"></a>
 ## StyleColorConfig
@@ -1917,6 +1923,8 @@ Authored overlay for TextCodeStyle. Inline and fenced code spans in markdown pro
 | `font` | [FontStyle](#fontstyle) | ✓ | Box text font overrides — full FontStyle (family, color, size, weight, style, decoration, case). |
 | `background` | str | ✓ | Box background fill. |
 | `border` | [BorderStyle](#borderstyle) | ✓ | Box border (width, color, radius). |
+| `highlight` | bool | ✓ | Syntax-highlight fenced markdown code blocks. |
+| `theme` | str | ✓ | Pygments style name for fenced markdown code tokens. |
 
 <a id="textblockquotestyle"></a>
 ## TextBlockquoteStyle
@@ -2159,6 +2167,15 @@ Authored overlay for TooltipShadowStyle. Tooltip drop-shadow toggle. JS applies
 |-------|------|:--------:|-------------|
 | `visible` | bool | ✓ | Show a drop-shadow on the tooltip box; theme always provides this. |
 
+<a id="tooltipswatchstyle"></a>
+## TooltipSwatchStyle
+Authored overlay for TooltipSwatchStyle. Series colour swatch in the tooltip — the mark-coloured chip next to each
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `size` | float | ✓ | Swatch edge length in pixels (square). |
+| `radius` | float | ✓ | Swatch corner radius in pixels (0 = square, ~half of size = circle). |
+
 <a id="scaletargetconfig"></a>
 ## ScaleTargetConfig
 Scale configuration for a single style target (background or color).
@@ -2644,7 +2661,7 @@ Authored overlay for BarLabelsStyle. Bar mark value-label config. Extends MarkLa
 |-------|------|:--------:|-------------|
 | `visible` | bool | ✓ | Show numeric value labels on each mark; False by default. |
 | `field` | str | ✓ | Column to source label text from; None uses the chart's y-field. |
-| `format` | str | ✓ | Number format string for value labels. Falls back to [`style.charts.axis_quantitative.format`](#axisstyle). |
+| `format` | str | ✓ | Number format string for value labels. |
 | `dx` | int | ✓ | Horizontal pixel offset for value labels; overrides the position default. |
 | `dy` | int | ✓ | Vertical pixel offset for value labels; overrides the position default. |
 | `font` | [FontStyle](#fontstyle) | ✓ | Value label font style (color, size, family, etc.). |
@@ -2670,7 +2687,7 @@ Authored overlay for PointLabelsStyle. Point/line mark value-label config. Used
 |-------|------|:--------:|-------------|
 | `visible` | bool | ✓ | Show numeric value labels on each mark; False by default. |
 | `field` | str | ✓ | Column to source label text from; None uses the chart's y-field. |
-| `format` | str | ✓ | Number format string for value labels. Falls back to [`style.charts.axis_quantitative.format`](#axisstyle). |
+| `format` | str | ✓ | Number format string for value labels. |
 | `dx` | int | ✓ | Horizontal pixel offset for value labels; overrides the position default. |
 | `dy` | int | ✓ | Vertical pixel offset for value labels; overrides the position default. |
 | `font` | [FontStyle](#fontstyle) | ✓ | Value label font style (color, size, family, etc.). |

dataface/agent_api/files.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from dataface.agent_api._link_scan import LinkHit, face_slug, rewrite_links
 from dataface.core.errors.execution import ExecutionError
 from dataface.core.project import FACES_SUBDIR, Project
 
@@ -63,6 +64,32 @@ class EditFileArgs(BaseModel):
     new_string: str = Field(description="Replacement text.")
 
 
+class MoveFileArgs(BaseModel):
+    """Move (rename) a project file. Fails if the destination already exists
+    or the source does not. Both paths are relative to the project root and
+    may not escape it.
+
+    When both paths are dashboard faces (under faces/), exact-match ``link:``
+    chart fields and markdown links pointing at the old slug are rewritten to
+    the new one in the same operation; any other reference to the old slug's
+    basename is reported as a fuzzy hit, never rewritten.
+    """
+
+    source_path: str = Field(
+        description="Current file path relative to the project root."
+    )
+    destination_path: str = Field(
+        description="New file path relative to the project root."
+    )
+
+
+class DeleteFileArgs(BaseModel):
+    """Delete a project file. Fails if it does not exist. Path is relative to
+    the project root and may not escape it."""
+
+    path: str = Field(description="File path relative to the project root.")
+
+
 class GlobFilesArgs(BaseModel):
     """List files matching a glob pattern (e.g. 'faces/*.yml').
 
@@ -126,6 +153,25 @@ class EditFileResult(BaseModel):
     error: str | None = None
 
 
+class MoveFileResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    success: bool
+    source_path: str
+    destination_path: str
+    links_rewritten: int = 0
+    fuzzy_links: list[LinkHit] = Field(default_factory=list)
+    error: str | None = None
+
+
+class DeleteFileResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    success: bool
+    path: str
+    error: str | None = None
+
+
 class GlobResult(BaseModel):
     model_config = ConfigDict(frozen=True)
 
@@ -199,6 +245,88 @@ def edit_file(
     return EditFileResult(success=True, path=path, replacements=1)
 
 
+def move_file(
+    source_path: str, destination_path: str, project: Project
+) -> MoveFileResult:
+    """Move *source_path* to *destination_path*, rewriting exact inbound
+    dashboard links along the way (see ``MoveFileArgs``). LOCAL semantics: no
+    exceptions escape, everything is reported in the typed result."""
+    try:
+        content = project.read_text(source_path)
+    except FileNotFoundError:
+        return MoveFileResult(
+            success=False,
+            source_path=source_path,
+            destination_path=destination_path,
+            error=f"file not found: {source_path}",
+        )
+    except (ValueError, IsADirectoryError, *_UNREADABLE_FILE) as exc:
+        return MoveFileResult(
+            success=False,
+            source_path=source_path,
+            destination_path=destination_path,
+            error=str(exc),
+        )
+    try:
+        destination_exists = project.exists(destination_path)
+    except ValueError as exc:
+        return MoveFileResult(
+            success=False,
+            source_path=source_path,
+            destination_path=destination_path,
+            error=str(exc),
+        )
+    if destination_exists:
+        return MoveFileResult(
+            success=False,
+            source_path=source_path,
+            destination_path=destination_path,
+            error=f"destination already exists: {destination_path}",
+        )
+
+    old_slug, new_slug = face_slug(source_path), face_slug(destination_path)
+    scan = rewrite_links(project, old_slug, new_slug) if old_slug and new_slug else None
+
+    try:
+        project.write_text(destination_path, content)
+    except (ValueError, OSError) as exc:
+        return MoveFileResult(
+            success=False,
+            source_path=source_path,
+            destination_path=destination_path,
+            error=str(exc),
+        )
+    try:
+        project.delete_text(source_path)
+    except (ValueError, OSError, FileNotFoundError) as exc:
+        return MoveFileResult(
+            success=False,
+            source_path=source_path,
+            destination_path=destination_path,
+            error=f"wrote {destination_path!r} but failed to delete {source_path!r}: {exc}",
+        )
+    return MoveFileResult(
+        success=True,
+        source_path=source_path,
+        destination_path=destination_path,
+        links_rewritten=len(scan.exact) if scan else 0,
+        fuzzy_links=scan.fuzzy if scan else [],
+    )
+
+
+def delete_file(path: str, project: Project) -> DeleteFileResult:
+    """Delete *path*. LOCAL semantics: no exceptions escape."""
+    try:
+        project.delete_text(path)
+    except FileNotFoundError:
+        return DeleteFileResult(
+            success=False, path=path, error=f"file not found: {path}"
+        )
+    except (ValueError, OSError) as exc:
+        return DeleteFileResult(success=False, path=path, error=str(exc))
+    return DeleteFileResult(success=True, path=path)
+
+
 def glob_files(pattern: str | None, project: Project) -> GlobResult:
     """List files matching *pattern*; ``None`` (the documented tool default)
     lists the faces subtree."""

dataface/agent_api/project_session.py

@@ -432,6 +432,7 @@ class ProjectSession:
         path: Path | None = None,
         *,
         yaml_content: str | None = None,
+        chart: str | None = None,
         variables: dict[str, Any] | None = None,
         format: RenderFormat = "json",
         use_cache: bool = True,
@@ -453,6 +454,7 @@ class ProjectSession:
         return _core_dashboard.render_dashboard(
             path=path,
             yaml_content=yaml_content,
+            chart=chart,
             variables=variables,
             adapter_registry=self.adapter_registry,
             project=self.project,

dataface/agent_api/surface_aliases.yaml

@@ -63,6 +63,10 @@ skill_design_report:
   tool: "get_skill('report-design')"
   dft: "dft skills report-design"
 
+skill_replicate_dashboard:
+  tool: "get_skill('dashboard-replicate')"
+  dft: "dft skills dashboard-replicate"
+
 skill_review:
   tool: "get_skill('dashboard-review')"
   dft: "dft skills dashboard-review"

dataface/ai/agent.py

@@ -25,7 +25,7 @@ from dataface.ai.llm import LLMClient, LLMClientError
 from dataface.ai.memories import format_memories_prompt, load_memories
 from dataface.ai.prompts import load_shared_prompt
 from dataface.ai.tool_schemas import CHAT_TOOLS
-from dataface.ai.tools import dispatch_tool_call
+from dataface.ai.tools import ToolHandler, dispatch_tool_call
 
 if TYPE_CHECKING:
     from dataface.core.execute.adapters import AdapterRegistry
@@ -167,6 +167,12 @@ class AgentProfile:
     name: str
     tools: list[dict[str, Any]]
     build_system_prompt: Callable[[DatafaceAIContext], str]
+    # Per-profile override for tool names the shared registry already handles
+    # (e.g. Cloud routing move_file/delete_file to a governed service instead
+    # of the generic local file-tool handler) — consulted before TOOL_HANDLERS
+    # in dispatch_tool_call — one tool name and contract across hosts, two
+    # backends. None for profiles with no host-specific behavior.
+    tool_overrides: dict[str, ToolHandler] | None = None
 
 
 # The default profile: the dashboard analyst that `dft chat` and the MCP/cloud
@@ -178,6 +184,24 @@ DASHBOARD_PROFILE = AgentProfile(
 )
 
 
+def _model_facing_result(result: dict[str, Any]) -> dict[str, Any]:
+    """Return the copy of a tool result the model reads.
+
+    SVG output is a display artifact for the host (Cloud embeds it; the CLI
+    never requests it) — feeding ~100KB of markup to the model wastes context
+    and invites it to echo the blob as prose. The model keeps the verdict
+    (success, warnings, errors); the host-facing ToolResultEvent keeps the
+    full payload.
+    """
+    data = result.get("data")
+    if isinstance(data, str) and data.lstrip().startswith("<svg"):
+        return {
+            **result,
+            "data": f"[svg omitted ({len(data)} chars) — rendered for the user]",
+        }
+    return result
+
+
 def run_agent(
     prompt: str | list[dict[str, Any]],
     *,
@@ -188,6 +212,7 @@ def run_agent(
     profile: AgentProfile | None = None,
     tools: list[dict[str, Any]] | None = None,
     external_manager: ExternalMCPManager | None = None,
+    extra_handlers: dict[str, ToolHandler] | None = None,
 ) -> Generator[AgentEvent, None, None]:
     """Run the agent loop and stream typed events.
 
@@ -199,6 +224,8 @@ def run_agent(
             tools. Used by chat sessions; defaults to the profile's tools.
         external_manager: ExternalMCPManager instance for routing 'server__tool' calls.
             Must be provided when tools contains external (namespaced) entries.
+        extra_handlers: Per-call handlers for tools with no meaning to dft-core
+            (e.g. Cloud's placement tool) — threaded straight to dispatch_tool_call.
     """
     active = profile if profile is not None else DASHBOARD_PROFILE
     effective_tools = tools if tools is not None else active.tools
@@ -246,13 +273,15 @@ def run_agent(
                 tc.arguments,
                 context=context,
                 external_manager=external_manager,
+                extra_handlers=extra_handlers,
+                tool_overrides=active.tool_overrides,
             )
             conversation.append(
                 {
                     "role": "tool",
                     "tool_call_id": tc.id,
                     "name": tc.name,
-                    "content": json.dumps(result, default=str),
+                    "content": json.dumps(_model_facing_result(result), default=str),
                 }
             )
             yield ToolResultEvent(id=tc.id, name=tc.name, result=result)

dataface/ai/skills/analyst-runbook/SKILL.md

@@ -31,6 +31,9 @@ whenever one fits — and say which you reused.{{/if_tool}}
    - **one chart** — a single trend, ranking, or breakdown
    - **a dashboard** — several related charts that explore a topic together
    - **a report** — narrative plus charts that walk through an analysis
+   - **a replication** — the user supplied an existing dashboard (screenshot,
+     image, export) to reproduce → `{{ s_skill_replicate_dashboard }}`;
+     fidelity to the source, not a redesign
 2. **Clarify only what blocks you.** If the metric, grain, time window, or filters
    are ambiguous *and* the choice changes the answer, ask one focused question.
    Otherwise state the assumption and proceed.

dataface/ai/skills/dashboard-build/SKILL.md

@@ -40,6 +40,7 @@ Build dashboards and reports **incrementally** — one chart at a time, validati
 ## Companion Skills
 
 - **`{{ s_skill_design_dashboard }}`** — chart-type, layout, and color decisions
+- **`{{ s_skill_replicate_dashboard }}`** — reproducing an existing dashboard from a screenshot or export
 - **`{{ s_skill_design_report }}`** — narrative reports (text + charts)
 - **`{{ s_skill_review }}`** — self-review checklist run at delivery
 - **`{{ s_skill_troubleshooting }}`** — when something breaks
@@ -268,7 +269,7 @@ Named presets (prefer these over raw D3 strings):
 | Writing SQL without checking column names | Check INFORMATION_SCHEMA via `{{ s_execute_query }}` first |
 | Hardcoding values during exploration | Use `{{ variables }}` from the start so the query cache survives |
 | Skipping validation between changes | `{{ s_validate_dashboard }}` after every YAML edit |
-| Too many charts (>8) | Split into multiple dashboards |
+| Too many charts (>8) the user didn't ask for | Split into multiple dashboards |
 | Using chart-type names as keys in layout | `table:` or `bar:` as keys cause parse errors — use descriptive names like `revenue_table` |
 | Referencing query names in layout | Layout references charts, not queries — create a chart that wraps the query |
 | KPI query returns multiple rows | Use `SUM()`/`COUNT()`/`AVG()` to aggregate to 1 row |
@@ -289,13 +290,13 @@ Named presets (prefer these over raw D3 strings):
 | "I know what the columns are called" | You don't. Check INFORMATION_SCHEMA with `{{ s_execute_query }}`. |
 | "Validation is slow, I'll do it at the end" | Validation is instant. Skipping it costs more time debugging later. |
 | "It's just a quick chart, no need for variables" | Variables cost nothing and enable caching. Use them. |
-| "User wants 15 charts on one dashboard" | 8 max. Propose splitting into focused dashboards. |
+| "15 charts is too many, I'll trim their list" | An explicit user ask wins. Suggest a split once, then build all 15. The 8-max default applies when the design is yours to choose. |
 
 ## Red Flags — STOP
 
 - About to write SQL without having explored the actual schema first
 - Building more than one new chart before validating the previous one
-- Dashboard has more than 8 visualizations
+- Dashboard has more than 8 visualizations the user didn't ask for
 - A chart exists without a clear question it answers
 - Using hardcoded values that should be variables
 - Delivering without running the self-review checklist