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

dataface/DATAFACE_SYNTAX.md

@@ -1119,6 +1119,7 @@ The registry is being filled out incrementally — some compile-time and variabl
 - **`DF-COMPILE-SOURCE-REQUIRED`** — a SQL query has no `source:` and no default is configured. Set the source on the query (`source: my_db`), at the face level (`source:` or `sources.default`), or project-wide via `sources.default` in `dataface.yml`.
 - **`DF-COMPILE-UNKNOWN-QUERY`** — a chart's `query:` references a name that does not appear under `queries:`. Check for a typo or add the missing query.
 - **`DF-COMPILE-EXTRA-FIELD`** — the face YAML contains a field not recognised by the schema. Remove it or check the schema for supported keys.
+- **`DF-COMPILE-WRONG-SHAPE`** — a YAML field that expects a mapping (nested block) received a scalar or sequence instead. The error hint lists the available keys. For example, `axis_x.label: "hi"` must be a mapping: `axis_x:\n  label:\n    angle: -45`.
 - **`DF-COMPILE-SQL-LITERAL-NEWLINES`** — a SQL field contains a literal `\n` (backslash + n) from single-quoted YAML. Use a YAML block scalar (`sql: |`) to write multiline SQL.
 
 ### Render errors

dataface/agent_api/describe.py

@@ -356,7 +356,7 @@ def _describe_one_path(
         for pf in project.iter_faces(under=under, recursive=True)
         if pf.is_yaml
         and not pf.is_private
-        and not pf.sibling(INSPECT_TEMPLATE_MANIFEST).exists()
+        and not pf.parent.file(INSPECT_TEMPLATE_MANIFEST).exists()
     )
     if not faces:
         return [

dataface/agent_api/describe_query.py

@@ -75,7 +75,7 @@ def describe_query(
         cfg = adapter_registry.resolve_source_config(source)
 
         if cfg.get("type") == "duckdb":
-            # Run DESCRIBE via the registry's existing read-only SqlAdapter so
+            # Run DESCRIBE via the registry's existing read-only DuckDBAdapter so
             # we don't open a writable dbt-duckdb connection that would conflict
             # with dft serve.
             cols = _duckdb_describe(sql, source, adapter_registry)
@@ -110,7 +110,7 @@ def describe_query(
 def _duckdb_describe(
     sql: str, source: str | None, adapter_registry: AdapterRegistry
 ) -> list[DescribeQueryColumn]:
-    """Run DESCRIBE ({sql}) via the registry's read-only SqlAdapter."""
+    """Run DESCRIBE ({sql}) via the registry's read-only DuckDBAdapter."""
     from dataface.core.compile.models.query.normalized import SqlQuery
 
     result = adapter_registry.execute(SqlQuery(sql=f"DESCRIBE ({sql})", source=source))

dataface/agent_api/docs/yaml-reference.md

@@ -30,7 +30,7 @@ AuthoredFace (dataface) definition from YAML.
 | `width` | str \| int | ✓ | Width when nested (e.g., '50%', '400px', or an integer in pixels). |
 | `height` | str \| int | ✓ | Height when nested (e.g., '300px' or an integer in pixels). |
 | `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Controls whether this layout item is rendered. Accepts a bool, variable name, Jinja expression, or {query, column} probe. |
-| `theme` | str | ✓ | Theme name (e.g., 'editorial', 'cream', 'stark'). |
+| `extends` | str \| list[str] | ✓ | Face name(s) or relative path(s) this face inherits from, low to high priority. |
 | `auto_link` | bool | ✓ | When True, table charts with no explicit link: automatically link each row to its canonical /data/<source>/<schema>/<table>/detail/ page. Default off. Explicit link: always wins; set link: ~ to suppress per chart. |
 
 <a id="sourcessection"></a>
@@ -1149,6 +1149,7 @@ Authored overlay for ChartsStyle. Registry of all chart-type styles plus shared
 | `color` | str \| [StyleColorConfig](#stylecolorconfig) | ✓ | Chart-local static mark color (CSS string) or gradient scale config; None uses the theme palette. |
 | `title` | [TitleStyle](#titlestyle) | ✓ | Chart-level title style override; None inherits the theme title style. |
 | `dashes` | list[list[int]] | ✓ | Ordered list of Vega-Lite strokeDash arrays for line-family categorical encoding; None disables dash emission. |
+| `default_width` | float | ✓ | Default chart width in pixels when no explicit width is set. |
 | `default_chart_height` | float | ✓ | Fallback chart height in pixels when aspect-ratio sizing is unavailable. |
 | `default_table_height` | float | ✓ | Placeholder table height in pixels; replaced by data-aware row-count sizing at render time. |
 | `label_usable_ratio` | float | ✓ | Fraction of chart width usable for axis labels (0–1); labels are tilted when full labels exceed this width. |
@@ -1222,15 +1223,19 @@ Authored overlay for PageStyle. Page-level (outer HTML canvas) styling.
 
 <a id="footerstyle"></a>
 ## FooterStyle
-Authored overlay for FooterStyle. Authored visibility toggle for the page footer chrome.
+Authored overlay for FooterStyle. Page footer chrome: visibility, attribution text, font, and rule.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `visible` | bool | ✓ | Show the footer attribution line. |
+| `text` | str | ✓ | Attribution text shown in the footer. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Footer text font style (size and color required). |
+| `y_offset` | float | ✓ | Vertical offset from bottom edge in pixels. |
+| `rule` | [FooterRule](#footerrule) | ✓ | Hairline rule above footer text; null disables the rule. |
 
 <a id="timestampstyle"></a>
 ## TimestampStyle
-Authored overlay for TimestampStyle. Authored timestamp chrome: visibility, placement, strftime format, and font.
+Authored overlay for TimestampStyle. Authored timestamp chrome: visibility, placement, strftime format, font, and y-offset.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
@@ -1238,6 +1243,7 @@ Authored overlay for TimestampStyle. Authored timestamp chrome: visibility, plac
 | `position` | enum: "top", "footer" | ✓ | Timestamp row: top page chrome or footer baseline. |
 | `align` | enum: "left", "right" | ✓ | Timestamp horizontal alignment within its row. |
 | `format` | str | ✓ | strftime format string for the render timestamp. |
+| `y` | float | ✓ | Y-coordinate for top-positioned timestamp in pixels. |
 | `font` | [FontStyle](#fontstyle) | ✓ | Timestamp font style overrides (size, color, weight, ...). |
 
 <a id="spacingvalues"></a>
@@ -1279,7 +1285,7 @@ A data_table row that reads a column's raw per-x value.
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `source` | str |  | Query column the row reads from (per-x raw value). |
-| `format` | str | ✓ | D3-style format string (Vega-Lite format parity). Optional. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | D3 format string or format config object. Optional; inherits the chart measure format when omitted and source matches chart.y. |
 | `label` | str | ✓ | Left-stub row label. Optional. |
 
 <a id="chartdatatableaggregate"></a>
@@ -1290,7 +1296,7 @@ A data_table row that reads an aggregate of a column grouped by x.
 |-------|------|:--------:|-------------|
 | `aggregate` | enum: "sum", "avg", "min", "max", "median", "count", "count_distinct" |  | Aggregate operation applied per x-group. One of: sum, avg, min, max, median, count, count_distinct. Exact names only — no aliases (spec G4). |
 | `source` | str |  | Query column being aggregated. Always required alongside `aggregate:` (spec G2). |
-| `format` | str | ✓ | D3-style format string for the aggregated value. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | D3 format string or format config object for the aggregated value. Optional. |
 | `label` | str | ✓ | Column header label override for this row. |
 
 <a id="chartdatatableperseries"></a>
@@ -1302,11 +1308,11 @@ A data_table entry that expands into one row per color: series.
 | `per_series` | str |  | Query column the row reads from (per-x, per-series value). |
 | `by_measure` | bool | ✓ | When True, expand one row reading the named measure field directly (no color: groupby). Required for multi-y charts where each measure is its own y-field rather than a color-encoded series. |
 | `label` | str | ✓ | Row label displayed in the strip's label gutter. When None and by_measure=True, the per_series field name is used. Has no effect when by_measure=False (series name is the label). |
-| `format` | str | ✓ | D3-style format string (Vega-Lite format parity). Optional. |
+| `format` | str \| [FormatConfig](#formatconfig) | ✓ | D3 format string or format config object. Optional. |
 
 <a id="fontstyle"></a>
 ## FontStyle
-Text appearance. Cascades as a unit (ADR-005: color inside font).
+Text appearance. Merged as a unit.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
@@ -1445,7 +1451,6 @@ Authored overlay for DataTableStyle. Attached data_table style. Lives at style.c
 | `divider` | [RuleStyle](#rulestyle) | ✓ | Rule at the boundary between the chart plot and the data strip. For position='bottom': rule sits above the strip (below the axis). For position='top': rule sits below the strip rows (above the plot top). |
 | `row` | [DataTableRowStyle](#datatablerowstyle) | ✓ | Data_table row padding and rule style. |
 | `label` | [DataTableLabelStyle](#datatablelabelstyle) | ✓ | Row label (series name) style. |
-| `number_align` | enum: "left", "right", "decimal" | ✓ | Alignment of numeric values in data_table cells. |
 | `padding_top` | float | ✓ | Padding above the topmost strip row in pixels. For position='bottom': gap between axis labels and the first row. For position='top': space above the topmost row (outer edge of strip). |
 | `padding_bottom` | float | ✓ | Padding below the last strip row in pixels. For position='bottom': space below the last row. For position='top': gap between the last row and the plot top edge. |
 | `label_max_lines` | int | ✓ | Number of x-axis label lines to reserve in the axis gap (only used for position='bottom'; ignored for position='top'). Typically 1 or 2. |
@@ -2049,6 +2054,15 @@ Authored overlay for InputStyle.
 | `widths` | [InputWidths](#inputwidths) | ✓ | Per-input-type default widths. |
 | `range` | [RangeDefaults](#rangedefaults) | ✓ | Range input default min/max/step values. |
 
+<a id="footerrule"></a>
+## FooterRule
+Authored overlay for FooterRule. Hairline rule above the footer attribution text. None = no rule.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `color` | str | ✓ | Rule stroke color. |
+| `stroke_width` | float | ✓ | Rule stroke width in pixels. |
+
 <a id="legendlabelstyle"></a>
 ## LegendLabelStyle
 Authored overlay for LegendLabelStyle.
@@ -2237,7 +2251,7 @@ Authored overlay for LineMarkStyle. Line mark stroke, interpolation, and halo. P
 
 <a id="pointmarkstyle"></a>
 ## PointMarkStyle
-Authored overlay for PointMarkStyle. Point mark style (data-point markers on line/area/scatter charts).
+Authored overlay for PointMarkStyle. Point mark style (data-point markers on scatter/point/line/area charts).
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
@@ -2248,7 +2262,7 @@ Authored overlay for PointMarkStyle. Point mark style (data-point markers on lin
 | `filled` | bool | ✓ | Whether points are filled; None uses VL default. |
 | `fill` | str | ✓ | Point interior fill color; only applied when filled=false. |
 | `stroke_width` | float | ✓ | Stroke width in pixels for hollow point rings; None uses VL default. |
-| `labels` | [PointLabelsStyle](#pointlabelsstyle) | ✓ | Value label style for point marks. |
+| `labels` | [PointLabelsStyle](#pointlabelsstyle) | ✓ | Value label style for point marks. On line charts, setting marks.point.labels is an alias for marks.line.labels. |
 
 <a id="rulemarkstyle"></a>
 ## RuleMarkStyle
@@ -2540,7 +2554,7 @@ Authored overlay for BarLabelsStyle. Bar mark value-label config. Extends MarkLa
 | `dx` | int | ✓ | Horizontal pixel offset for value labels; overrides the position default. |
 | `dy` | int | ✓ | Vertical pixel offset for value labels; overrides the position default. |
 | `font` | [FontStyle](#fontstyle) | ✓ | Value label font style (color, size, family, etc.). |
-| `position` | enum: "top", "inside_top", "middle" | ✓ | Label position relative to the bar. 'top' places labels above the bar top (outside). 'inside_top' places labels just inside the top edge. 'middle' centers labels vertically in the bar. |
+| `position` | enum: "above", "top", "middle", "middle_aligned", "bottom" | ✓ | Label position relative to the bar. 'above' places labels above the bar top (outside). 'top' places labels just inside the top edge. 'middle' centers labels vertically in the bar. 'middle_aligned' centers all labels at a common height (mean of bar heights / 2). 'bottom' places labels just inside the bottom edge. |
 
 <a id="strokestyle"></a>
 ## StrokeStyle

dataface/agent_api/project_session.py

@@ -30,6 +30,7 @@ from dataface.agent_api.validate import (
 from dataface.core import dashboard as _core_dashboard
 from dataface.core.compile.config import (
     ProjectSourcesConfig,
+    get_export_config,
 )
 from dataface.core.execute.adapters.adapter_registry import (
     AdapterRegistry,
@@ -43,12 +44,12 @@ from dataface.core.inspect.query_validator import (
 )
 from dataface.core.project import Project
 from dataface.core.project_roots import find_project_root
+from dataface.core.render.board_links import LinkContext
 
 if TYPE_CHECKING:
     from dataface.core.dashboard import RenderedDashboard, RenderFormat
     from dataface.core.execute.source_resolver import SourceResolver
     from dataface.core.inspect.query_validator import RelationshipContext
-    from dataface.core.render.board_links import LinkContext
 
 # Probe at module load time — single find_spec call per process.
 _SUPER_SCHEMA_AVAILABLE: bool = (
@@ -416,6 +417,12 @@ class ProjectSession:
         link_context: LinkContext | None = None,
         **render_options: Any,
     ) -> RenderedDashboard:
+        # When the caller does not supply a link_context, derive origin from the
+        # project's public_url config so dft render exports carry fully-qualified links.
+        if link_context is None:
+            public_url = get_export_config(self.project).public_url
+            if public_url:
+                link_context = LinkContext(runtime="serve", origin=public_url)
         return _core_dashboard.render_dashboard(
             path=path,
             yaml_content=yaml_content,

dataface/agent_api/render_face.py

@@ -8,13 +8,15 @@ from pathlib import Path
 from typing import Any
 
 from dataface.agent_api.project_session import ProjectSession
+from dataface.core.compile.config import get_export_config
 from dataface.core.compile.markdown import (
     MARKDOWN_NOT_FACE_MESSAGE,
     is_markdown_face,
     markdown_to_yaml,
 )
 from dataface.core.execute.cache_backend import QueryResultCache
-from dataface.core.project import Project, ProjectFile
+from dataface.core.project import Project, ProjectDirectory
+from dataface.core.render.board_links import LinkContext
 from dataface.core.render.face_api import compile_and_render
 
 
@@ -76,21 +78,26 @@ def render_face(
         # project-relative handle; nested sub-file refs are unsupported in that
         # mode (relative reads still resolve via face_dir below).
         try:
-            base_file: ProjectFile | None = p.file_for_path(face_file)
+            base_dir: ProjectDirectory | None = p.directory_for_path(face_file.parent)
         except ValueError:
-            base_file = None
+            base_dir = None
+        extra = dict(options)
+        if "link_context" not in extra:
+            public_url = get_export_config(p).public_url
+            if public_url:
+                extra["link_context"] = LinkContext(runtime="serve", origin=public_url)
         return compile_and_render(
             yaml_content,
             p,
             adapter_registry=project_session.adapter_registry,
             cache=cache,
             warnings_ignore=warnings_ignore,
-            base_file=base_file,
+            base_dir=base_dir,
             face_dir=face_file.parent,
             format=format,
             variables=variables,
             use_cache=use_cache,
-            **options,
+            **extra,
         )
     finally:
         project_session.close()

dataface/agent_api/validate.py

@@ -15,13 +15,20 @@ from dataface.agent_api._paths import (
     resolve_scoped_path,
 )
 from dataface.core.compile.errors import DatafaceError
-from dataface.core.errors import DF_UNKNOWN_INTERNAL, StructuredError
+from dataface.core.errors import (
+    DF_COMPILE_META_SCHEMA,
+    DF_UNKNOWN_INTERNAL,
+    StructuredError,
+)
 from dataface.core.project import Project
 from dataface.core.render.warnings.base import RenderWarning
 
 if TYPE_CHECKING:
     from dataface.agent_api.project_session import ProjectSession
 
+# Filenames treated as cascade fragments (FacePatch), not standalone compilable faces.
+_META_FILENAMES: frozenset[str] = frozenset({"meta.yaml", "meta.yml"})
+
 
 class ValidateDashboardArgs(BaseModel):
     """Validate a face YAML file without executing queries.
@@ -116,7 +123,8 @@ def _validate_one_path(
         for pf in project.iter_faces(under=under, recursive=True)
         if pf.is_yaml
         and not pf.is_private
-        and not pf.sibling(INSPECT_TEMPLATE_MANIFEST).exists()
+        and Path(pf.relpath).name not in _META_FILENAMES
+        and not pf.parent.file(INSPECT_TEMPLATE_MANIFEST).exists()
     )
     if not faces:
         return [
@@ -134,6 +142,46 @@ def _validate_one_path(
     return [validate(f, project=project) for f in faces]
 
 
+def _validate_meta_file(path: Path) -> ValidateResult:
+    """Validate a meta.yaml as a FacePatch fragment — no layout required."""
+    from pydantic import ValidationError as PydanticValidationError
+
+    from dataface.core.compile.errors import CompilationError
+    from dataface.core.compile.meta import load_meta_file
+    from dataface.core.compile.models.face.patch import FacePatch
+
+    try:
+        meta_data, _ = load_meta_file(path)
+    except CompilationError as exc:
+        return ValidateResult(
+            success=False,
+            path=path,
+            errors=[
+                DatafaceError.from_code(
+                    DF_COMPILE_META_SCHEMA, message=str(exc)
+                ).to_structured(file=str(path))
+            ],
+        )
+
+    try:
+        FacePatch.model_validate(meta_data)
+    except PydanticValidationError as exc:
+        errors = [
+            DatafaceError.from_code(
+                DF_COMPILE_META_SCHEMA,
+                message=(
+                    f"{' → '.join(str(loc) for loc in e['loc'])}: {e['msg']}"
+                    if e["loc"]
+                    else e["msg"]
+                ),
+            ).to_structured(file=str(path))
+            for e in exc.errors()
+        ]
+        return ValidateResult(success=False, path=path, errors=errors)
+
+    return ValidateResult(success=True, path=path)
+
+
 def validate(path: Path, *, project: Project) -> ValidateResult:
     """Fast YAML schema + cross-reference validation. No warehouse, no execute."""
     from dataface.core.compile.compiler import compile_file
@@ -164,6 +212,9 @@ def validate(path: Path, *, project: Project) -> ValidateResult:
             ],
         )
 
+    if resolved.name in _META_FILENAMES:
+        return _validate_meta_file(resolved)
+
     try:
         result = compile_file(project.file_for_path(resolved), project=project)
     except OSError as exc:

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

@@ -121,6 +121,8 @@ rows:
   - cols: [by_region, by_product]
 ```
 
+Don't put a `title:` on every row. A section heading over already-labeled charts is repetition, not structure — group with proximity instead. Reach for a row `title:` only when the dashboard is becoming more of a narrative — when there's accompanying `text:` prose, or the heading genuinely says something the charts don't (a shared scope like "Last 30 days", a real mode boundary). A title with no text alongside it usually means the title and the sectioning weren't needed — drop it. (This is dashboard guidance — in a **report**, sections are good: narrative `## …` headings in `text:` blocks carry the prose between charts — see `{{ s_skill_design_report }}`.)
+
 ### Step 6 — Save the Final YAML (when saving applies)
 
 Skip this step when you are previewing ephemerally — see "Previewing vs. saving a face" above; your host decides the default. On hosts that offer the user a Save control over the rendered preview (the Cloud chat, for example), saving is the user's click — don't write the file yourself. When the host has no such control and saving applies, write the YAML to a **new** face under `faces/` (never silently fold into an existing one) with your normal file-edit mechanism, then:

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

@@ -107,6 +107,8 @@ Most important information first, following Western reading pattern (top-left
 - Related metrics grouped by proximity
 - Consistent styling throughout
 
+**Section titles — use sparingly.** A `title:` on a `rows:`/`cols:`/`grid` item renders a heading above that group. On a dense, chart-only dashboard it is almost always noise: the KPIs and chart titles inside already say what each group is, so a row header like "Core Metrics", "Trendlines", or "Overview" just repeats them. Group with proximity and whitespace, not labels. Reach for a section title only when the dashboard is becoming more of a narrative — when there's accompanying `text:` prose that introduces the section, or when the heading genuinely says something the charts don't (a scoping qualifier the charts share like "Last 30 days" or "North America", a real mode boundary the layout alone wouldn't signal). A title with no text alongside it is the tell: usually it means neither the title nor the sectioning was needed — delete it and let the charts speak. This is guidance for designing **dashboards** — in a **report**, sections are good: there the narrative is the point, and `## …` headings in `text:` blocks carry the prose that introduces each section.
+
 ### 5. Color & Visual Design
 
 - **Gray is default** — muted everything, ONE accent color for emphasis
@@ -170,6 +172,7 @@ Before delivering:
 | Pie chart with 7 segments | Use a bar chart instead |
 | Decorative color | Color must encode data or meaning |
 | Generic titles | Titles should state what the chart answers |
+| Section title over every row | Drop it — labeled charts don't need a heading repeating them. Reserve titles for reports or a real scoping/mode boundary |
 | Scrolling dashboard | Reduce charts or split dashboards |
 
 ## Rationalizations to Resist
@@ -180,3 +183,4 @@ Before delivering:
 | "Pie chart is fine for 6 categories" | It's not — humans compare angles poorly. Use bar. |
 | "The legend explains the colors" | Direct labels are always better than legends. |
 | "More charts = more value" | More charts = more noise. Each must earn its place. |
+| "Section titles organize the dashboard" | They organize a *report*. On a dense dashboard the charts are already labeled — a heading per row is repetition, not structure. |

dataface/ai/skills/two-by-two-grid-overview/SKILL.md

@@ -37,8 +37,7 @@ default.
 
 ```yaml
 rows:
-  - title: Overview
-    cols:
+  - cols:
       - revenue_trend    # top-left
       - cost_trend       # top-right
   - cols:
@@ -46,6 +45,8 @@ rows:
       - by_product       # bottom-right
 ```
 
+No section title — the four labeled charts are self-explanatory, and a heading over them just repeats their titles.
+
 Each chart is defined as usual in `charts:`. The 2×2 is purely a layout
 decision — swap in any chart type per cell.
 
@@ -57,7 +58,7 @@ See `examples/two-by-two-grid-overview.yml` for the inline-data worked example.
 |---|---|---|
 | 2×3 (six cells) | Add a third `cols:` row | Six equally-weighted metrics |
 | Asymmetric | `width: "60%"` on one cell | Slightly more emphasis on one chart |
-| Section title | `title:` on a `rows:` item | Separate the two rows conceptually |
+| Section title | `title:` on a `rows:` item | Rarely needed — only when a heading adds something the charts don't (a shared scope, a mode boundary). Default to omitting it |
 | Grid layout | `grid: columns: 24` + `col_span: 12` | Finer column control |
 
 ## Common pitfalls

dataface/cli/commands/serve.py

@@ -46,21 +46,46 @@ def serve_command(
     Returns:
         None (exits with code 0 on success, 1 on errors)
     """
+    from dataface.core.compile.config import list_built_in_themes, load_config
+    from dataface.core.errors import DF_SERVE_INVALID_DEFAULT_THEME
     from dataface.core.project import Project
     from dataface.core.project_roots import find_dft_root, infer_dialect_from_dbt
-    from dataface.core.serve.bootstrap import apply_default_theme
     from dataface.core.serve.port import resolve_port
     from dataface.core.serve.server import create_server
 
     # Resolve the project root: --project-dir if given, else discover from cwd.
     project_dir = project_dir or find_dft_root() or Path.cwd()
 
-    # Resolve default theme (env var > dataface.yml theme: > built-in default).
-    # Fails fast on invalid values.
+    core_project = Project(project_dir)
+
+    # Validate DFT_DEFAULT_THEME at startup — fail fast before serving any request.
+    # The env var is read per-compilation by get_default_theme_name(); validation
+    # here ensures the user sees a clear error at startup rather than on first render.
+    env_theme = os.environ.get(
+        "DFT_DEFAULT_THEME"
+    )  # noqa: TID251 — DFT_DEFAULT_THEME knob
+    # Empty string is treated as unset (matches get_default_theme_name, which
+    # falls back to the shipped default) — only a non-empty unknown name errors.
+    if env_theme:
+        available = list_built_in_themes()
+        if env_theme not in available:
+            err = DatafaceError.from_code(
+                DF_SERVE_INVALID_DEFAULT_THEME,
+                source="DFT_DEFAULT_THEME env var",
+                theme=env_theme,
+                available=", ".join(available),
+            )
+            print_structured_errors([err.to_structured()])
+            raise typer.Exit(1) from None
+
+    # Validate dataface.yml wholesale: stray keys (style:, board:, theme:, etc.) are a
+    # hard error here at startup rather than silently ignored.
+    from pydantic import ValidationError as _PydanticError
+
     try:
-        apply_default_theme(Project(project_dir))
-    except DatafaceError as e:
-        print_structured_errors([e.to_structured()])
+        load_config(core_project)
+    except _PydanticError as e:
+        typer.echo(f"dataface.yml validation error: {e}", err=True)
         raise typer.Exit(1) from None
 
     # Resolve port: --port > DFT_PORT > dataface.yml server.port > hash(project_dir)

dataface/core/compile/__init__.py

@@ -43,10 +43,9 @@ from dataface.core.compile.errors import (
 )
 from dataface.core.compile.meta import (
     MetaLintConfig,
-    apply_meta_to_face,
     find_meta_files,
     load_meta_file,
-    resolve_meta_chain,
+    resolve_meta_lint,
 )
 from dataface.core.compile.models.chart.authored import (
     AreaChart,
@@ -208,10 +207,9 @@ __all__ = [
     "get_project_warnings_ignore",
     # Meta configuration
     "MetaLintConfig",
-    "apply_meta_to_face",
     "find_meta_files",
     "load_meta_file",
-    "resolve_meta_chain",
+    "resolve_meta_lint",
     # Type guards
     "is_face",
     "is_chart",