dataface 0.3.2.dev111__py3-none-any.whl → 0.4.0__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -252,8 +252,9 @@ aliases:
 ```
 
 Rules:
-- An alias must not collide with a real face file path — the server raises an error at startup if it does.
-- Each alias must be unique across the project — two faces claiming the same alias is a startup error.
+- Every alias must be absolute (leading `/`) — a relative entry fails validation on that face.
+- An alias must not collide with a real face file path — `dft serve` raises an error at startup if it does.
+- Each alias must be unique across the project — two faces claiming the same alias is a startup error under `dft serve`. A host with no startup step resolves a duplicate to the first face by slug instead of reporting it.
 - Aliasing a generated system route (data or inspector view) is allowed: the redirect takes precedence, letting you override what that URL serves.
 
 #### Parameterized aliases (capture a path segment into a variable)
@@ -613,7 +614,11 @@ Each block below shows the minimum-viable shape for one chart type. They are sta
 type: bar
 x: category
 y: value
-color: group           # Optional second dimension; stacks by default
+color: group           # Optional second dimension; grouped side by side by default
+style:
+  orientation: vertical  # vertical = column chart; horizontal = horizontal bar chart.
+                          # Auto-resolves from x's column type when omitted: categorical x → horizontal.
+  stack: zero            # see the stack table under "area" — bar takes the same values
 
 # line — temporal/ordered x, numeric y
 type: line
@@ -625,8 +630,14 @@ color: segment         # Optional: one line per segment
 type: area
 x: date
 y: value
+color: segment         # Required for stacking — stack modes split by this field
 style:
-  stack: normalize     # 100% stacked
+  # stack names the shape you get. All four values work on bar and area alike:
+  stack: zero          # stacked
+  # stack: none        # overlapping — bar groups side by side, area overlays.
+                        # The default when color: is set.
+  # stack: normalize   # 100% stacked — every column fills the full height
+  # stack: center      # streamgraph — stacked around a centered baseline
 
 # scatter — x and y numeric
 type: scatter

dataface/agent_api/docs/yaml-reference.md

@@ -15,10 +15,10 @@ AuthoredFace (dataface) definition from YAML.
 | `source` | str | ✓ | Default source name for all queries in this face. Inheritable via meta.yaml cascade. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy for every query in this dashboard, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts the whole dashboard out. Inheritable via the meta.yaml cascade. |
 | `variables` | dict[str, [Variable](#variable) \| VariableRef] | ✓ | Variable definitions for dynamic filtering and UI controls. |
-| `queries` | dict[str, [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef] | ✓ | Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.). |
+| `queries` | dict[str, [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef] | ✓ | Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.). |
 | `charts` | dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| ChartRef] | ✓ | Named chart definitions. When no explicit layout is present, charts render as an implicit row layout in authored order. |
-| `rows` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Vertical stack layout: list of chart names or inline chart/face definitions. |
-| `cols` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Horizontal layout: list of chart names or inline chart/face definitions. |
+| `rows` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Vertical stack layout: list of chart names or inline chart/face definitions. |
+| `cols` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Horizontal layout: list of chart names or inline chart/face definitions. |
 | `grid` | [GridLayout](#gridlayout) | ✓ | CSS-grid style layout with explicit row/column placement. |
 | `tabs` | [TabLayout](#tablayout) | ✓ | Tabbed navigation layout where each tab contains its own layout. |
 | `card_gap` | bool | ✓ | When True, adds gap between cards. Default: cards are edge-to-edge (0 gap). |
@@ -55,7 +55,7 @@ Variable definition from YAML.
 | `visible` | bool | ✓ | When False, the variable is not rendered in the UI but can still be set via URL params. |
 | `enabled` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Enable this control. Accepts: static bool; a variable name or Jinja boolean expression string (no {{ }} required — bare names auto-wrap); or a {query, column} form that reads a single boolean cell from a named query. None = enabled. Absent variable in a string expression raises (use a default). |
 | `column` | str | ✓ | Column name in the query result to use as option values. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) | ✓ | Query name or inline query definition for populating options. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) | ✓ | Query name or inline query definition for populating options. |
 | `dimension` | str | ✓ | MetricFlow dimension name for populating options. |
 | `measure` | str | ✓ | MetricFlow measure name for populating options. |
 | `model` | str | ✓ | dbt model name for populating options. |
@@ -159,54 +159,6 @@ dbt source schema query.
 | `table` | str | ✓ | Table name for schema queries. |
 | `column` | str | ✓ | Column name for schema queries. |
 
-<a id="lookmlquery"></a>
-## LookmlQuery
-LookML query rooted at one explore.
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `explore` | str |  | LookML explore name. Presence of this key infers type: lookml. Use a merge query instead to combine multiple sources. |
-| `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
-| `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
-| `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
-| `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
-| `type` | enum: "lookml" | ✓ | Query adapter type. |
-| `fields` | list[str] | ✓ | Qualified 'view.field' refs to select. Optional at authoring time: collected from chart channels when absent. |
-| `sorts` | list[str] | ✓ | Looker sort clauses, e.g. ['view.field', 'view.other desc']. Lowered to ORDER BY via likeml. |
-| `pivots` | list[str] | ✓ | Qualified 'view.field' refs to pivot on. |
-| `pivots_unwrapped` | bool | ✓ | Which of Looker's two pivot SQL shapes to emit: False/None = wrapped (5-layer DENSE_RANK), True = plain GROUP BY. |
-| `total` | bool | ✓ | Looker grand-totals flag. |
-| `subtotals` | list[str] | ✓ | Dimension refs to subtotal via GROUP BY ROLLUP. |
-| `filter_expression` | str | ✓ | Looker query-level free-form boolean filter over ${view.field} refs. |
-| `dynamic_fields` | list[dict[str, Any]] | ✓ | Looker dynamic fields: custom measures / custom dimensions synthesized into SQL. Table calculations compose as a derived wrapper query, not here. |
-| `limit` | int | ✓ | Maximum number of rows returned. |
-| `column_limit` | int | ✓ | Looker column_limit — caps wrapped-pivot columns. |
-| `filters` | dict[str, Any] | ✓ | RAW Looker filter expressions keyed by 'view.field' (e.g. "13 months", "gold") — translated to SQL predicates by likeml. |
-
-<a id="lookmlmergequery"></a>
-## LookmlMergeQuery
-LookML query that merges multiple sources.
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `merge` | list[dict[str, Any]] |  | LookML merge sources — a list of source specs. Each is either an explore spec ({explore, fields, filters?, merge_on?}) or a query reference ({query, columns, merge_on?}) for a derived source such as a table-calc wrapper. First is the primary; each secondary's `merge_on` maps its key to the primary's. Presence of this key infers type: lookml. Compiled to a FULL OUTER JOIN via likeml. |
-| `source` | str \| dict[str, Any] | ✓ | Source name reference, or an inline file path (e.g. `./data/sales.csv`). File paths are detected by `/` or data file extension. An inline connection-bearing dict (`{type: postgres, ...}`) is rejected at compile time — reference a named source instead. |
-| `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
-| `ignore` | list[str] | ✓ | Diagnostic codes to suppress for this query (e.g., ['WARN-FANOUT-RISK', 'WARN-REAGGREGATION']). |
-| `cache` | [Cache](#cache) | ✓ | Cache policy override for this query, e.g. cache: 5m — refines the policy inherited from the source and project scopes; cache: false opts out of result caching entirely. Queries with cache: false cannot be used as {{ queries.X.cache }} upstream references. |
-| `type` | enum: "lookml" | ✓ | Query adapter type. |
-| `fields` | list[str] | ✓ | Qualified 'view.field' refs to select. Optional at authoring time: collected from chart channels when absent. |
-| `sorts` | list[str] | ✓ | Looker sort clauses, e.g. ['view.field', 'view.other desc']. Lowered to ORDER BY via likeml. |
-| `pivots` | list[str] | ✓ | Qualified 'view.field' refs to pivot on. |
-| `pivots_unwrapped` | bool | ✓ | Which of Looker's two pivot SQL shapes to emit: False/None = wrapped (5-layer DENSE_RANK), True = plain GROUP BY. |
-| `total` | bool | ✓ | Looker grand-totals flag. |
-| `subtotals` | list[str] | ✓ | Dimension refs to subtotal via GROUP BY ROLLUP. |
-| `filter_expression` | str | ✓ | Looker query-level free-form boolean filter over ${view.field} refs. |
-| `dynamic_fields` | list[dict[str, Any]] | ✓ | Looker dynamic fields: custom measures / custom dimensions synthesized into SQL. Table calculations compose as a derived wrapper query, not here. |
-| `limit` | int | ✓ | Maximum number of rows returned. |
-| `column_limit` | int | ✓ | Looker column_limit — caps wrapped-pivot columns. |
-| `filters` | dict[str, Any] | ✓ | RAW Looker filter expressions keyed by 'view.field' (e.g. "13 months", "gold") — translated to SQL predicates by likeml. |
-
 <a id="barchart"></a>
 ## BarChart
 Authored patch for bar and histogram charts.
@@ -217,9 +169,9 @@ Authored patch for bar and histogram charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `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. |
@@ -246,9 +198,9 @@ Authored patch for line charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `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. |
@@ -275,9 +227,9 @@ Authored patch for area charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `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. |
@@ -304,9 +256,9 @@ Authored patch for scatter charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `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. |
@@ -334,9 +286,9 @@ Authored patch for heatmap charts.
 | `type` | enum: "heatmap" |  | Heatmap chart type. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `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. |
@@ -363,9 +315,9 @@ Authored patch for pie and donut charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `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. |
@@ -386,9 +338,9 @@ Authored patch for KPI (key performance indicator) charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `warnings_ignore` | list[str] | ✓ | Codes of render warnings to suppress for this chart. |
 | `label` | str | ✓ | KPI label rendered above the headline value. |
 | `variant` | enum: "stacked", "inline", "compact" | ✓ | Layout variant. 'stacked' (default) shows value, label, and support on three vertical lines. 'inline' lays value, label, and support out on a single baseline-aligned row. 'compact' is 2-column — big value on the left, up to two stacked lines on the right with the bottom line sharing baseline with the value; a lone `support` block splits across the two right-column lines. |
@@ -406,9 +358,9 @@ Authored patch for table charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `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. |
@@ -427,9 +379,9 @@ Authored patch for point_map and bubble_map charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `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. |
@@ -457,9 +409,9 @@ Authored patch for map and geoshape charts.
 | `conditional_formatting` | dict[str, [FieldConditionalFormatting](#fieldconditionalformatting)] | ✓ | Discrete rule-driven style overrides indexed by column name. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `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. |
@@ -494,9 +446,9 @@ Authored patch for spark_bar charts (compact horizontal bars).
 | `type` | enum: "spark_bar" |  | SparkBar chart type. |
 | `id` | str | ✓ | Explicit chart ID (auto-generated from the chart's YAML key if omitted). |
 | `description` | str | ✓ | Human-readable description used by AI search and context tooltips. |
-| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| [LookmlQuery](#lookmlquery) \| [LookmlMergeQuery](#lookmlmergequery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
+| `query` | str \| [SqlQuery](#sqlquery) \| [MetricflowQuery](#metricflowquery) \| [HttpQuery](#httpquery) \| [ValuesQuery](#valuesquery) \| [CompactValuesQuery](#compactvaluesquery) \| [SchemaQuery](#schemaquery) \| QueryRef | ✓ | Named query reference, inline AuthoredQuery, or SQL string shorthand. |
 | `link` | str | ✓ | Click-through URL template for drill-down links. |
-| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'model.explore' for a LookML source, or 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the LookML catalog / dbt semantic manifest. Mutually exclusive with `query:`. |
+| `model` | str | ✓ | Semantic-layer entry point, two dot-joined names: 'source.semantic_model' for a dbt_profile (MetricFlow) source. Channel fields name the model's fields directly; roles are inferred from the dbt semantic manifest. Mutually exclusive with `query:`. |
 | `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. |
@@ -504,14 +456,6 @@ Authored patch for spark_bar charts (compact horizontal bars).
 | `y` | str \| list[str] | ✓ | Y-axis (value) column name(s). |
 | `style` | [SparkBarChartStyle](#sparkbarchartstyle) | ✓ | Chart-local style overrides. |
 
-<a id="foreachitem"></a>
-## ForeachItem
-Top-level foreach construct in a layout list.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `foreach` | [ForeachConfig](#foreachconfig) | foreach loop configuration with query, as, and items. |
-
 <a id="gridlayout"></a>
 ## GridLayout
 Grid layout configuration.
@@ -958,9 +902,7 @@ Authored overlay for TableChartStyle. Table chart style overrides layered on top
 | `spark` | [SparkStyle](#sparkstyle) | ✓ | Inline sparkline defaults for table cells. |
 | `transpose` | bool | ✓ | When True, render a single wide data row as N (label, value) rows — one per column. Raises ChartDataError when data has more than one row. Used for Looker single-value summary tiles with multiple measures. |
 | `text_baseline_offset` | float | ✓ | Vertical offset to align SVG text baseline with cell grid in pixels. |
-| `title_baseline_offset` | float | ✓ | Vertical offset to align SVG title baseline in pixels. |
-| `title_subtitle_gap` | float | ✓ | Gap between table title and subtitle lines in pixels. |
-| `subtitle` | [SubtitleStyle](#subtitlestyle) | ✓ | Table subtitle font-sizing constants. |
+| `title_subtitle_gap` | float | ✓ | Pure whitespace between the title's descent and the subtitle's ascent, in pixels — not a baseline-to-baseline distance. Combined with the title and subtitle font sizes (via _TITLE_ASCENT_RATIO in render/chart/table.py) to reproduce Vega-Lite's title-&gt;subtitle spacing at any font size, not one calibrated pair. Font size and colour for the subtitle itself come from style.title.subtitle — the same source chart-family titles use — not a table-local constant. |
 
 <a id="basemapconfig"></a>
 ## BasemapConfig
@@ -1050,23 +992,13 @@ Authored overlay for SparkBarChartStyle. Produced by cascade from theme YAML.
 | `border` | [BorderStyle](#borderstyle) | ✓ | Spark_bar outer border style. |
 | `subtitle` | [SubtitleStyle](#subtitlestyle) | ✓ | Spark_bar subtitle font-sizing constants. |
 
-<a id="foreachconfig"></a>
-## ForeachConfig
-foreach loop configuration.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `query` | [ForeachQuery](#foreachquery) | Inline data source providing the rows to iterate over. |
-| `as` | str | Variable name bound to each row (accessible as {{ as.field }}). |
-| `items` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | Layout item templates resolved once per data row. |
-
 <a id="griditem"></a>
 ## GridItem
 Grid layout item with position and span.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `item` | str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)] |  | Chart name or inline chart/face definition to place in this grid cell. |
+| `item` | str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)] |  | Chart name or inline chart/face definition to place in this grid cell. |
 | `col` | int | ✓ | Column position (0-indexed). Auto-placed if omitted. |
 | `row` | int | ✓ | Row position (0-indexed). Auto-placed if omitted. |
 | `col_span` | int | ✓ | Number of columns to span (width in grid units). |
@@ -1086,8 +1018,8 @@ Tab layout item.
 | `description` | str | ✓ | Optional metadata for AI search and context tooltips. |
 | `text` | str | ✓ | Markdown text content shown in this tab. |
 | `style` | [Style](#style) | ✓ | Style patch for this tab's content area. |
-| `rows` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Vertical stack layout for this tab's content. |
-| `cols` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Horizontal layout for this tab's content. |
+| `rows` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Vertical stack layout for this tab's content. |
+| `cols` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Horizontal layout for this tab's content. |
 | `grid` | [GridLayout](#gridlayout) | ✓ | CSS-grid layout for this tab's content. |
 | `tabs` | [TabLayout](#tablayout) | ✓ | Nested tab layout (tabs within tabs). |
 
@@ -1128,6 +1060,9 @@ Box border. Does NOT cascade (ADR-003: box properties reset per level).
 | `radius` | float | ✓ | Border corner radius in pixels. |
 | `color` | str | ✓ | Border color (CSS color string). |
 | `width` | float | ✓ | Border width in pixels. |
+| `dash_array` | list[float] | ✓ | SVG stroke-dasharray pattern in pixels (e.g. [4, 4]). None means a solid border. |
+| `line_cap` | enum: "butt", "round", "square" | ✓ | SVG stroke-linecap for a dashed border. None uses the renderer default (butt). |
+| `dash_offset` | float | ✓ | SVG stroke-dashoffset in pixels. None means 0. |
 
 <a id="titlestyle"></a>
 ## TitleStyle
@@ -1242,7 +1177,6 @@ Authored overlay for VariablesStyle. Variable controls chrome styling.
 | `label` | [VariablesLabelStyle](#variableslabelstyle) | ✓ | Variable label typography. |
 | `value` | [VariablesValueStyle](#variablesvaluestyle) | ✓ | Variable value typography. |
 | `placeholder` | [VariablesPlaceholderStyle](#variablesplaceholderstyle) | ✓ | Style for unselected/hint text in variable inputs. |
-| `line_height` | float | ✓ | Line height for variable control text in pixels. |
 | `padding` | float | ✓ | Outer padding around the variables panel in pixels. |
 | `container_height` | float | ✓ | Height of the variables panel container in pixels. |
 | `container_padding` | float | ✓ | Inner padding of the variables panel container in pixels. |
@@ -1843,14 +1777,6 @@ Authored overlay for SparkStyle. Inline sparkline defaults (inside table cells).
 | `bar` | [SparkBarCellStyle](#sparkbarcellstyle) | ✓ | Style for bar/bar-normalize sparklines. |
 | `area` | [SparkAreaStyle](#sparkareastyle) | ✓ | Style for area sparklines. |
 
-<a id="subtitlestyle"></a>
-## SubtitleStyle
-Authored overlay for SubtitleStyle. Subtitle font style for chart subtitles (Table, SparkBar).
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `font` | [FontStyle](#fontstyle) | ✓ | Subtitle font style; theme populates font.size directly. |
-
 <a id="projectionstyle"></a>
 ## ProjectionStyle
 Authored overlay for ProjectionStyle. Vega-Lite map projection configuration for geo chart families.
@@ -1921,15 +1847,13 @@ Authored overlay for SparkBarCountStyle. Count-value sub-block for SparkBarChart
 | `visible` | bool | ✓ | Show count/value text next to bars. |
 | `width` | float | ✓ | Reserved width for bar count text in pixels. |
 
-<a id="foreachquery"></a>
-## ForeachQuery
-Inline data source for compile-time foreach loops.
+<a id="subtitlestyle"></a>
+## SubtitleStyle
+Authored overlay for SubtitleStyle. Subtitle font style for chart subtitles (Table, SparkBar).
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `data` | list[dict[str, Any]] | ✓ | Inline row data for compile-time iteration. |
-| `static_data` | list[dict[str, Any]] | ✓ | Alias for data; inline row data for compile-time iteration. |
-| `palette` | str | ✓ | Palette name to iterate its live stops from the palette YAML source of truth (one row per stop: {n: 1-indexed position, hex: sRGB hex}). Accepts the same 'name:steps' / 'name_r' shorthand as palette(). |
+| `font` | [FontStyle](#fontstyle) | ✓ | Subtitle font style; theme populates font.size directly. |
 
 <a id="titlewidthoffsetsstyle"></a>
 ## TitleWidthOffsetsStyle
@@ -2985,8 +2909,6 @@ Postgres source configuration.
 | `password` | str |  | Database password (dbt accepts pass as an input alias). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
-| `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
-| `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `port` | int | ✓ | Database port number. |
 | `schema` | str | ✓ | Default schema for queries. |
@@ -3012,8 +2934,6 @@ Snowflake source configuration.
 | `database` | str |  | Snowflake database name. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
-| `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
-| `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `user` | str | ✓ | Snowflake user name. Omit for token-based authentication when supported. |
 | `password` | str | ✓ | Snowflake password. Omit when using OAuth or key-pair auth. |
@@ -3054,8 +2974,6 @@ BigQuery source configuration.
 | `dataset` | str |  | BigQuery dataset name (equivalent to schema). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
-| `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
-| `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `keyfile` | str | ✓ | Path to service account JSON key file. |
 | `keyfile_json` | dict[str, str \| int \| float \| bool] | ✓ | Inline service account JSON dict. |
@@ -3097,8 +3015,6 @@ Redshift source configuration.
 | `dbname` | str |  | Redshift database name (dbt accepts database as an input alias). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
-| `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
-| `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `port` | int | ✓ | Redshift port number. |
 | `schema` | str | ✓ | Default schema for queries. |
@@ -3145,8 +3061,6 @@ MySQL source configuration.
 | `password` | str |  | MySQL password. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
-| `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
-| `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `attribution` | dict[str, str] | ✓ | Cost-attribution pairs sent with every query against this source, e.g. attribution: {team: analytics}. Emitted as BigQuery job labels and as a query comment elsewhere. Keys and values must match BigQuery's label rules ([a-z][a-z0-9_-]{0,62} / [a-z0-9_-]{0,63}). The dft_ prefix and the app key are reserved for the engine's own identity. |
 | `port` | int | ✓ | MySQL port number. |
 | `schema` | str | ✓ | Default schema for queries. |
@@ -3160,8 +3074,6 @@ DuckDB source configuration.
 | `type` | enum: "duckdb" |  | Source type identifier. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
 | `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
-| `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
-| `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `path` | str | ✓ | DuckDB file path or ':memory:' for an in-memory database. |
 | `schema` | str | ✓ | Default schema for unqualified table names (sets search_path). |
 | `duckdb_config` | dict[str, str \| int \| float \| bool] | ✓ | DuckDB connection configuration values, such as enable_external_access. |
@@ -3188,8 +3100,6 @@ SQLite source configuration.
 |-------|------|:--------:|-------------|
 | `type` | enum: "sqlite" |  | Source type identifier. |
 | `path` | str |  | Path to the SQLite database file. |
-| `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
-| `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
 
 <a id="csvsourceconfig"></a>
@@ -3199,7 +3109,7 @@ CSV file source configuration.
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `type` | enum: "csv" |  | Source type identifier. |
-| `files` | dict[str, str] |  | Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty. |
+| `files` | dict[str, str] |  | Mapping of table_name → relative path or glob pattern. Each key is the SQL table name. The value is a path relative to the project root, or a glob pattern using ``*`` (matches within a directory) and ``?`` (matches one character). A glob must match at least one file; all matched files must share the same column schema and are concatenated into one table. The fan-out limit is ``execution.max_glob_file_count`` in ``dataface.yml`` (default 1000). Required and must not be empty. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
 | `delimiter` | str | ✓ | Field delimiter character. |
 | `encoding` | str | ✓ | File encoding. |
@@ -3211,7 +3121,7 @@ Parquet file source configuration.
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `type` | enum: "parquet" |  | Source type identifier. |
-| `files` | dict[str, str] |  | Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty. |
+| `files` | dict[str, str] |  | Mapping of table_name → relative path or glob pattern. Each key is the SQL table name. The value is a path relative to the project root, or a glob pattern using ``*`` (matches within a directory) and ``?`` (matches one character). A glob must match at least one file; all matched files must share the same column schema and are concatenated into one table. The fan-out limit is ``execution.max_glob_file_count`` in ``dataface.yml`` (default 1000). Required and must not be empty. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
 
 <a id="jsonsourceconfig"></a>
@@ -3221,8 +3131,9 @@ JSON file source configuration.
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `type` | enum: "json" |  | Source type identifier. |
-| `files` | dict[str, str] |  | Mapping of table_name → file path. Each key is the SQL table name; the value is the path relative to the project root. Required and must not be empty. |
+| `files` | dict[str, str] |  | Mapping of table_name → relative path or glob pattern. Each key is the SQL table name. The value is a path relative to the project root, or a glob pattern using ``*`` (matches within a directory) and ``?`` (matches one character). A glob must match at least one file and all matched files are concatenated into one table. The fan-out limit is ``execution.max_glob_file_count`` in ``dataface.yml`` (default 1000). Required and must not be empty. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
+| `union_by_name` | bool | ✓ | When True, rows from different files in a glob set are unified by column name: columns absent in a particular file are filled with NULL.  When False (default), all files in a glob set must share the same column schema — a mismatch raises an error. |
 
 <a id="httpsourceconfig"></a>
 ## HttpSourceConfig
@@ -3271,13 +3182,3 @@ Cross-file chart reference. Bare string is coerced automatically.
 | Field | Type | Description |
 |-------|------|-------------|
 | `ref` | str | Reference path: '&lt;file&gt;.charts.&lt;name&gt;'. May start with one or more '../' segments to reach a sibling directory. A bare string value is coerced automatically. |
-
-<a id="lookmlmodelconfig"></a>
-## LookMLModelConfig
-One LookML model: a named collection of explores under a warehouse source.
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `lkml` | str | ✓ | Path to a specific .lkml model file, relative to the project root. |
-| `group_label` | str | ✓ | LookML group_label selecting this model's explores. Not yet enforced at compile time. |
-| `explores` | list[str] | ✓ | Explicit list of explore names in this model. |

dataface/agent_api/serve.py

@@ -43,7 +43,6 @@ def prepare_serve(
     max_workers: int | None,
     no_cache: bool,
     cache_path: Path | None,
-    allow_external_access: bool,
 ) -> ServeSetup | Diagnostic:
     """Validate startup config, resolve port/dialect, and build the ASGI app.
 
@@ -97,7 +96,6 @@ def prepare_serve(
         max_workers=max_workers,
         no_cache=no_cache,
         cache_path=cache_path,
-        allow_external_access_in_readonly=allow_external_access,
     )
 
     return ServeSetup(

dataface/agent_api/validate.py

@@ -227,6 +227,8 @@ def _validate_resolved(resolved: ProjectPath) -> ValidateResult:
     if resolved.is_meta:
         return _validate_meta_file(resolved)
 
+    from dataface.core.compile.errors import CompilationError
+
     try:
         result = compile_file(resolved.read_face())
     except OSError as exc:
@@ -239,6 +241,12 @@ def _validate_resolved(resolved: ProjectPath) -> ValidateResult:
                 )
             ],
         )
+    except CompilationError as exc:
+        return ValidateResult(
+            success=False,
+            path=Path(resolved.relpath),
+            errors=[exc.to_diagnostic(file=resolved.relpath)],
+        )
 
     errors = list(result.errors)
     return ValidateResult(

dataface/ai/llm.py

@@ -28,7 +28,7 @@ else:
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_OPENAI_MODEL = "gpt-5.6"
+DEFAULT_OPENAI_MODEL = "gpt-5.6-terra"
 
 
 #: Connect budget for a caller-supplied read timeout. Named so the callers that

dataface/cli/commands/render.py

@@ -172,6 +172,7 @@ def render_command(
     fail_on_chart_errors: bool = True,
     max_workers: int | None = None,
     print0: bool = False,
+    chart: str | None = None,
     *,
     project: FilesystemProject,
 ) -> str | None:
@@ -237,6 +238,7 @@ def render_command(
             raise RenderFailed([resolved])
         result = project_session.render_dashboard(
             face=resolved,
+            chart=chart,
             format=format,
             variables=variables,
             use_cache=use_cache,
@@ -273,6 +275,7 @@ def render_command_from_yaml(
     fail_on_chart_errors: bool = True,
     max_workers: int | None = None,
     print0: bool = False,
+    chart: str | None = None,
     *,
     project: FilesystemProject,
 ) -> str | None:
@@ -329,6 +332,7 @@ def render_command_from_yaml(
         face = InMemoryFace(yaml_content, path=None)
         result = project_session.render_dashboard(
             face=face,
+            chart=chart,
             format=format,
             variables=variables,
             use_cache=use_cache,
@@ -439,6 +443,7 @@ def render_commands(
     max_workers: int | None = None,
     print0: bool = False,
     fail_fast: bool = False,
+    chart: str | None = None,
 ) -> None:
     """Render one or more dashboards, printing output paths to stdout.
 
@@ -485,6 +490,7 @@ def render_commands(
                 fail_on_chart_errors=fail_on_chart_errors,
                 max_workers=max_workers,
                 print0=print0,
+                chart=chart,
             )
         except RenderFailed as exc:
             print_diagnostics(exc.errors, json_output=json_errors)