dataface 0.1.6.dev82__py3-none-any.whl → 0.1.6.dev183__py3-none-any.whl

dataface/agent_api/_paths.py

@@ -6,9 +6,8 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from dataface.core.project_roots import (
-    discover_render_context as discover_render_context,
-    discovery_boundary_for_face as discovery_boundary_for_face,
     find_dft_root as find_dft_root,
+    find_project_root as find_project_root,
 )
 from dataface.core.scoped_paths import (
     resolve_scoped_path as resolve_scoped_path,
@@ -60,8 +59,8 @@ class FaceRenderContext:
     """Path resolution result from a face path + project root.
 
     Adapter registry is built by `ProjectSession.open`, not by the context — call sites
-    open a `ProjectSession` with `project_root` + `dbt_project_path` and read the
-    registry off `project.adapter_registry`.
+    open a `ProjectSession` with `project_root` and read the registry off
+    `project.adapter_registry`.
     """
 
     face_file: Path
@@ -69,18 +68,16 @@ class FaceRenderContext:
     scoped_base: Path
     project_root: Path
     output_dir: Path
-    dbt_project_path: Path | None = None
 
 
 def build_face_render_context(
     face_path: Path,
     project_dir: Path,
 ) -> FaceRenderContext:
-    """Resolve a face path and walk for dbt context.
+    """Resolve a face path against the given project root.
 
-    ``project_dir`` is authoritative; the walk only contributes the dbt project
-    path. Callers must resolve their project dir first (e.g. via
-    ``resolve_project_dir(raw_dir)`` at the CLI boundary).
+    ``project_dir`` is authoritative. Callers must resolve their project dir first
+    (e.g. via ``resolve_project_dir(raw_dir)`` at the CLI boundary).
     """
     if face_path.is_absolute():
         face_file = face_path.resolve()
@@ -89,10 +86,6 @@ def build_face_render_context(
     else:
         face_file = (project_dir / face_path).resolve()
 
-    _, dbt_project_path = discover_render_context(
-        face_file.parent,
-        discovery_boundary_for_face(face_file.parent, project_dir),
-    )
     project_root = project_dir
 
     try:
@@ -109,7 +102,6 @@ def build_face_render_context(
         scoped_base=project_root,
         project_root=project_root,
         output_dir=project_root,
-        dbt_project_path=dbt_project_path,
     )
 
 
@@ -122,21 +114,18 @@ class YamlRenderContext:
 
     project_root: Path
     output_dir: Path
-    dbt_project_path: Path | None = None
 
 
 def build_yaml_render_context(
     project_dir: Path,
 ) -> YamlRenderContext:
-    """Walk for dbt context anchored at the given project root.
+    """Resolve the project root for rendering inline YAML.
 
     ``project_dir`` is authoritative. Callers must resolve their project dir
     first (e.g. via ``resolve_project_dir(raw_dir)`` at the CLI boundary).
     """
     project_root = project_dir.resolve()
-    _, dbt_project_path = discover_render_context(project_root, None)
     return YamlRenderContext(
         project_root=project_root,
         output_dir=project_root,
-        dbt_project_path=dbt_project_path,
     )

dataface/agent_api/docs/yaml-reference.md

@@ -128,8 +128,8 @@ Authored patch for bar and histogram charts.
 | `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
 | `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
 | `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
-| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
-| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
 | `style` | [BarChartStyle](#barchartstyle) | ✓ | Chart-local style overrides. |
 
 <a id="linechart"></a>
@@ -156,8 +156,8 @@ Authored patch for line charts.
 | `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
 | `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
 | `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
-| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
-| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
 | `style` | [LineChartStyle](#linechartstyle) | ✓ | Chart-local style overrides. |
 
 <a id="areachart"></a>
@@ -184,8 +184,8 @@ Authored patch for area charts.
 | `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
 | `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
 | `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
-| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
-| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
 | `style` | [AreaChartStyle](#areachartstyle) | ✓ | Chart-local style overrides. |
 
 <a id="scatterchart"></a>
@@ -212,8 +212,8 @@ Authored patch for scatter charts.
 | `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
 | `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
 | `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
-| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
-| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
 | `size` | str | ✓ | Field used to size-encode data points (quantitative). |
 | `shape` | str | ✓ | Field used to shape-encode data points (categorical). |
 | `style` | [ScatterChartStyle](#scatterchartstyle) | ✓ | Chart-local style overrides. |
@@ -242,8 +242,8 @@ Authored patch for heatmap charts.
 | `sort` | [ChartSort](#chartsort) | ✓ | Sort configuration: field to sort by and direction (asc/desc). |
 | `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
 | `data_table` | [ChartDataTable](#chartdatatable) | ✓ | Optional mini data-grid attached below/above the chart. |
-| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
-| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Not valid on kpi, table, callout, or spark_bar — those renderers own their own sizing contracts. |
+| `height` | int \| float | ✓ | Explicit chart height in pixels. Positive number only. When set, overrides aspect_ratio and theme cascade. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
+| `width` | int \| float | ✓ | Chart width hint in pixels. Positive number only. Used by the label-overlap heuristic to determine whether x-axis labels need tilting. Does not override the layout slot width — the chart still fills its allocated container. Only valid on cartesian chart families: area, bar, heatmap, histogram, line, and scatter. Other chart families use renderer-owned or layout-owned sizing contracts. |
 | `style` | [HeatmapChartStyle](#heatmapchartstyle) | ✓ | Chart-local style overrides. |
 
 <a id="piechart"></a>
@@ -1082,8 +1082,8 @@ Authored overlay for TitleStyle. Board and face titles.
 |-------|------|:--------:|-------------|
 | `font` | [FontStyle](#fontstyle) | ✓ | Title font style overrides. |
 | `line_height` | float | ✓ | Line height multiplier for titles and markdown headings. Headings typically want a tighter multiplier than body prose. |
-| `sizes` | list[float] | ✓ | Font sizes for the H1–H6 heading ramp, indexed by ``face.level - 1``. Combined with ``width_offsets`` at render time to size titles responsively by card width. |
-| `width_offsets` | [TitleWidthOffsetsStyle](#titlewidthoffsetsstyle) | ✓ | Additive level offsets by card width (tiny/narrow/medium/wide). Added to the title's base level before indexing ``sizes``. Consumed by chart_title_spec / face_title_spec. |
+| `sizes` | list[float] | ✓ | Font sizes for the H1–H6 heading ramp, indexed by ``face.level - 1``. Face/prose titles index this ramp directly (no width input). Object titles (chart/table/spark) combine ``width_offsets`` with a fixed object-title anchor to pick a slot. |
+| `width_offsets` | [TitleWidthOffsetsStyle](#titlewidthoffsetsstyle) | ✓ | Additive level offsets by card width (tiny/narrow/medium/wide). Consumed by ``chart_title_spec`` only — object titles add the tier offset to a fixed anchor to pick an H slot from ``sizes``. Face/prose titles are level-only and do not consult these. |
 | `min_height` | float | ✓ | Minimum title row height in pixels. |
 | `overflow` | str | ✓ | Text overflow mode (clip, truncate, wrap-two, wrap). |
 | `position` | [TitlePositionStyle](#titlepositionstyle) | ✓ | Vega-Lite title positioning: anchor, angle, offset, baseline. |
@@ -2372,10 +2372,11 @@ Authored overlay for SparkAreaStyle.
 
 <a id="geoshapemarkstyle"></a>
 ## GeoshapeMarkStyle
-Authored overlay for GeoshapeMarkStyle. Geoshape (choropleth) mark boundary stroke.
+Authored overlay for GeoshapeMarkStyle. Geoshape (choropleth) mark fill and boundary stroke.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
+| `fill` | str | ✓ | Neutral geoshape fill color. |
 | `stroke` | [StrokeStyle](#strokestyle) | ✓ | Geoshape boundary stroke style. |
 
 <a id="circlemarkstyle"></a>

dataface/agent_api/project_session.py

@@ -17,7 +17,6 @@ else:
 # Verb-forwarder imports use SUBMODULES so test monkeypatches on the
 # module attribute affect the call site.
 from dataface.agent_api import (
-    dashboards as _dashboards,
     describe as _describe,
     describe_query as _describe_query,
     query as _query,
@@ -42,7 +41,7 @@ from dataface.core.inspect.query_validator import (
     validate_query as _core_validate_query,
 )
 from dataface.core.project import Project
-from dataface.core.project_roots import discover_render_context
+from dataface.core.project_roots import find_project_root
 
 if TYPE_CHECKING:
     from dataface.core.dashboard import RenderedDashboard, RenderFormat
@@ -71,7 +70,6 @@ class ProjectSession:
     cache: DuckDBCache | None
     _owns_registry: bool
     _read_only: bool
-    _dbt_project_path: Path | None
     _connection_string: str | None
     _dialect: str
     _target: str
@@ -96,7 +94,6 @@ class ProjectSession:
             # short-circuit the build on first access.
             self.__dict__["adapter_registry"] = adapter_registry
         self._read_only = read_only
-        self._dbt_project_path = None
         self._connection_string = None
         self._dialect = "duckdb"
         self._target = "dev"
@@ -111,7 +108,6 @@ class ProjectSession:
         *,
         cache: DuckDBCache | None = None,
         read_only: bool = True,
-        dbt_project_path: Path | None = None,
         connection_string: str | None = None,
         dialect: str = "duckdb",
         target: str = "dev",
@@ -135,7 +131,6 @@ class ProjectSession:
             cache=cache,
             read_only=read_only,
         )
-        session._dbt_project_path = dbt_project_path
         session._connection_string = connection_string
         session._dialect = dialect
         session._target = target
@@ -151,7 +146,6 @@ class ProjectSession:
         *,
         cache: DuckDBCache | None = None,
         read_only: bool = True,
-        dbt_project_path: Path | None = None,
         connection_string: str | None = None,
         dialect: str = "duckdb",
         target: str = "dev",
@@ -166,7 +160,6 @@ class ProjectSession:
         this method stores it directly without re-wrapping.
         """
         session = cls(project=project, cache=cache, read_only=read_only)
-        session._dbt_project_path = dbt_project_path
         session._connection_string = connection_string
         session._dialect = dialect
         session._target = target
@@ -185,13 +178,8 @@ class ProjectSession:
     ) -> Self:
         """Open a ProjectSession rooted at the project directory discovered upward from face_file."""
         resolved = Path(face_file).resolve()
-        project_root, dbt_project_path = discover_render_context(resolved.parent, None)
-        return cls.open(
-            project_root,
-            read_only=read_only,
-            cache=cache,
-            dbt_project_path=dbt_project_path,
-        )
+        project_root = find_project_root(resolved.parent, boundary=None)
+        return cls.open(project_root, read_only=read_only, cache=cache)
 
     def __enter__(self) -> Self:
         return self
@@ -210,7 +198,6 @@ class ProjectSession:
         return build_adapter_registry(
             self.project,
             read_only=self._read_only,
-            dbt_project_path=self._dbt_project_path,
             connection_string=self._connection_string,
             profile_type=self._dialect,
             target=self._target,
@@ -279,11 +266,6 @@ class ProjectSession:
 
     # ── Verb forwarders ──────────────────────────────────────────────────────
 
-    def validate(self, face_path: Path) -> ValidateResult:
-        result = _validate.validate(face_path, project=self.project)
-        annotated = _validate.annotate_with_data_lint([result], project_session=self)
-        return annotated[0]
-
     def validate_paths(self, paths: list[Path] | None) -> list[ValidateResult]:
         results = _validate.validate_paths(paths, project=self.project)
         return _validate.annotate_with_data_lint(results, project_session=self)
@@ -346,32 +328,9 @@ class ProjectSession:
             relationship_context=self._relationship_context,
         )
 
-    def describe_face(self, path: Path) -> _describe.DescribeFaceResult:
-        return _describe.describe_face(path, project=self.project)
-
     def describe_paths(self, paths: list[Path]) -> list[_describe.DescribeFaceResult]:
         return _describe.describe_paths(paths, project=self.project)
 
-    def list_dashboards(
-        self,
-        directory: Path | None = None,
-        recursive: bool = True,
-    ) -> _dashboards.ListDashboardsResult:
-        """When ``directory`` is None, defaults to ``self.project.root``. When provided, callers are responsible for passing an absolute path; relative paths resolve against the process working directory."""
-        return _dashboards.list_dashboards(
-            directory=directory if directory is not None else self.project.root,
-            recursive=recursive,
-        )
-
-    def get_dashboard(
-        self,
-        path: Path,
-        include_raw: bool = False,
-    ) -> _dashboards.CompiledDashboard:
-        return _dashboards.get_dashboard(
-            path, include_raw=include_raw, project=self.project
-        )
-
     def lookup_face_query_sql(
         self,
         name: str,
@@ -401,6 +360,7 @@ class ProjectSession:
         variables: dict[str, Any] | None = None,
         source: str | None = None,
         limit: int = 50,
+        lenient_variables: bool = False,
     ) -> _query.ExecuteQueryResult:
         return _query.execute_query(
             sql,
@@ -408,6 +368,7 @@ class ProjectSession:
             source=source,
             limit=limit,
             adapter_registry=self.adapter_registry,
+            lenient_variables=lenient_variables,
         )
 
     def describe_query(

dataface/agent_api/query.py

@@ -88,6 +88,10 @@ class ExecuteQueryArgs(BaseModel):
     )
     source: str | None = Field(None, description="Data source name to execute against")
     limit: int | None = Field(None, description="Maximum rows to return (default 50)")
+    lenient_variables: bool = Field(
+        False,
+        description="When True, undefined Jinja variables degrade gracefully (useful for iterative chart editing where not all variables are set).",
+    )
 
 
 class ExecuteQueryResult(BaseModel):
@@ -135,6 +139,7 @@ def execute_query(
     limit: int = 50,
     *,
     adapter_registry: AdapterRegistry,
+    lenient_variables: bool = False,
 ) -> ExecuteQueryResult:
     """Execute a SQL query and return the results.
 
@@ -155,6 +160,7 @@ def execute_query(
             sql=sql,
             source=source,
             limit=fetch_limit,
+            lenient_variables=lenient_variables,
         )
 
         result = adapter_registry.execute(query, variables=variables)

dataface/agent_api/render_face.py

@@ -15,10 +15,6 @@ from dataface.core.compile.markdown import (
 )
 from dataface.core.execute.duckdb_cache import DuckDBCache
 from dataface.core.project import Project
-from dataface.core.project_roots import (
-    discover_render_context,
-    discovery_boundary_for_face,
-)
 from dataface.core.render.face_api import compile_and_render
 
 
@@ -72,16 +68,7 @@ def render_face(
     if project is not None:
         if warnings_ignore is None:
             warnings_ignore = project.warnings_ignore
-        # Discover dbt_project.yml between the face and the project root.
-        # build_adapter_registry's own fallback would only walk upward from
-        # project.root, missing nested dbt projects under it.
-        _, dbt_project_path = discover_render_context(
-            face_file.parent,
-            discovery_boundary_for_face(face_file.parent, project.root),
-        )
-        project_session = ProjectSession.open(
-            project.root, cache=cache, dbt_project_path=dbt_project_path
-        )
+        project_session = ProjectSession.open(project.root, cache=cache)
     else:
         if warnings_ignore is None:
             warnings_ignore = frozenset()

dataface/ai/context.py

@@ -21,6 +21,7 @@ class DatafaceAIContext:
     # `dft chat` after binding; consumed by `_view_url` to build clickable
     # localhost URLs in `render_dashboard` responses (including as_link=True).
     server_port: int | None = None
+    prompt_context: dict[str, str] | None = None
 
     def resolve_dashboard_path(self, path: Path) -> Path:
         """Resolve a dashboard path inside the scoped dashboards directory.

dataface/ai/mcp/server.py

@@ -180,14 +180,14 @@ def create_server(context: DatafaceAIContext) -> Any:
         return TypeAdapter(AnyUrl).validate_python(value)
 
     @server.list_resources()  # type: ignore[no-untyped-call]
-    async def handle_list_resources() -> list[Resource]:
+    async def handle_list_resources() -> list[Resource]:  # pyright: ignore[reportUnusedFunction]  # decorator-registered — pyright cannot model runtime registration  # fmt: skip
         return [
             Resource(uri=_uri(u), mimeType=m, name=n, description=d)
             for u, m, n, d in (*_BASE_RESOURCES, *_docs_topic_resources())
         ]
 
     @server.list_resource_templates()  # type: ignore[no-untyped-call]
-    async def handle_list_resource_templates() -> list[ResourceTemplate]:
+    async def handle_list_resource_templates() -> list[ResourceTemplate]:  # pyright: ignore[reportUnusedFunction]  # decorator-registered — pyright cannot model runtime registration  # fmt: skip
         return [
             ResourceTemplate(
                 uriTemplate="dataface://dashboard/{path}",
@@ -204,11 +204,11 @@ def create_server(context: DatafaceAIContext) -> Any:
         ]
 
     @server.read_resource()  # type: ignore[no-untyped-call]
-    async def handle_read_resource(uri: AnyUrl) -> str:
+    async def handle_read_resource(uri: AnyUrl) -> str:  # pyright: ignore[reportUnusedFunction]  # decorator-registered — pyright cannot model runtime registration  # fmt: skip
         return _read_resource_content(str(uri), context=context)
 
     @server.list_tools()  # type: ignore[no-untyped-call]
-    async def handle_list_tools() -> list[Tool]:
+    async def handle_list_tools() -> list[Tool]:  # pyright: ignore[reportUnusedFunction]  # decorator-registered — pyright cannot model runtime registration  # fmt: skip
         return [
             Tool(
                 name=cast(str, t["name"]),
@@ -234,7 +234,7 @@ def create_server(context: DatafaceAIContext) -> Any:
         ]
 
     @server.call_tool()
-    async def handle_call_tool(
+    async def handle_call_tool(  # pyright: ignore[reportUnusedFunction]  # decorator-registered — pyright cannot model runtime registration
         name: str, arguments: dict[str, Any] | None
     ) -> CallToolResult:
         arguments = arguments or {}

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

@@ -19,6 +19,13 @@ metadata:
 
 **`{{ s_render_dashboard }}` is how you deliver a dashboard** — call it and return its output. Do not skip it.
 
+## Delivery discipline
+
+- `{{ s_render_dashboard }}` delivers the dashboard — call it and let the result stand. Do not also paste the rendered output or the full YAML back as prose; that just duplicates the deliverable as an unreadable dump.
+- Act, don't ask. Apply edits and render directly — do not ask for permission or offer optional follow-ups ("if you want, I can save this", "would you like me to…").
+- Fail loud. If a tool returns an error, report it and either fix the input and call the tool again, or stop and say what's blocking. Never route around a failed tool by fabricating output, dumping query rows as a text table in place of a chart, or improvising a different format. A failed render is a failure to report, not to paper over.
+- Never claim a render, query, or save succeeded unless the tool returned success. Never invent columns, tables, or data — if a schema or query call fails, fix it against the real schema.
+
 Build dashboards and reports **incrementally** — one chart at a time, validating at every step. Never one-shot an entire dashboard.
 
 ## Companion Skills

dataface/cli/commands/_agent_input.py

@@ -140,11 +140,11 @@ class PromptToolkitInput:
         kb = KeyBindings()
 
         @kb.add("enter")
-        def _submit(event: Any) -> None:
+        def _submit(event: Any) -> None:  # pyright: ignore[reportUnusedFunction]  # decorator-registered — pyright cannot model runtime registration  # fmt: skip
             event.current_buffer.validate_and_handle()
 
         @kb.add("escape", "enter")
-        def _newline_meta(event: Any) -> None:
+        def _newline_meta(event: Any) -> None:  # pyright: ignore[reportUnusedFunction]  # decorator-registered — pyright cannot model runtime registration  # fmt: skip
             event.current_buffer.insert_text("\n")
 
         self._session: PromptSession = PromptSession(
@@ -205,7 +205,7 @@ def select_input_layer(
         return StdlibInput(hist_path)
 
     try:
-        import prompt_toolkit  # noqa: PLC0415, F401
+        import prompt_toolkit  # noqa: PLC0415, F401  # pyright: ignore[reportUnusedImport] — availability probe; ImportError selects StdlibInput
     except ImportError:
         return StdlibInput(hist_path)
 

dataface/cli/commands/render.py

@@ -129,11 +129,7 @@ def render_command(
 
     with (
         cache_from_env() as cache,
-        ProjectSession.open(
-            ctx.project_root,
-            cache=cache,
-            dbt_project_path=ctx.dbt_project_path,
-        ) as project_session,
+        ProjectSession.open(ctx.project_root, cache=cache) as project_session,
     ):
         result = project_session.render_dashboard(
             path=ctx.scoped_path,
@@ -219,11 +215,7 @@ def render_command_from_yaml(
 
     with (
         cache_from_env() as cache,
-        ProjectSession.open(
-            ctx.project_root,
-            cache=cache,
-            dbt_project_path=ctx.dbt_project_path,
-        ) as project_session,
+        ProjectSession.open(ctx.project_root, cache=cache) as project_session,
     ):
         result = project_session.render_dashboard(
             yaml_content=yaml_content,

dataface/core/compile/__init__.py

@@ -120,7 +120,6 @@ from dataface.core.compile.models.source import (
     is_database_source,
     is_file_source,
     parse_source_config,
-    resolve_env_var,
 )
 from dataface.core.compile.models.variable.authored import (
     Variable,
@@ -201,7 +200,6 @@ __all__ = [
     "is_database_source",
     "is_file_source",
     "is_api_source",
-    "resolve_env_var",
     # Config
     "ProjectSourcesConfig",
     "get_config",

dataface/core/compile/channel.py

@@ -52,11 +52,6 @@ def parse_style_channel(
     if isinstance(raw, str):
         return ResolvedStyleChannel(channel=channel_name, mode="series", data_field=raw)
 
-    if not isinstance(raw, dict):
-        raise ValueError(
-            f"Channel '{channel_name}' must be a string or dict, got {type(raw).__name__}"
-        )
-
     has_column = "column" in raw
     has_value = "value" in raw
     has_scale = "scale" in raw
@@ -188,7 +183,7 @@ def normalize_chart_channels(
         channels["color"] = parse_style_channel(color_raw, "color")
 
     # Upgrade series channel to gradient when style.color carries a scale.
-    if isinstance(style_color, StyleColorConfig) and style_color.scale is not None:
+    if isinstance(style_color, StyleColorConfig):
         if "color" not in channels:
             raise ValueError(
                 "style.color: {scale: ...} requires chart.color to name a data field.\n"

dataface/core/compile/colors.py

@@ -43,7 +43,7 @@ def sanitize_color(color: str | None, fallback: str | None = None) -> str | None
     immediately — authored colors that are not valid are a configuration error,
     not a case for silent defaulting.
     """
-    if not color or not isinstance(color, str):
+    if not color:
         return fallback
     if _CSS_HEX_COLOR_PATTERN.match(color):
         return color

dataface/core/compile/compiler.py

@@ -271,9 +271,7 @@ def compile(
         yaml_content: YAML string to compile
         options: Optional compilation options
         base_dir: Base directory for resolving file references
-        project_sources: Project-level sources, ready to use. Callers that
-            hold a ``ProjectSession`` thread ``project_session.sources``;
-            one-shot callers pre-load via ``load_project_sources(Project(project_dir))``.
+        project_sources: Project-level sources.
 
     Returns:
         CompileResult with compiled face or errors
@@ -440,6 +438,7 @@ def compile_file(
     apply_meta: bool = True,
     *,
     project: Project,
+    markdown_metadata_table: bool = False,
 ) -> CompileResult:
     """Compile a YAML file to a Face.
 
@@ -451,6 +450,8 @@ def compile_file(
         options: Optional compilation options
         apply_meta: If True, resolve and apply meta.yaml chain (default: True)
         project: Project for meta resolution and source loading
+        markdown_metadata_table: When True and file_path is a .md, prepend
+            non-face frontmatter keys as a metadata table before the body.
 
     Returns:
         CompileResult with compiled face or errors
@@ -471,13 +472,14 @@ def compile_file(
         )
 
     # Markdown report files: translate to YAML before compiling
-    if file_path.suffix.lower() == ".md":
-        from dataface.core.compile.markdown import (
-            MARKDOWN_NOT_FACE_MESSAGE,
-            is_markdown_face,
-            markdown_to_yaml,
-        )
+    from dataface.core.compile.markdown import (
+        MARKDOWN_NOT_FACE_MESSAGE,
+        MARKDOWN_SUFFIXES,
+        is_markdown_face,
+        markdown_to_yaml,
+    )
 
+    if file_path.suffix.lower() in MARKDOWN_SUFFIXES:
         if not is_markdown_face(file_path):
             return CompileResult(
                 errors=[CompilationError(MARKDOWN_NOT_FACE_MESSAGE).to_structured()]
@@ -485,7 +487,9 @@ def compile_file(
 
         try:
             raw_text = file_path.read_text(encoding="utf-8")
-            yaml_content = markdown_to_yaml(raw_text)
+            yaml_content = markdown_to_yaml(
+                raw_text, metadata_table=markdown_metadata_table
+            )
         except (OSError, ValueError) as e:
             return CompileResult(
                 errors=[CompilationError(f"Markdown parse error: {e}").to_structured()]
@@ -820,10 +824,8 @@ def load_from_reference(
         section_name = "variables"
     elif isinstance(reference, QueryRef):
         section_name = "queries"
-    elif isinstance(reference, ChartRef):
-        section_name = "charts"
     else:
-        raise CompilationError(f"Unexpected reference type: {type(reference)!r}")
+        section_name = "charts"
 
     # Grammar already validated by the typed model; split is deterministic.
     file_path_str, item_name = reference.ref.rsplit(f".{section_name}.", 1)