dataface 0.1.6.dev558__py3-none-any.whl → 0.1.6.dev644__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -114,6 +114,12 @@ rows:
 ### Queries (named, parameterized, inline)
 
 ```yaml
+variables:
+  region:
+    input: select
+    options:
+      static: [US, EU, APAC]
+
 queries:
   # Bare-string form — SQL inherits the face-level source
   revenue: SELECT month, SUM(amount) AS total FROM orders GROUP BY 1 ORDER BY 1
@@ -342,6 +348,12 @@ Queries are the data layer. Charts reference queries by name; queries never embe
 ```yaml
 source: my_profile             # Optional: default source for every query below
 
+variables:
+  region:
+    input: select
+    options:
+      static: [US, EU, APAC]
+
 queries:
   # SQL — the default. `type: sql` is implicit when `sql:` is present.
   revenue: SELECT month, SUM(amount) AS total FROM orders GROUP BY 1 ORDER BY 1
@@ -423,6 +435,7 @@ Queries are Jinja-rendered before execution. Reference variables as bare names
 ```yaml
 variables:
   region: { input: select, options: { static: [US, EU, APAC] } }
+  period: { input: daterange }
 
 queries:
   sales:
@@ -503,22 +516,20 @@ charts:
     y: total                  # column name OR [col, col, ...] for multi-series
     color: segment            # column | {value: "#ccc"} | {field, scale} | {field, when}
 
-    # Sizing — live at chart root, NOT under style:
+    # Sizing — height lives at chart root; aspect_ratio is a style field
     height: 400               # exact px; bypasses aspect_ratio and min/max clamps
-    aspect_ratio: 2.0         # shape without a fixed size; height = width / aspect_ratio
-    # height and aspect_ratio are ignored on kpi, table, callout, spark_bar
+    # height/aspect_ratio are ignored on kpi, table, callout, spark_bar
 
     # Style + behavior
     sort: { by: total, order: desc }
     x_label: "Month"
     y_label: "Revenue (USD)"
     link: "/orders?month={{ month }}"      # Click-through URL template (drill-down)
-    filters: { ... }                        # Result filters
 
     style:                    # Chart-local style patch (typed; not raw CSS) — paint only
-      orientation: vertical   # style: does NOT accept height or aspect_ratio
+      aspect_ratio: 2.0       # shape without a fixed size; height = width / aspect_ratio
       number_format: ",.0f"   # D3 format string or named alias for axis/tooltip format
-      stack: zero               # false | true | zero | normalize | center
+      # bar/area families also accept style.orientation and style.stack
 ```
 
 ### Chart types (29 total)
@@ -572,7 +583,6 @@ All chart types accept the channels and style fields below — but each type rej
 | `background` | string \| object | Background channel — color, `{value}`, `{field, scale/when}`, or map layer |
 | `sort` | object | `{by, order}` — categorical sort. Horizontal bar charts default to value-descending order when omitted. |
 | `link` | string | Click-through URL template for drill-down links |
-| `filters` | object | Post-execution row filters: `{col: var_name}` (implicit `eq`) or `{col: {op: var}}` where op is one of `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `in`, `not_in`, `between`. Implicit-eq values may also be Jinja templates (e.g. `"{{ region }}"`) resolved at execute time. A filter is skipped when the variable is `None`, `""`, or renders to `"none"`. |
 | `layers` | list | Layer definitions for `type: layered` (see [Composition](#composition)) |
 | `conditional_formatting` | object | Discrete style rules by column (see [Conditional formatting](#conditional-formatting)) |
 | `data_table` | list | Attached mini-table beneath bar/line/area/layered (see [Composition](#composition)) |
@@ -585,7 +595,7 @@ All chart types accept the channels and style fields below — but each type rej
 
 KPI-only fields: `value`, `label`, `support`. KPI uses `label:` for the header text — `title:` is rejected on KPI charts. `glyph` and `tone` moved into the style namespace: use `style.glyph.character` and `style.tone`. To override glyph/value color, use `style.kpi.glyph.font.color` / `style.kpi.value.font.color`.
 
-Top-level chart fields shared by all types: `id`, `query`, `type`, `title`, `subtitle`, `description`, `height`, `aspect_ratio`, `style`, `link`, `filters`, `conditional_formatting`.
+Top-level chart fields shared by all types: `id`, `query`, `type`, `title`, `subtitle`, `description`, `height`, `aspect_ratio`, `style`, `link`, `conditional_formatting`.
 
 ### Chart-type cheatsheet
 

dataface/agent_api/__init__.py

@@ -53,11 +53,18 @@ from dataface.agent_api.schema_hints import (
     SchemaHints as SchemaHints,
     schema_hints as schema_hints,
 )
-from dataface.agent_api.validate import ValidateDashboardArgs, ValidateResult
+from dataface.agent_api.validate import (
+    ValidateDashboardArgs,
+    ValidateResult,
+)
 from dataface.agent_api.validate_query import (
     QueryDiagnostic as QueryDiagnostic,
     validate_query as validate_query,
 )
+from dataface.core.compile.compiler import (
+    CompileResult as CompileResult,
+    compile as compile,
+)
 from dataface.core.compile.config import ProjectSourcesConfig as ProjectSourcesConfig
 from dataface.core.dashboard import (
     RenderedDashboard as RenderedDashboard,
@@ -69,6 +76,8 @@ from dataface.core.render.board_links import LinkContext as LinkContext
 from dataface.core.render.errors import RenderError as RenderError
 
 __all__ = [
+    "compile",
+    "CompileResult",
     "DescribeFaceArgs",
     "DescribeFaceResult",
     "DocsArgs",

dataface/agent_api/cache.py

@@ -3,13 +3,14 @@
 from collections.abc import Generator
 from contextlib import contextmanager
 
-from dataface.core.execute.duckdb_cache import DuckDBCache, open_cache_from_env
+from dataface.core.execute.duckdb_cache import open_cache_from_env
+from dataface.core.execute.trivial_local_cache import TrivialDuckDBCache
 
 __all__ = ["cache_from_env", "open_cache_from_env"]
 
 
 @contextmanager
-def cache_from_env() -> Generator[DuckDBCache | None]:
+def cache_from_env() -> Generator[TrivialDuckDBCache | None]:
     """Open DFT_CACHE_PATH-backed cache (or None) and close it on exit.
 
     Use for CLI verbs and composition roots that need a cache scoped to

dataface/agent_api/data_paths.py

@@ -201,19 +201,25 @@ def build_alias_index_for_project(project: Project) -> AliasIndex:
 def data_alias_errors_for_file(
     face_file: Path,
     source_names: frozenset[str],
+    project: Project,
 ) -> list[str]:
     """Read aliases from a face file and lint any /data/ prefixed ones.
 
-    Source-name check only — no DB connection, no resolver. Called from the
-    validate path which must stay connection-free.
+    Reads through *project* (the FilePlugin seam), so it works against a
+    git-blob store as well as the filesystem. Source-name check only — no DB
+    connection, no resolver. Called from the validate path which must stay
+    connection-free.
 
     Returns a list of error message strings; empty means no data alias issues.
     Silently returns [] when the file cannot be parsed (compile catches that).
     """
     from dataface.core.serve.alias_index import read_aliases_from_file
 
+    # file_for_path raises ValueError when face_file is outside project.root —
+    # that is a caller bug, not a parse error, and must NOT be swallowed.
+    project_file = project.file_for_path(face_file)
     try:
-        aliases = read_aliases_from_file(face_file)
+        aliases = read_aliases_from_file(project_file)
     except ValueError:
-        return []  # compile path reports alias parse errors with better context
+        return []  # compile path reports alias-shape parse errors with context
     return validate_data_aliases(aliases, source_names=source_names)

dataface/agent_api/docs/yaml-reference.md

@@ -100,9 +100,8 @@ AuthoredQuery definition from YAML.
 | `rows` | list[dict[str, Any]] | ✓ | Inline data rows for values-type queries (list of row dicts). |
 | `values` | list[list[Any]] | ✓ | Inline column-oriented data for values-type queries (list of lists). |
 | `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
-| `filters` | dict[str, Any] | ✓ | Jinja2 filter expressions applied to query results. |
+| `filters` | dict[str, Any] | ✓ | Declarative column filters injected into the query's WHERE clause (SQL/DuckDB sources). |
 | `limit` | int | ✓ | Maximum number of rows returned. |
-| `pivot` | [Pivot](#pivot) | ✓ | Cross-tab pivot hint: transforms long-form SQL output into a wide table at render time (table consumers only). Does not affect SQL execution. |
 | `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['fanout_risk', 'reaggregation']). |
 
 <a id="barchart"></a>
@@ -116,7 +115,6 @@ Authored patch for bar and histogram charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -144,7 +142,6 @@ Authored patch for line charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -172,7 +169,6 @@ Authored patch for area charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -200,7 +196,6 @@ Authored patch for scatter charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -230,7 +225,6 @@ Authored patch for heatmap charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -259,7 +253,6 @@ Authored patch for pie and donut charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -281,7 +274,6 @@ Authored patch for KPI (key performance indicator) charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `label` | str | ✓ | KPI label rendered above the headline value. |
@@ -300,12 +292,14 @@ Authored patch for table charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
 | `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
 | `style` | [TableChartStyle](#tablechartstyle) | ✓ | Chart-local style overrides. |
+| `rows` | list[str] | ✓ | Fields whose distinct values form the row dimension of a pivot cross-tab. Each string is a column name from the query result. Omit for flat (non-pivot) tables. |
+| `columns` | list[str] | ✓ | Fields whose distinct values become column headers in a pivot cross-tab. Multiple fields create a nested multi-dimension pivot (outer → inner). Omit for flat tables. |
+| `values` | list[str] | ✓ | Measure fields that fill pivot cells. Each string is a column name from the query result. When omitted, all query columns not claimed by rows or columns are used. |
 
 <a id="pointmapchart"></a>
 ## PointMapChart
@@ -318,7 +312,6 @@ Authored patch for point_map and bubble_map charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -346,7 +339,6 @@ Authored patch for map and geoshape charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -373,7 +365,6 @@ Authored patch for layered multi-mark charts.
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -408,7 +399,6 @@ Authored patch for spark_bar charts (compact horizontal bars).
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
 | `query` | str \| [Query](#query) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `filters` | dict[str, [FilterDef](#filterdef)] | ✓ | Declarative column filters applied to chart data after query execution. |
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `title` | str | ✓ | Chart title displayed above the chart (not used on type: kpi). |
@@ -510,25 +500,6 @@ Options configuration for variable inputs.
 | `column` | str | ✓ | Column in the query result to use as option values. |
 | `label_column` | str | ✓ | Column in the query result to use as display labels (separate from values). |
 
-<a id="pivot"></a>
-## Pivot
-Query-level pivot rendering hint for cross-tab table layout.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `column` | str | Dimension whose distinct values become column headers in the cross-tab layout. |
-| `value` | str | Measure that fills each cell in the cross-tab layout. |
-
-<a id="filterdef"></a>
-## FilterDef
-One column→variable binding in chart.filters.
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `op` | enum: "eq", "neq", "gt", "gte", "lt", "lte", "like", "ilike", "in", "not_in", "between" | ✓ | Comparison operator. Defaults to 'eq'. |
-| `var` | str | ✓ | Plain variable name (no Jinja). Set when the filter value is a dashboard variable reference. |
-| `template` | str | ✓ | Jinja template resolved at execute time. Only valid with op='eq'. Set when conditional-disable or complex expressions are needed. |
-
 <a id="fieldconditionalformatting"></a>
 ## FieldConditionalFormatting
 Conditional formatting rules scoped to a single column.
@@ -578,7 +549,6 @@ Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -595,7 +565,7 @@ Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
 | `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `orientation` | enum: "horizontal", "vertical", "auto" | ✓ | Preferred bar orientation; None uses the renderer default (vertical). |
-| `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for bar charts; None uses the renderer default (VL stacks by default). |
+| `stack` | enum: "none", "zero", "normalize", "center" | ✓ | Default stack mode for bar charts; none renders side-by-side columns. |
 | `stack_order` | enum: "value", "data", "alphabetical" | ✓ | Z-order of stacked segments. None/'value' puts the largest aggregate at baseline. 'data' follows SQL row order (orientation-stable not guaranteed). 'alphabetical' sorts by color field name. Ignored when stacking is off or no color. |
 | `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration for bar charts. |
 | `marks` | [BarChartMarksStyle](#barchartmarksstyle) | ✓ | Bar-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |
@@ -615,7 +585,6 @@ Authored overlay for LineChartStyle. Line chart style: chart-level fields + mark
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -649,7 +618,6 @@ Authored overlay for AreaChartStyle. Area chart style: chart-level fields + mark
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -665,7 +633,7 @@ Authored overlay for AreaChartStyle. Area chart style: chart-level fields + mark
 | `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
 | `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
-| `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for area charts; False overlaps silhouettes. |
+| `stack` | enum: "none", "zero", "normalize", "center" | ✓ | Default stack mode for area charts; none overlaps silhouettes. |
 | `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration for area charts. |
 | `marks` | [AreaChartMarksStyle](#areachartmarksstyle) | ✓ | Area-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |
 
@@ -684,7 +652,6 @@ Authored overlay for ScatterChartStyle. Scatter chart style: chart-level fields
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -717,7 +684,6 @@ Authored overlay for HeatmapChartStyle. Heatmap chart style.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -762,7 +728,6 @@ Authored overlay for PieChartStyle. Pie/donut chart style: geometry + total (fla
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -796,7 +761,6 @@ Authored overlay for KpiChartStyle. Produced by cascade from theme YAML.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -825,7 +789,6 @@ Authored overlay for TableChartStyle. Table chart style overrides layered on top
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Table background color; None inherits from theme. |
@@ -883,7 +846,6 @@ Authored overlay for PointMapChartStyle. Point map chart style.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -908,7 +870,6 @@ Authored overlay for GeoshapeChartStyle. Geoshape (choropleth) chart style.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -959,7 +920,6 @@ Flat style patch for layered multi-mark charts.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style overrides. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style overrides. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -976,7 +936,7 @@ Flat style patch for layered multi-mark charts.
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
 | `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `orientation` | enum: "horizontal", "vertical", "auto" | ✓ | Preferred bar orientation; None uses the renderer default (vertical). |
-| `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for bar/area charts. |
+| `stack` | enum: "none", "zero", "normalize", "center" | ✓ | Default stack mode for bar/area charts. |
 | `stack_order` | enum: "value", "data", "alphabetical" | ✓ | Z-order of stacked segments. |
 | `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration. |
 | `marks` | [LayeredMarksStyle](#layeredmarksstyle) | ✓ | Per-mark-type style overrides (bar/line/area/point). |
@@ -1102,7 +1062,7 @@ Authored overlay for TitleStyle. Board and face titles.
 | `min_height` | float | ✓ | Minimum title row height in pixels. |
 | `overflow` | str | ✓ | Text overflow mode (clip, truncate, wrap-two, wrap). |
 | `position` | [TitlePositionStyle](#titlepositionstyle) | ✓ | Vega-Lite title positioning: anchor, angle, offset, baseline. |
-| `level` | enum: "auto" | ✓ | Heading level override for face titles. ``'auto'`` (default) computes the level semantically as the count of titled ancestors. An integer value locks all titles in this face and its descendants to that H-level. |
+| `level` | int \| enum: "auto" | ✓ | Heading level override for face titles. ``'auto'`` (default) computes the level semantically as the count of titled ancestors. An integer value locks all titles in this face and its descendants to that H-level. |
 | `subtitle` | [TitleSubtitleStyle](#titlesubtitlestyle) | ✓ | Subtitle font styles. |
 
 <a id="textstyle"></a>
@@ -1142,7 +1102,6 @@ Authored overlay for ChartsStyle. Registry of all chart-type styles plus shared
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
 | `background` | str | ✓ | Chart canvas background; None inherits from the board background via apply_inherit. Falls back to [`style.background`](#style). |
@@ -1335,15 +1294,6 @@ Authored overlay for PaddingStyle. Per-chart padding inset (px). All 4 sides req
 | `top` | float | ✓ | Top padding in pixels. |
 | `bottom` | float | ✓ | Bottom padding in pixels. |
 
-<a id="inferencestyle"></a>
-## InferenceStyle
-Authored overlay for InferenceStyle.
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `infer_zero_when_missing` | bool | ✓ | Auto-infer zero-baseline when not authored. |
-| `infer_fields_when_missing` | bool | ✓ | Auto-infer chart fields (x, y, etc.) when not authored. |
-
 <a id="legendstyle"></a>
 ## LegendStyle
 Authored overlay for LegendStyle.
@@ -1417,7 +1367,7 @@ Authored overlay for ScaleStyle. Scale configuration primitive.
 | `point_padding` | float | ✓ | Padding fraction for point scales; None uses Vega-Lite's default. |
 | `rect_band_padding_inner` | float | ✓ | Inner padding fraction for rect band scales; None uses Vega-Lite's default. |
 | `round` | bool | ✓ | Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding). |
-| `zero` | bool | ✓ | Force scale to include zero; None uses Vega-Lite's default. |
+| `zero` | bool \| enum: "auto" | ✓ | Force scale zero-baseline: True/False pins it; "auto" runs the Dataface smart-zero heuristic; None passes through to Vega-Lite. |
 | `clamp` | bool | ✓ | Clamp values to scale domain; None uses Vega-Lite's default (no clamping). |
 | `continuous_padding` | float | ✓ | Padding in pixels for continuous scales; None uses Vega-Lite's default. |
 | `band` | [ScaleBandStyle](#scalebandstyle) | ✓ | Band mark size constraints; None uses Vega-Lite's defaults. |
@@ -1654,7 +1604,7 @@ Configuration for a single table column.
 |-------|------|:--------:|-------------|
 | `label` | str | ✓ | Display header label (defaults to column name). |
 | `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format (D3 string, preset name, or FormatConfig). |
-| `spark` | enum: "line", "area", "bar", "bar-normalize", "columns" | ✓ | Inline spark chart config or spark type name. |
+| `spark` | enum: "line", "area", "bar", "bar-normalize", "column", "columns" | ✓ | Inline spark chart config or spark type name. |
 | `swatch` | bool | ✓ | When True, render this column's cells as small rounded color squares instead of text. Cell value must be a CSS color string (e.g. '#3164a3'). Useful for series-keyed tables — e.g. a 'Series' column where each row is identified by its color in the parent chart's palette. |
 | `width` | int \| str | ✓ | Column width (integer pixels or CSS string like '10%'). |
 | `max_width` | int \| str | ✓ | Maximum column width for auto-sized text columns (integer pixels or CSS string like '30%'). Cannot be set together with width:. |
@@ -1702,6 +1652,7 @@ Authored overlay for SparkStyle. Inline sparkline defaults (inside table cells).
 | `empty` | [SparkEmptyStyle](#sparkemptystyle) | ✓ | Style for empty/no-data sparklines. |
 | `single_value` | [SparkSingleValueStyle](#sparksinglevaluestyle) | ✓ | Style for single-data-point sparklines. |
 | `columns` | [SparkColumnsStyle](#sparkcolumnsstyle) | ✓ | Style for column-type sparklines. |
+| `column` | [SparkColumnStyle](#sparkcolumnstyle) | ✓ | Style for the single vertical `column` spark mark. |
 | `bar` | [SparkBarCellStyle](#sparkbarcellstyle) | ✓ | Style for bar/bar-normalize sparklines. |
 | `area` | [SparkAreaStyle](#sparkareastyle) | ✓ | Style for area sparklines. |
 
@@ -1944,7 +1895,6 @@ Authored overlay for HistogramChartStyle. Histogram chart style.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -2119,7 +2069,7 @@ Scale configuration for a single style target (background or color).
 | `min` | float \| int | ✓ | Minimum scale domain value (overrides data minimum). |
 | `max` | float \| int | ✓ | Maximum scale domain value (overrides data maximum). |
 | `null_color` | str | ✓ | Color assigned to null values. |
-| `hinge` | enum: "auto" | ✓ | Diverging scale midpoint value, or 'auto' to use the data midpoint. |
+| `hinge` | float \| enum: "auto" | ✓ | Diverging scale midpoint value, or 'auto' to use the data midpoint. |
 | `arm_mode` | enum: "asymmetric", "symmetric" | ✓ | How diverging scale arms are stretched: 'asymmetric' (proportional) or 'symmetric' (equal arms). |
 
 <a id="axisgridstyle"></a>
@@ -2306,6 +2256,7 @@ Authored overlay for SliceMarkStyle. Pie/donut slice mark — mark-level paint a
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Arc slice opacity (0–1); None means not overridden at this level. |
 | `gap` | float | ✓ | Angular gap between slices in radians. |
 | `corner_radius` | float | ✓ | Corner radius of arc slices in pixels. |
 | `stroke` | [StrokeStyle](#strokestyle) | ✓ | Arc slice stroke style. |
@@ -2334,7 +2285,7 @@ Configuration for spark charts (inline sparklines) in table columns.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `type` | enum: "line", "area", "bar", "bar-normalize", "columns" | ✓ | Spark chart type (line, area, bar, bar-normalize, columns). |
+| `type` | enum: "line", "area", "bar", "bar-normalize", "column", "columns" | ✓ | Spark chart type (line, area, bar, bar-normalize, column, columns). |
 | `color` | str | ✓ | Color for the spark mark. |
 | `height` | int | ✓ | Spark chart height in pixels. |
 | `width` | int | ✓ | Spark chart width in pixels. |
@@ -2386,6 +2337,15 @@ Authored overlay for SparkColumnsStyle. Inline `spark.type: columns` (multi-valu
 | `min_bar_height` | float | ✓ | Minimum rendered bar height in pixels. |
 | `border` | [BorderStyle](#borderstyle) | ✓ | Column bar border style. |
 
+<a id="sparkcolumnstyle"></a>
+## SparkColumnStyle
+Authored overlay for SparkColumnStyle. Inline `spark.type: column` (single vertical bar) defaults.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `width` | float | ✓ | Spark column default width in pixels. |
+| `height` | float | ✓ | Spark column default height in pixels. |
+
 <a id="sparkbarcellstyle"></a>
 ## SparkBarCellStyle
 Authored overlay for SparkBarCellStyle. Inline `spark.type: bar` and `bar-normalize` (single horizontal bar) defaults.

dataface/agent_api/project_session.py

@@ -124,7 +124,7 @@ class ProjectSession:
         """Construct a ProjectSession rooted at *project_dir*.
 
         Cache lifecycle belongs to the caller: pass ``cache=open_cache_from_env()``
-        (or another DuckDBCache) when persistent caching is desired, otherwise omit
+        (or another cache backend) when persistent caching is desired, otherwise omit
         and the project will run uncached. ``close()`` does not touch the cache —
         whoever opened it closes it.
 

dataface/agent_api/render_face.py

@@ -45,7 +45,7 @@ def render_face(
         use_cache: Whether to use the in-memory Executor result cache.
         cache: Optional DuckDB query-result cache. When provided, the caller
             owns the cache lifecycle and must close it. The DuckDB cache is
-            *not* read from DFT_CACHE_PATH — pass an open DuckDBCache to
+            *not* read from DFT_CACHE_PATH — pass an open cache backend to
             enable caching (see ``open_cache_from_env`` in
             ``dataface.core.execute.duckdb_cache``).
         **options: Additional render options (e.g. ``scale`` for PNG).

dataface/agent_api/validate.py

@@ -170,7 +170,7 @@ def _validate_meta_file(path: Path) -> ValidateResult:
             DatafaceError.from_code(
                 DF_COMPILE_META_SCHEMA,
                 message=(
-                    f"{' → '.join(str(loc) for loc in e['loc'])}: {e['msg']}"
+                    f"{'.'.join(str(loc) for loc in e['loc'])}: {e['msg']}"
                     if e["loc"]
                     else e["msg"]
                 ),
@@ -258,7 +258,9 @@ def annotate_with_data_lint(
         if not result.path.exists() or not result.path.is_file():
             annotated.append(result)
             continue
-        alias_msgs = data_alias_errors_for_file(result.path, source_names=source_names)
+        alias_msgs = data_alias_errors_for_file(
+            result.path, source_names=source_names, project=project_session.project
+        )
         if not alias_msgs:
             annotated.append(result)
             continue

dataface/cli/_error_format.py

@@ -21,6 +21,18 @@ from dataface.core.errors import StructuredError
 from dataface.core.render.warnings.base import RenderWarning
 
 
+def _display_path(abs_path: str, line: int | None, cwd: Path | None = None) -> str:
+    """Return path relative to cwd when possible, with optional :line suffix."""
+    p = Path(abs_path)
+    base = cwd if cwd is not None else Path.cwd()
+    try:
+        rel = p.relative_to(base)
+        display = str(rel)
+    except ValueError:
+        display = abs_path
+    return f"{display}:{line}" if line else display
+
+
 def print_structured_errors(
     errs: list[StructuredError],
     *,
@@ -42,8 +54,7 @@ def print_structured_errors(
         if e.hint:
             body_parts.append(f"[dim]Hint:[/] {e.hint}")
         if e.file:
-            loc = e.file + (f":{e.line}" if e.line else "")
-            body_parts.append(f"[dim]At:[/] {loc}")
+            body_parts.append(f"[dim]At:[/] {_display_path(e.file, e.line)}")
         if e.docs_topic:
             body_parts.append(f"[dim]Docs:[/] dft docs {e.docs_topic}")
         elif e.doc_url: