dataface 0.1.4.dev6__py3-none-any.whl → 0.1.5.dev48__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -1113,17 +1113,30 @@ Active code categories (see `dataface/core/errors/codes_*.py` for the authoritat
 
 | Prefix | Meaning |
 |--------|---------|
+| `DF-COMPILE-*` | Compile-time errors (missing fields, unknown references, malformed YAML) |
 | `DF-RENDER-*` | Chart rendering errors (wrong row counts, unknown chart types, format issues) |
 | `DF-EXECUTE-*` | Query execution errors (missing sources, inline-source policy, source typing) |
 | `DF-UNKNOWN-*` | Fallback codes for legacy string-message errors not yet migrated |
 
-The registry is being filled out incrementally — many compile-time and variable-resolution errors still raise as plain `DatafaceError` without a structured code. Today's typed codes:
+The registry is being filled out incrementally — some compile-time and variable-resolution errors still raise as plain `DatafaceError` without a structured code. Today's typed codes:
+
+### Compile errors
+
+- **`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-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
 
 - **`DF-RENDER-KPI-MULTIROW`** — a KPI chart's query returned more than one row but `value` is a column reference. Add `LIMIT 1` or aggregate down to one row.
 - **`DF-RENDER-UNKNOWN-CHART-TYPE`** — `type:` is not a recognized chart type. See the [Charts](#charts) section for the list.
 - **`DF-RENDER-FORMAT-UNSUPPORTED`** — the render `format` argument is not one of `svg`/`html`/`png`.
 - **`DF-RENDER-NO-LAYOUT`** — the face has no `rows`/`cols`/`grid`/`tabs` and nothing to render.
 - **`DF-RENDER-INPUT-INVALID`** — the render call received structurally invalid input (e.g. both `path` and `yaml_content`).
+
+### Execute errors
+
 - **`DF-EXECUTE-SOURCE-NOT-FOUND`** / **`-NOT-FOUND-EMPTY`** — the query's `source:` (or default source) is not configured in `dataface.yml`.
 - **`DF-EXECUTE-NO-DEFAULT-SOURCE`** — multiple sources are defined and no `default_source` was set.
 - **`DF-EXECUTE-SOURCE-INLINE-FORBIDDEN`** / **`-CROSS-FILE-FORBIDDEN`** — inline source definitions are restricted by project policy.

dataface/agent_api/_init_templates/{index.md → README.md}

@@ -11,14 +11,14 @@ for your data project.
 ## Authoring modes
 
 **YAML (`.yml`)** — structured dashboards with queries, charts, and layout.
-See the [dataface guide](dataface) for a working example covering queries, charts, and variables.
+See the [dataface guide](guide) for a working example covering queries, charts, and variables.
 
 **Markdown (`.md`)** — prose pages like this one. Add YAML frontmatter for
 queries and charts, then embed them inline with `{% raw %}{{ chart my_chart }}{% endraw %}`.
 
 ## Next steps
 
-1. Open `faces/dataface.yml` and tweak the content.
+1. Open `faces/guide.yml` and tweak the content.
 2. Run `dft serve` and open the URL it prints.
 3. Add new `.yml` or `.md` files under `faces/` — they appear automatically.
 4. Run `dft validate` to validate your face YAML for errors.

dataface/agent_api/_project_agents_md.py

@@ -15,7 +15,7 @@ _TEMPLATES = importlib.resources.files("dataface.agent_api._init_templates")
 
 def load_agents_snippet() -> str:
     """Return the packaged markdown blurb (includes marker comments)."""
-    return _TEMPLATES.joinpath("agents_dft_snippet.md").read_text()
+    return _TEMPLATES.joinpath("agents_dft_snippet.md").read_text(encoding="utf-8")
 
 
 def has_dataface_markers(text: str) -> bool:

dataface/agent_api/_session_store.py

@@ -198,7 +198,7 @@ class SessionIndex:
     def _load(self) -> dict[str, list[SessionMeta]]:
         if self._path.exists():
             try:
-                raw = json.loads(self._path.read_text())
+                raw = json.loads(self._path.read_text(encoding="utf-8"))
                 if isinstance(raw, dict):
                     return raw
                 logger.warning("sessions/index.json has unexpected shape; rebuilding")
@@ -208,7 +208,7 @@ class SessionIndex:
 
     def _save(self) -> None:
         self._path.parent.mkdir(parents=True, exist_ok=True)
-        self._path.write_text(json.dumps(self._data, indent=2))
+        self._path.write_text(json.dumps(self._data, indent=2), encoding="utf-8")
 
     def _rebuild(self) -> dict[str, list[SessionMeta]]:
         """Scan all JSONL files under ~/.dft/sessions/ and reconstruct the index."""
@@ -234,7 +234,7 @@ class SessionIndex:
             data.setdefault(cwd, []).append(entry)
         # Persist the rebuilt index
         self._path.parent.mkdir(parents=True, exist_ok=True)
-        self._path.write_text(json.dumps(data, indent=2))
+        self._path.write_text(json.dumps(data, indent=2), encoding="utf-8")
         return data
 
 

dataface/agent_api/dashboards.py

@@ -148,7 +148,7 @@ def list_dashboards(
         if yaml_file.name.startswith("_"):
             continue
         try:
-            content = yaml.safe_load(yaml_file.read_text())
+            content = yaml.safe_load(yaml_file.read_text(encoding="utf-8"))
             if not isinstance(content, dict):
                 skipped.append(
                     SkippedFile(
@@ -235,7 +235,7 @@ def get_dashboard(
         )
 
     try:
-        raw_yaml = file_path.read_text()
+        raw_yaml = file_path.read_text(encoding="utf-8")
     except OSError as e:
         return CompiledDashboard(
             success=False,

dataface/agent_api/docs/yaml-reference.md

@@ -15,7 +15,7 @@ AuthoredFace (dataface) definition from YAML.
 | `source` | str | ✓ | Default source name shorthand (equivalent to sources.default). Sets the connection for all queries. |
 | `variables` | dict[str, [Variable](#variable) \| VariableRef] | ✓ | Variable definitions for dynamic filtering and UI controls. |
 | `queries` | dict[str, [Query](#query) \| 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) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| ChartRef] | ✓ | Named chart definitions referenced in the layout. |
+| `charts` | dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [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) \| [LayeredChart](#layeredchart) \| [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) \| [LayeredChart](#layeredchart) \| [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) \| [LayeredChart](#layeredchart) \| [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) \| [LayeredChart](#layeredchart) \| [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. |
@@ -646,13 +646,14 @@ HTTP/REST API source configuration.
 
 <a id="dbtprofilesourceconfig"></a>
 ## DbtProfileSourceConfig
-Reference to a dbt profile (for backward compatibility).
+Reference to a dbt profile.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `type` | enum: "dbt_profile" |  | Source type identifier. |
 | `profile` | str |  | dbt profile name from profiles.yml. |
 | `target` | str | ✓ | dbt target to use; defaults to the profile's default target. |
+| `profiles_dir` | str | ✓ | Directory containing profiles.yml, relative to the dataface project root. Use when profiles.yml is in a subdirectory (e.g. services/dbt). Resolution order: profiles_dir → $DBT_PROFILES_DIR → project root → ~/.dbt. |
 
 <a id="variableoptions"></a>
 ## VariableOptions
@@ -1485,11 +1486,21 @@ Authored overlay for LegendStyle.
 
 <a id="tooltipstyle"></a>
 ## TooltipStyle
-Authored overlay for TooltipStyle. Tooltip rendering defaults.
+Authored overlay for TooltipStyle. Tooltip box style — all cascade keys for the hover bubble.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `format` | str | ✓ | Default tooltip value format string; theme always provides this. |
+| `background` | str | ✓ | Tooltip background color (CSS color string); theme always provides this. |
+| `line_height` | float | ✓ | Tooltip line-height multiplier; theme always provides this. |
+| `max_width` | float | ✓ | Maximum tooltip width in pixels; theme always provides this. |
+| `gap` | float | ✓ | Gap in pixels between label and value columns; theme always provides this. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Tooltip font overrides (size etc.); cascade fills missing fields. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Tooltip inner padding (4 sides in pixels); theme always provides this. |
+| `label` | [TooltipSlotStyle](#tooltipslotstyle) | ✓ | Label-column font overrides (color, weight). |
+| `value` | [TooltipSlotStyle](#tooltipslotstyle) | ✓ | Value-column font overrides (color, weight). |
+| `border` | [TooltipBorderStyle](#tooltipborderstyle) | ✓ | Tooltip border style; theme always provides this. |
+| `shadow` | [TooltipShadowStyle](#tooltipshadowstyle) | ✓ | Tooltip drop-shadow config; theme always provides this. |
 
 <a id="stylecolorconfig"></a>
 ## StyleColorConfig
@@ -2266,6 +2277,32 @@ Authored overlay for LegendElementStyle.
 | `font` | [FontStyle](#fontstyle) | ✓ | Legend element font style overrides. |
 | `padding` | float | ✓ | Padding between legend symbol and element text in pixels. |
 
+<a id="tooltipslotstyle"></a>
+## TooltipSlotStyle
+Authored overlay for TooltipSlotStyle. Typography for a single tooltip slot (label or value).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Font overrides for this tooltip slot (color, weight). |
+
+<a id="tooltipborderstyle"></a>
+## TooltipBorderStyle
+Authored overlay for TooltipBorderStyle. Tooltip box border — all fields required; theme YAML supplies defaults.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `color` | str | ✓ | Border color as a CSS color string. |
+| `width` | float | ✓ | Border width in pixels. |
+| `radius` | float | ✓ | Border corner radius in pixels. |
+
+<a id="tooltipshadowstyle"></a>
+## TooltipShadowStyle
+Authored overlay for TooltipShadowStyle. Tooltip drop-shadow toggle. JS applies the shadow expression when visible=true.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show a drop-shadow on the tooltip box; theme always provides this. |
+
 <a id="scaletargetconfig"></a>
 ## ScaleTargetConfig
 Scale configuration for a single style target (background or color).

dataface/agent_api/init.py

@@ -51,9 +51,18 @@ def init_project(
     (root / "faces" / "partials").mkdir(exist_ok=True)
 
     scaffolds: list[tuple[str, str]] = [
-        ("dataface.yml", _TEMPLATES.joinpath("dataface.yml").read_text()),
-        ("faces/index.md", _TEMPLATES.joinpath("index.md").read_text()),
-        ("faces/dataface.yml", _TEMPLATES.joinpath("faces-dataface.yml").read_text()),
+        (
+            "dataface.yml",
+            _TEMPLATES.joinpath("dataface.yml").read_text(encoding="utf-8"),
+        ),
+        (
+            "faces/README.md",
+            _TEMPLATES.joinpath("README.md").read_text(encoding="utf-8"),
+        ),
+        (
+            "faces/guide.yml",
+            _TEMPLATES.joinpath("guide.yml").read_text(encoding="utf-8"),
+        ),
         ("faces/partials/.gitkeep", ""),
     ]
 
@@ -62,10 +71,10 @@ def init_project(
         if target.exists() and not force:
             result.skipped_files.append(Path(rel))
         elif target.exists():
-            target.write_text(content)
+            target.write_text(content, encoding="utf-8")
             result.refreshed_files.append(Path(rel))
         else:
-            target.write_text(content)
+            target.write_text(content, encoding="utf-8")
             result.created_files.append(Path(rel))
 
     _ensure_gitignore_entries(root, result)
@@ -74,10 +83,12 @@ def init_project(
         snippet = load_agents_snippet()
         agents_md_path = root / "AGENTS.md"
         existing: str | None = (
-            agents_md_path.read_text() if agents_md_path.exists() else None
+            agents_md_path.read_text(encoding="utf-8")
+            if agents_md_path.exists()
+            else None
         )
         final_text, action = merge_agents_snippet(existing, snippet)
-        agents_md_path.write_text(final_text)
+        agents_md_path.write_text(final_text, encoding="utf-8")
         if action == "created":
             result.created_files.append(Path("AGENTS.md"))
         elif action == "refreshed":
@@ -88,7 +99,7 @@ def init_project(
     if write_claude_md:
         claude_md_path = root / "CLAUDE.md"
         if not claude_md_path.exists():
-            claude_md_path.write_text("@AGENTS.md\n")
+            claude_md_path.write_text("@AGENTS.md\n", encoding="utf-8")
             result.created_files.append(Path("CLAUDE.md"))
 
     if eject_inspect:
@@ -111,16 +122,18 @@ def init_project(
 def _ensure_gitignore_entries(root: Path, result: InitResult) -> None:
     gitignore = root / ".gitignore"
     if not gitignore.exists():
-        gitignore.write_text("\n".join(GITIGNORE_ENTRIES) + "\n")
+        gitignore.write_text("\n".join(GITIGNORE_ENTRIES) + "\n", encoding="utf-8")
         result.created_files.append(Path(".gitignore"))
         return
 
-    text = gitignore.read_text()
+    text = gitignore.read_text(encoding="utf-8")
     existing = set(text.splitlines())
     missing = [e for e in GITIGNORE_ENTRIES if e not in existing]
     if not missing:
         return
 
     separator = "" if not text or text.endswith("\n") else "\n"
-    gitignore.write_text(f"{text}{separator}" + "\n".join(missing) + "\n")
+    gitignore.write_text(
+        f"{text}{separator}" + "\n".join(missing) + "\n", encoding="utf-8"
+    )
     result.refreshed_files.append(Path(".gitignore"))

dataface/agent_api/inspect.py

@@ -78,9 +78,9 @@ def eject_templates(
         if target_file.exists() and not force:
             continue
 
-        content = source_file.read_text()
+        content = source_file.read_text(encoding="utf-8")
         source_hash = sha256(content.encode("utf-8")).hexdigest()
-        target_file.write_text(content)
+        target_file.write_text(content, encoding="utf-8")
 
         manifest_templates[name] = {
             "filename": f"{name}.yml",

dataface/agent_api/mcp_install.py

@@ -126,7 +126,7 @@ def _upsert_mcp_config(
     existing: dict[str, Any] = {}
     if config_path.exists():
         try:
-            existing = json.loads(config_path.read_text())
+            existing = json.loads(config_path.read_text(encoding="utf-8"))
             if not isinstance(existing, dict):
                 existing = {}
         except (json.JSONDecodeError, OSError):
@@ -140,7 +140,7 @@ def _upsert_mcp_config(
 
     existing.setdefault(servers_key, {})
     existing[servers_key]["dataface"] = server_entry
-    config_path.write_text(json.dumps(existing, indent=2) + "\n")
+    config_path.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8")
     return f"  {'Updated' if already_has else 'Added dataface to'} {config_path}"
 
 
@@ -158,7 +158,7 @@ def _upsert_toml_mcp_config(
 
     existing: dict[str, Any] = {}
     if config_path.exists():
-        existing = tomllib.loads(config_path.read_text())
+        existing = tomllib.loads(config_path.read_text(encoding="utf-8"))
 
     already_has = "dataface" in existing.get(servers_key, {})
     if already_has and not force:
@@ -166,5 +166,5 @@ def _upsert_toml_mcp_config(
 
     existing.setdefault(servers_key, {})
     existing[servers_key]["dataface"] = server_entry
-    config_path.write_text(tomli_w.dumps(existing))
+    config_path.write_text(tomli_w.dumps(existing), encoding="utf-8")
     return f"  {'Updated' if already_has else 'Added dataface to'} {config_path}"

dataface/agent_api/pack.py

@@ -291,7 +291,8 @@ def _write_face(path: Path, face_dict: dict) -> None:
     path.write_text(
         yaml.dump(
             face_dict, default_flow_style=False, sort_keys=False, allow_unicode=True
-        )
+        ),
+        encoding="utf-8",
     )
 
 
@@ -417,7 +418,8 @@ def apply_proposal(
         # Write a minimal partial YAML comment block
         partial_path.write_text(
             f"# Shared partial: {partial_filename}\n"
-            f"# Add shared query fragments, variables, or chart definitions here.\n"
+            f"# Add shared query fragments, variables, or chart definitions here.\n",
+            encoding="utf-8",
         )
         result.created_files.append(rel)
 

dataface/agent_api/schema.py

@@ -646,7 +646,7 @@ def _project_uses_direct_file_queries(project_root: Path) -> bool:
 
     for dashboard in list_dashboards(directory=project_root, recursive=True).dashboards:
         try:
-            content = dashboard.absolute_path.read_text()
+            content = dashboard.absolute_path.read_text(encoding="utf-8")
         except OSError:
             continue
         if (

dataface/agent_api/search.py

@@ -124,7 +124,7 @@ def _build_index(directory: Path) -> list[dict[str, Any]]:
     for dash in listing.dashboards:
         abs_path = dash.absolute_path
         try:
-            content = yaml.safe_load(abs_path.read_text())
+            content = yaml.safe_load(abs_path.read_text(encoding="utf-8"))
         except (yaml.YAMLError, OSError):
             continue
 

dataface/agent_api/surface_aliases.yaml

@@ -39,7 +39,7 @@ render_dashboard:
 
 query_face:
   tool: "query_face"
-  dft: "dft query --face"
+  dft: "dft query --in"
 
 describe_query:
   tool: "describe_query"

dataface/ai/external_mcp.py

@@ -234,7 +234,7 @@ def _parse_json_config(
     if not path.exists():
         return
     try:
-        data = json.loads(path.read_text())
+        data = json.loads(path.read_text(encoding="utf-8"))
     except json.JSONDecodeError:
         _console.print(f"[yellow]MCP: {path} has invalid JSON; skipping[/yellow]")
         return
@@ -271,7 +271,7 @@ def _parse_toml_config(
     if not path.exists():
         return
     try:
-        data = tomllib.loads(path.read_text())
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
     except (tomllib.TOMLDecodeError, OSError) as exc:
         _console.print(
             f"[yellow]MCP: {path} has invalid TOML: {exc}; skipping[/yellow]"

dataface/ai/memories.py

@@ -17,7 +17,7 @@ def load_memories(base_dir: Path | None = None) -> list[dict[str, Any]]:
     if not path.exists():
         return []
 
-    payload = yaml.safe_load(path.read_text()) or {}
+    payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
     rows = payload.get("memories") if isinstance(payload, dict) else None
     if not isinstance(rows, list):
         return []

dataface/ai/prompts.py

@@ -41,7 +41,7 @@ def load_prompt(prompt_name: str, prompts_dir: Path) -> str:
     """
     prompt_file = prompts_dir / f"{prompt_name}.md"
     if prompt_file.exists():
-        return prompt_file.read_text()
+        return prompt_file.read_text(encoding="utf-8")
     return ""
 
 
@@ -94,7 +94,7 @@ class PromptLoader:
         prompt_file = self.prompts_dir / f"{prompt_name}.md"
         if not prompt_file.exists():
             raise FileNotFoundError(f"Prompt file not found: {prompt_file}")
-        return prompt_file.read_text()
+        return prompt_file.read_text(encoding="utf-8")
 
     def exists(self, prompt_name: str) -> bool:
         """Check if a prompt file exists.
@@ -129,7 +129,7 @@ def load_shared_prompt(skill_name: str, *, surface: SkillSurface = "tool") -> st
     """
     skill_file = SKILLS_DIR / skill_name / "SKILL.md"
     if skill_file.exists():
-        body = _strip_frontmatter(skill_file.read_text())
+        body = _strip_frontmatter(skill_file.read_text(encoding="utf-8"))
         return render_skill_body(body, surface=surface)
     return ""
 

dataface/ai/skills/dataface-troubleshooting/SKILL.md

@@ -38,7 +38,10 @@ These come from `{{ s_validate_dashboard }}`. The error message tells you exactl
 
 ### "must have at least one layout"
 
-Every face needs a layout element. Add `rows: []`, `cols: []`, `grid: {...}`, `tabs: {...}`, or `text: "..."`.
+Every face needs visible content. Add a chart under `charts:`, an explicit
+layout (`rows:`, `cols:`, `grid:`, or `tabs:`), or text/title content. If
+`charts:` is present and no layout key is present, Dataface renders those
+charts as implicit rows.
 
 ### "references unknown chart 'X'"
 

dataface/cli/commands/chat.py

@@ -236,7 +236,7 @@ def _render_tool_result(name: str, result: Any, console: Console, tmpdir: Path)
         # Sanitize name to avoid path separators from LLM-provided tool names.
         safe_name = re.sub(r"[^\w-]", "_", name)
         tmp_file = tmpdir / f"dft_{safe_name}_{int(time.monotonic() * 1000)}.json"
-        tmp_file.write_text(body)
+        tmp_file.write_text(body, encoding="utf-8")
         summary = f"[dim]... ({extra} more lines, full result in {tmp_file})[/dim]"
         console.print(
             Panel(

dataface/cli/commands/init.py

@@ -80,7 +80,7 @@ def run_wizard(
         agents_md_prompt = (
             "Create AGENTS.md at the project root with Dataface instructions?"
         )
-    elif has_dataface_markers(agents_md_path.read_text()):
+    elif has_dataface_markers(agents_md_path.read_text(encoding="utf-8")):
         agents_md_prompt = "Refresh the Dataface section in AGENTS.md?"
     else:
         agents_md_prompt = "Append Dataface instructions to your existing AGENTS.md?"
@@ -137,7 +137,10 @@ def run_wizard(
             default=True,
         )
 
-    # Playground extra — skip prompt if already installed
+    # Playground extra — skip prompt if already installed.
+    # Default is False: dataface-playground is not on public PyPI yet, so an
+    # unprompted install attempt would always fail for OSS users. Explicit
+    # --with-playground still works; failure degrades to a warning (see below).
     if not _missing_packages("playground"):
         do_with_playground = False
     else:
@@ -145,7 +148,7 @@ def run_wizard(
             with_playground,
             yes=yes,
             prompt="Install the dataface[playground] extra now (so 'dft playground' works without prompting later)?",
-            default=True,
+            default=False,
         )
 
     # IDE detection — only prompt for IDEs found on PATH
@@ -238,7 +241,14 @@ def run_wizard(
     if do_with_playground:
         from dataface.cli._extras import install_extras
 
-        install_extras("playground", interactive=False)
+        try:
+            install_extras("playground", interactive=False)
+        except typer.Exit:
+            install_warnings.append(
+                "playground skipped — dataface-playground is not on public PyPI yet. "
+                "Install it from the private registry or run `dft playground` later "
+                "to install interactively."
+            )
 
     if do_vscode:
         from dataface.cli.commands import extension as extension_cmd

dataface/cli/commands/query.py

@@ -186,7 +186,7 @@ def _resolve_sql_text(
         if not file.exists():
             typer.echo(f"Error: file not found: {file}", err=True)
             raise typer.Exit(1)
-        return file.read_text(), False, None
+        return file.read_text(encoding="utf-8"), False, None
 
     if not target:
         typer.echo(

dataface/cli/main.py

@@ -903,9 +903,16 @@ def serve(
     Renders your dashboards in the browser. Face file paths map
     to URLs (faces/sales.yml → /sales/). Query params become variables.
 
-    Auto-discovers the project root by walking up from the current directory
-    to find dataface.yml or dbt_project.yml. When a dbt project is found,
-    the SQL dialect is inferred from the profile target.
+    Auto-discovers the project root by walking UP from the current directory
+    to find dataface.yml or dbt_project.yml. Subdirectories are not searched.
+    When a dbt project is found, the SQL dialect is inferred from the profile
+    target.
+
+    dbt profile location is resolved in this order:
+      1. profiles_dir field in the dbt_profile source config (dataface.yml)
+      2. DBT_PROFILES_DIR environment variable
+      3. Project root (next to dataface.yml / dbt_project.yml)
+      4. ~/.dbt/profiles.yml
 
     Port is auto-resolved: --port flag > DFT_PORT env var > dataface.yml
     port field > deterministic hash of project directory. If the chosen port

dataface/core/compile/compiler.py

@@ -478,20 +478,19 @@ def compile_file(
 
     # Markdown report files: translate to YAML before compiling
     if file_path.suffix.lower() == ".md":
-        from dataface.core.compile.markdown import is_markdown_face, markdown_to_yaml
+        from dataface.core.compile.markdown import (
+            MARKDOWN_NOT_FACE_MESSAGE,
+            is_markdown_face,
+            markdown_to_yaml,
+        )
 
         if not is_markdown_face(file_path):
             return CompileResult(
-                errors=[
-                    CompilationError(
-                        "Not a Dataface face file: .md files require YAML frontmatter "
-                        "with at least one of: queries, charts, variables, source, sources"
-                    ).to_structured()
-                ]
+                errors=[CompilationError(MARKDOWN_NOT_FACE_MESSAGE).to_structured()]
             )
 
         try:
-            raw_text = file_path.read_text()
+            raw_text = file_path.read_text(encoding="utf-8")
             yaml_content = markdown_to_yaml(raw_text)
         except (OSError, ValueError) as e:
             return CompileResult(
@@ -499,7 +498,7 @@ def compile_file(
             )
     else:
         try:
-            yaml_content = file_path.read_text()
+            yaml_content = file_path.read_text(encoding="utf-8")
         except OSError as e:
             return CompileResult(
                 errors=[CompilationError(f"Failed to read file: {e}").to_structured()]