dataface 0.4.1.dev134__py3-none-any.whl → 0.4.1.dev224__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -928,6 +928,8 @@ variables:
 
 Top-level option-source binding (alternative to `options:`): `column`, `query`, `dimension` (MetricFlow), `measure` (MetricFlow), `model` (dbt).
 
+Top-level `column` is `table.column`, and the table may be schema-qualified when it is not in the connection's default schema — `column: gis.fact_sales.property_type`. `filter()` accepts the same qualified form.
+
 Enabled/disabled forms (`enabled: false` means the control is inactive):
 
 ```yaml

dataface/agent_api/_init_templates/meta.yaml

@@ -6,8 +6,8 @@
 # directory and its subdirectories; each face overrides what it sets.
 #
 # A meta.yaml deeper in the tree layers on top of the ones above it, and a face
-# always wins over meta. Nested style keys merge (a face setting style.board.margin
-# keeps a meta-supplied style.board.width).
+# always wins over meta. Nested style keys merge (a face setting style.frame.margin
+# keeps a meta-supplied style.frame.width).
 #
 # Uncomment and edit to set project-wide defaults:
 #
@@ -15,5 +15,5 @@
 # source: my_warehouse    # default data source for faces that don't name one
 #
 # style:
-#   board:
+#   frame:
 #     width: 1000

dataface/agent_api/dashboards.py

@@ -7,13 +7,20 @@ values. No bare dict[str, Any] in any return position. Tool/CLI callers use
 
 from __future__ import annotations
 
+import sys
 from pathlib import Path
-from typing import Any, Literal
+from typing import Literal
 
 import yaml
-from pydantic import BaseModel, ConfigDict, Field, field_serializer
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, model_validator
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
 
 from dataface.agent_api._paths import resolve_face_or_error
+from dataface.agent_api.query import VariableBinding, variables_to_dict as _vars_to_dict
 from dataface.core.compile import Face, compile_file
 from dataface.core.dashboard import RenderedDashboard as RenderedDashboard
 from dataface.core.diagnostics import Diagnostic
@@ -112,8 +119,12 @@ class RenderDashboardArgs(BaseModel):
             "the list of available chart ids."
         ),
     )
-    variables: dict[str, Any] | None = Field(
-        None, description="Variable values to apply to the dashboard"
+    variables: list[VariableBinding] | None = Field(
+        None,
+        description=(
+            "Variable values to apply to the dashboard, as an array of {name, value} pairs. "
+            'Example: [{"name": "region", "value": "US"}, {"name": "year", "value": 2024}]'
+        ),
     )
     format: Literal["json", "text", "yaml", "svg", "terminal", "data"] | None = Field(
         None,
@@ -148,6 +159,12 @@ class RenderDashboardArgs(BaseModel):
         ),
     )
 
+    @model_validator(mode="after")
+    def _no_duplicate_variable_names(self) -> Self:
+        if self.variables is not None:
+            _vars_to_dict(self.variables)
+        return self
+
 
 # ---------------------------------------------------------------------------
 # Public verbs

dataface/agent_api/docs/yaml-reference.md

@@ -26,7 +26,7 @@ AuthoredFace (dataface) definition from YAML.
 | `details` | [FaceDetails](#facedetails) | ✓ | Collapsible section metadata. String shorthand: details: 'text' → FaceDetails(summary='text'). Block form: details: {summary: ..., expanded_title: ..., expanded: false}. |
 | `id` | str | ✓ | Explicit ID for this face. Auto-generated from filename if omitted. |
 | `style` | [Style](#style) | ✓ | Style patch (background, padding, border, etc.). Background and semantic color tokens (accent, muted) cascade to nested child faces. |
-| `width` | str \| int | ✓ | Width when nested (e.g., '50%', '400px', or an integer in pixels). On the root face there is no parent to place it into, so it instead sets the board's own width (equivalent to 'style.board.width') — percentages are rejected there since there's nothing to size relative to. |
+| `width` | str \| int | ✓ | Width when nested (e.g., '50%', '400px', or an integer in pixels). On the root face there is no parent to place it into, so it instead sets the board's own width (equivalent to 'style.frame.width') — percentages are rejected there since there's nothing to size relative to. |
 | `height` | str \| int | ✓ | Height when nested (e.g., '300px' or an integer in pixels). |
 | `visible` | bool \| str \| [SingleRowBoolProbe](#singlerowboolprobe) | ✓ | Controls whether this layout item is rendered. Accepts a bool, variable name, Jinja expression, or {query, column} probe. |
 | `extends` | str \| list[str] | ✓ | Face name(s) or relative path(s) this face inherits from, low to high priority. |
@@ -54,7 +54,7 @@ Variable definition from YAML.
 | `required` | bool | ✓ | When True, a value must be provided before queries execute. |
 | `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. |
+| `column` | str | ✓ | Table column to draw option values from, as 'table.column'. The table may be schema-qualified ('schema.table.column') when it is not in the connection's default schema. |
 | `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. |
@@ -496,7 +496,7 @@ Authored overlay for Style — all fields optional. Adds CSS shorthand coercers.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `board` | [BoardStyle](#boardstyle) | ✓ | Face-level structural board dimensions. |
+| `frame` | [FrameStyle](#framestyle) | ✓ | Face-level structural frame dimensions. |
 | `background` | str | ✓ | Working-surface background color (board and card fills). |
 | `accent` | str | ✓ | Accent color token cascaded to sparklines, bars, and focus rings. |
 | `muted` | str | ✓ | Muted secondary-text color token (KPI support rows, table and spark subtitles). |
@@ -1023,13 +1023,13 @@ Tab layout item.
 | `grid` | [GridLayout](#gridlayout) | ✓ | CSS-grid layout for this tab's content. |
 | `tabs` | [TabLayout](#tablayout) | ✓ | Nested tab layout (tabs within tabs). |
 
-<a id="boardstyle"></a>
-## BoardStyle
-Authored overlay for BoardStyle. Face-level structural dimensions. Do NOT cascade to child faces.
+<a id="framestyle"></a>
+## FrameStyle
+Authored overlay for FrameStyle. Face-level structural dimensions. Do NOT cascade to child faces.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `width` | float | ✓ | Maximum dashboard width in pixels. Caps the measured layout width, setting the board's proportions. Rendered as an on-screen pixel maximum everywhere except the dft HTML page (dft serve, dft render --format html), which scales the board to its container. |
+| `width` | float | ✓ | Maximum board width in pixels. Caps the measured layout width, setting the board's proportions. Rendered as an on-screen pixel maximum everywhere except the dft HTML page (dft serve, dft render --format html), which scales the board to its container. |
 | `min_height` | float | ✓ | Minimum board height in pixels. |
 | `margin` | float | ✓ | Board outer margin in pixels. |
 | `card_padding` | float | ✓ | Padding added to each card side in pixels. |
@@ -1689,7 +1689,7 @@ Authored overlay for TableTitleStyle.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `height` | float | ✓ | Table title row height in pixels. |
+| `height` | float | ✓ | Minimum title-block height in pixels. Applies as a floor only when a subtitle is present; a title-only block sizes to its natural content height instead. |
 | `font` | [FontStyle](#fontstyle) | ✓ | Table title font style overrides. Unset fields fall back to [`style.charts.table.font`](#tablechartstyle). |
 
 <a id="paginationconfig"></a>

dataface/agent_api/pack.py

@@ -274,7 +274,7 @@ def _build_face_dict(dashboard: ProposedDashboard) -> dict[str, Any]:
         "title": dashboard.title,
         "description": dashboard.purpose,
         "text": (
-            f"Dashboard for {dashboard.primary_entity}. " "Add queries and charts here."
+            f"Dashboard for {dashboard.primary_entity}. Add queries and charts here."
         ),
     }
     if dashboard.canonical_data_url:

dataface/agent_api/query.py

@@ -1,9 +1,15 @@
 """Typed query verbs for the agent API."""
 
+import sys
 from pathlib import Path, PurePosixPath
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
 
 from dataface.agent_api._paths import resolve_face_path
 from dataface.core.compile import compile_file
@@ -16,6 +22,34 @@ from dataface.core.validate import normalize_data_for_json
 MAX_QUERY_LIMIT = 1000
 
 
+class VariableBinding(BaseModel):
+    """One variable binding in a tool call: a name–value pair.
+
+    Used in the ``variables`` / ``vars`` fields of ``render_dashboard``,
+    ``execute_query``, and ``query_face`` instead of an open-keyed dict, so
+    that OpenAI strict mode can validate the full tool-call structure.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str = Field(..., description="Variable name, e.g. 'region'")
+    value: str | int | float | bool = Field(
+        ..., description="Scalar value for the variable"
+    )
+
+
+def variables_to_dict(
+    bindings: list[VariableBinding],
+) -> dict[str, str | int | float | bool]:
+    """Convert a VariableBinding list to a dict, raising on duplicate names."""
+    result: dict[str, str | int | float | bool] = {}
+    for binding in bindings:
+        if binding.name in result:
+            raise ValueError(f"Duplicate variable name: {binding.name!r}")
+        result[binding.name] = binding.value
+    return result
+
+
 class FaceQueryLookupResult(BaseModel):
     """Result of extracting SQL from a named face query for offline use (validate/describe)."""
 
@@ -100,8 +134,12 @@ class ExecuteQueryArgs(BaseModel):
         ...,
         description="SQL query to execute. Use {{ variable_name }} for parameterized values — these work identically in dashboard YAML, so queries you test here will be cached when reused in dashboards.",
     )
-    variables: dict[str, Any] | None = Field(
-        None, description='Variable values to substitute (e.g. {"region": "US"})'
+    variables: list[VariableBinding] | None = Field(
+        None,
+        description=(
+            "Variable values to substitute, as an array of {name, value} pairs. "
+            'Example: [{"name": "region", "value": "US"}, {"name": "year", "value": 2024}]'
+        ),
     )
     source: str | None = Field(None, description="Data source name to execute against")
     limit: int | None = Field(None, description="Maximum rows to return (default 50)")
@@ -118,6 +156,12 @@ class ExecuteQueryArgs(BaseModel):
         description="Short phrase naming what this query is for (e.g. 'Leads by industry'), shown to the user in place of the raw SQL.",
     )
 
+    @model_validator(mode="after")
+    def _no_duplicate_variable_names(self) -> Self:
+        if self.variables is not None:
+            variables_to_dict(self.variables)
+        return self
+
 
 class ExecuteQueryResult(BaseModel):
     model_config = ConfigDict(frozen=True)
@@ -242,8 +286,12 @@ class QueryFaceArgs(BaseModel):
         ..., description="Name of the query inside the face's `queries:` block"
     )
     path: Path = Field(..., description="Path to the face YAML file")
-    vars: dict[str, Any] | None = Field(
-        None, description='Variable overrides (e.g. {"country": "FR"})'
+    vars: list[VariableBinding] | None = Field(
+        None,
+        description=(
+            "Variable overrides as an array of {name, value} pairs. "
+            'Example: [{"name": "country", "value": "FR"}]'
+        ),
     )
     limit: int = Field(
         20, ge=1, le=1000, description="Max rows to return (default 20, max 1000)"
@@ -251,6 +299,12 @@ class QueryFaceArgs(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
+    @model_validator(mode="after")
+    def _no_duplicate_variable_names(self) -> Self:
+        if self.vars is not None:
+            variables_to_dict(self.vars)
+        return self
+
 
 class QueryFaceResult(BaseModel):
     model_config = ConfigDict(frozen=True)

dataface/agent_api/serve.py

@@ -58,9 +58,7 @@ def prepare_serve(
     from dataface.core.serve.port import resolve_port
     from dataface.core.serve.server import create_server
 
-    env_theme = os.environ.get(
-        "DFT_DEFAULT_THEME"
-    )  # noqa: TID251 — DFT_DEFAULT_THEME knob
+    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:

dataface/ai/llm.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import copy
 import json
 import logging
 import os
@@ -93,24 +94,69 @@ def _resolve_model(
     return explicit_model or os.getenv(env_var) or default_model
 
 
+def _to_strict_json_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Transform a JSON Schema dict in-place to conform to OpenAI strict-mode rules.
+
+    Mirrors openai/lib/_pydantic.py::_ensure_strict_json_schema:
+    - Every object gets additionalProperties: false.
+    - required covers all property keys whenever properties is present.
+    - 'default: null' entries are stripped (non-null defaults are left intact).
+    Recurses into $defs, definitions, properties, items, anyOf, allOf, oneOf.
+    """
+    if schema.get("type") == "object":
+        schema.setdefault("additionalProperties", False)
+    props = schema.get("properties", {})
+    if props:
+        schema["required"] = list(props.keys())
+
+    if schema.get("default") is None and "default" in schema:
+        del schema["default"]
+
+    for defs_key in ("$defs", "definitions"):
+        for sub in schema.get(defs_key, {}).values():
+            _to_strict_json_schema(sub)
+
+    for sub in schema.get("properties", {}).values():
+        _to_strict_json_schema(sub)
+
+    for key in ("anyOf", "allOf", "oneOf"):
+        for sub in schema.get(key, []):
+            _to_strict_json_schema(sub)
+
+    if "items" in schema:
+        _to_strict_json_schema(schema["items"])
+
+    return schema
+
+
 def _normalize_openai_tools(
     tools: list[dict[str, Any]] | None,
 ) -> list[dict[str, Any]]:
     # None means "use default agent tools"; [] means "no tools, text-only completion".
     source_tools = ALL_TOOLS if tools is None else tools
-    if not source_tools:
-        return []
-    if "input_schema" in source_tools[0]:
-        return [
-            {
-                "type": "function",
-                "name": tool["name"],
-                "description": tool["description"],
-                "parameters": tool["input_schema"],
-            }
-            for tool in source_tools
-        ]
-    return source_tools
+    result: list[dict[str, Any]] = []
+    for tool in source_tools:
+        if "input_schema" in tool:
+            # First-party tool in MCP/input_schema format — strict-transform and
+            # convert to OpenAI Responses API format. Strict mode is a property of
+            # schemas we authored, not of the transport; MCP passthrough schemas
+            # (already in OpenAI function format) are appended below unchanged.
+            result.append(
+                {
+                    "type": "function",
+                    "strict": True,
+                    "name": tool["name"],
+                    "description": tool["description"],
+                    "parameters": _to_strict_json_schema(
+                        copy.deepcopy(tool["input_schema"])
+                    ),
+                }
+            )
+        else:
+            # Already in OpenAI function format (e.g. MCP passthrough) — pass through
+            # untouched. Caller-supplied schemas must not be strict-marked or rewritten.
+            result.append(tool)
+    return result
 
 
 class LLMClientError(RuntimeError):

dataface/ai/tools/__init__.py

@@ -18,7 +18,10 @@ from dataface.agent_api import (
     skills as _skills,
 )
 from dataface.agent_api._paths import resolve_face_or_error
-from dataface.agent_api.query import ExecuteQueryArgs as _ExecuteQueryArgs
+from dataface.agent_api.query import (
+    ExecuteQueryArgs as _ExecuteQueryArgs,
+    variables_to_dict as _vars_to_dict,
+)
 from dataface.agent_api.validate import (
     ValidateDashboardArgs as _ValidateDashboardArgs,
     validate_dashboard as _validate_dashboard_func,
@@ -105,7 +108,9 @@ def _handle_render(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, An
     return ctx.project_session.render_dashboard(
         face=face,
         chart=parsed.chart,
-        variables=parsed.variables,
+        variables=(
+            _vars_to_dict(parsed.variables) if parsed.variables is not None else None
+        ),
         format=parsed.format or "json",
         as_link=parsed.as_link,
         server_port=ctx.server_port,
@@ -117,7 +122,9 @@ def _handle_query(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any
     parsed = _ExecuteQueryArgs.model_validate(args)
     return _query.execute_query(
         sql=parsed.sql,
-        variables=parsed.variables,
+        variables=(
+            _vars_to_dict(parsed.variables) if parsed.variables is not None else None
+        ),
         source=parsed.source or ctx.default_source,
         limit=parsed.limit or 50,
         adapter_registry=ctx.project_session.adapter_registry,
@@ -141,7 +148,7 @@ def _handle_query_face(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str
         name=parsed.name,
         path=parsed.path,
         project=ctx.project_session.project,
-        vars=parsed.vars,
+        vars=_vars_to_dict(parsed.vars) if parsed.vars is not None else None,
         limit=parsed.limit,
         adapter_registry=ctx.project_session.adapter_registry,
     ).model_dump(mode="json", exclude_none=True)

dataface/cli/commands/board_artifact.py

@@ -1,4 +1,4 @@
-"""board emit / board render commands — thin wrappers over dataface.agent_api.board_artifact."""
+"""artifact emit / artifact render commands — thin wrappers over dataface.agent_api.board_artifact."""
 
 from __future__ import annotations
 

dataface/cli/commands/extension.py

@@ -70,6 +70,7 @@ def install_extension(editor: str, emit: Callable[[str], None] = print) -> int:
                 [binary, "--install-extension", str(vsix_path)],
                 capture_output=True,
                 text=True,
+                encoding="utf-8",
                 timeout=60,
             )
         except subprocess.TimeoutExpired:

dataface/cli/commands/serve.py

@@ -32,14 +32,11 @@ def serve_command(
     """Start unified Dataface server.
 
     This command starts a FastAPI server that serves:
-    - Profile templates at /profile/{template}/?model=X&column=Y
     - Any face file at /{path}/?var=value (path.yml → /path/)
     - Health check at /health
 
     Example URLs:
-        http://localhost:9876/health
-        http://localhost:9876/profile/model/?model=fct_orders&theme=dark
-        http://localhost:9876/profile/numeric_column/?model=fct_orders&column=revenue
+        http://localhost:9876/
         http://localhost:9876/sales/?region=West
 
     Args:
@@ -94,17 +91,11 @@ def serve_command(
     port = setup.port
     app = setup.app
 
-    # Start server
-    typer.echo("🚀 Starting dashboard server")
+    # Start server. The URL is the whole banner: it lists every face in the
+    # project, so any other route printed here is a second way to say the same
+    # thing — or, once a route is renamed, a link that 404s.
+    typer.echo("📈 Starting dashboard server")
     typer.echo(f"   URL: http://{host}:{port}")
-    typer.echo(f"   Health: http://{host}:{port}/health")
-    typer.echo("")
-    typer.echo("   Routes:")
-    typer.echo(f"     http://{host}:{port}/profile/model/?model=<table>")
-    typer.echo(
-        f"     http://{host}:{port}/profile/numeric_column/?model=<table>&column=<col>"
-    )
-    typer.echo(f"     http://{host}:{port}/<name>/?var=value")
     typer.echo("")
     typer.echo("   Press CTRL+C to stop")
 

dataface/cli/commands/skills_init.py

@@ -122,8 +122,7 @@ def run_init_skills(
                 typer.echo(f"    ✓ {name}")
         elif result.skipped_existing:
             typer.echo(
-                f"  Workflow skills unchanged ({len(result.skipped_existing)})"
-                f" → {rel}/"
+                f"  Workflow skills unchanged ({len(result.skipped_existing)}) → {rel}/"
             )
         if result.retired_removed:
             typer.echo(f"  Removed retired: {', '.join(result.retired_removed)}")

dataface/cli/main.py

@@ -1,6 +1,7 @@
 """Main CLI entry point."""
 
 import importlib.util
+import io
 import logging
 import sys
 from pathlib import Path
@@ -71,9 +72,9 @@ inspect_app = typer.Typer(
     rich_markup_mode=_RICH_MARKUP_MODE,
 )
 
-# Board subcommand app — `dft board emit` / `dft board render`
-board_app = typer.Typer(
-    name="board",
+# Artifact subcommand app — `dft artifact emit` / `dft artifact render`
+artifact_app = typer.Typer(
+    name="artifact",
     help="Emit a resolved-board artifact + recording, and render one back.",
     no_args_is_help=True,
     pretty_exceptions_show_locals=False,
@@ -632,7 +633,7 @@ def mcp_serve(
 # --- Dashboards -------------------------------------------------------------
 
 
-app.add_typer(board_app, name="board", rich_help_panel="Dashboards")
+app.add_typer(artifact_app, name="artifact", rich_help_panel="Dashboards")
 
 
 @app.command("describe", rich_help_panel="Dashboards")
@@ -920,7 +921,7 @@ def render(
     )
 
 
-@board_app.command("emit")
+@artifact_app.command("emit")
 def emit_board(
     face: Annotated[
         Path,
@@ -965,14 +966,14 @@ def emit_board(
 
     The artifact is the resolved board's published, data-free contract; the
     recording is a separate sidecar carrying the rows it was resolved
-    against. Render the pair back with `dft board render` — no compile step,
+    against. Render the pair back with `dft artifact render` — no compile step,
     no warehouse connection.
 
     \b
     Examples:
-      dft board emit faces/sales.yml
-      dft board emit faces/sales.yml --artifact out/sales.board.json --recording out/sales.recording.json
-      dft board emit faces/sales.yml --var region=West
+      dft artifact emit faces/sales.yml
+      dft artifact emit faces/sales.yml --artifact out/sales.board.json --recording out/sales.recording.json
+      dft artifact emit faces/sales.yml --var region=West
     """
     board_artifact_cmd.emit_board_command(
         face,
@@ -985,7 +986,7 @@ def emit_board(
     )
 
 
-@board_app.command("render")
+@artifact_app.command("render")
 def render_board(
     artifact: Annotated[Path, typer.Argument(help="Path to a board artifact file.")],
     recording: Annotated[
@@ -1001,14 +1002,14 @@ def render_board(
 ) -> None:
     """Render a board from its artifact + recording — no compile, no warehouse.
 
-    Both files come from `dft board emit`. A recording missing a query, or
+    Both files come from `dft artifact emit`. A recording missing a query, or
     captured under different variable values than the artifact expects,
     fails loudly rather than rendering an empty or wrong chart.
 
     \b
     Examples:
-      dft board render out/sales.board.json out/sales.recording.json
-      dft board render out/sales.board.json out/sales.recording.json --output sales.svg
+      dft artifact render out/sales.board.json out/sales.recording.json
+      dft artifact render out/sales.board.json out/sales.recording.json --output sales.svg
     """
     board_artifact_cmd.render_board_command(
         artifact,
@@ -1464,6 +1465,20 @@ for _ep in _entry_points(group="dataface.cli_plugins"):
     _plugin()
 
 
+def _reconfigure_console_encoding() -> None:
+    """Force UTF-8 on stdout/stderr so non-ASCII diagnostics never crash.
+
+    Windows consoles default to the legacy cp1252 codepage; printing
+    non-ASCII text (e.g. an arrow in an error message) would otherwise raise
+    UnicodeEncodeError while reporting the original error. No-op on
+    Linux/macOS, where the streams are already UTF-8. Streams without
+    reconfigure() — e.g. one swapped in under test capture — are left alone.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.TextIOWrapper):
+            stream.reconfigure(encoding="utf-8")
+
+
 def version_callback(value: bool) -> None:
     """Print version and exit."""
     if value:
@@ -1486,6 +1501,7 @@ def main(
     ] = None,
 ) -> None:
     """dft - Declarative, dbt-native dashboards in YAML."""
+    _reconfigure_console_encoding()
     # Runs before any subcommand, so every warehouse query this process sends is
     # attributed to the CLI. `dft serve` narrows it to "serve" in its own command.
     set_surface("cli")