dataface 0.1.5.dev177__py3-none-any.whl → 0.1.5.dev215__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -346,7 +346,7 @@ queries:
       - [Bob, 87.1]
 ```
 
-Query types (`type:` literals): `sql`, `csv`, `http`, `dbt_model`, `metricflow`, `values`. `schema_resolver` is internal-only and not part of the authored surface.
+Query types (`type:` literals): `sql`, `csv`, `http`, `dbt_model`, `metricflow`, `values`. `schema` is internal-only and not part of the authored surface.
 
 Common fields (all query types):
 
@@ -597,12 +597,14 @@ support:                # Optional support line (same shape: value/label/format/
   glyph: "▲"
   tone: positive
 
-# table — renders all query columns unless `style.columns` selects a subset
+# table — renders all query columns unless `style.columns` selects a subset.
+# `columns` is a MAPPING keyed by column name (NOT a list). Omit it to show
+# every query column; include it to choose a subset and/or style columns.
 type: table
 style:
   columns:
-    - column: order_id
-    - column: amount
+    order_id: {}                         # include with default styling
+    amount:                              # the key is the column name
       label: Amount
       format: currency_whole
       align: right                       # left | center | right

dataface/agent_api/cache.py

@@ -1,5 +1,24 @@
 """Cache constructors at the agent_api boundary."""
 
-from dataface.core.execute.duckdb_cache import open_cache_from_env
+from collections.abc import Generator
+from contextlib import contextmanager
 
-__all__ = ["open_cache_from_env"]
+from dataface.core.execute.duckdb_cache import DuckDBCache, open_cache_from_env
+
+__all__ = ["cache_from_env", "open_cache_from_env"]
+
+
+@contextmanager
+def cache_from_env() -> Generator[DuckDBCache | None]:
+    """Open DFT_CACHE_PATH-backed cache (or None) and close it on exit.
+
+    Use for CLI verbs and composition roots that need a cache scoped to
+    a single command invocation. Long-lived processes (server boot, MCP
+    server) use ``open_cache_from_env()`` directly and own the lifecycle.
+    """
+    cache = open_cache_from_env()
+    try:
+        yield cache
+    finally:
+        if cache is not None:
+            cache.close()

dataface/agent_api/dashboards.py

@@ -79,7 +79,7 @@ class RenderDashboardArgs(BaseModel):
     variables: dict[str, Any] | None = Field(
         None, description="Variable values to apply to the dashboard"
     )
-    format: Literal["json", "text", "yaml", "svg"] | None = Field(
+    format: Literal["json", "text", "yaml", "svg", "terminal"] | None = Field(
         None,
         description=(
             "Output format. 'json' (default) returns resolved chart "
@@ -89,7 +89,9 @@ class RenderDashboardArgs(BaseModel):
             "YAML with inline data — valid input for re-compilation, "
             "ideal for round-trip editing. 'svg' returns the rendered "
             "dashboard as inline SVG (under result['data']) for hosts "
-            "that embed the rendered output directly."
+            "that embed the rendered output directly. 'terminal' returns "
+            "the charts as ANSI text (under result['data']) for display "
+            "in a terminal."
         ),
     )
     as_link: bool = Field(

dataface/agent_api/docs/yaml-reference.md

@@ -11,6 +11,7 @@ AuthoredFace (dataface) definition from YAML.
 | `tags` | list[str] | ✓ | Tags for categorization and search. |
 | `docs` | str | ✓ | Relative path under the docs site for the canonical doc page that explains this face. Surfaced as a 'Docs →' link in the playground gallery when DFT_DOCS_URL is set. |
 | `text` | str | ✓ | Markdown text content for text-only sections. |
+| `allow_html` | bool | ✓ | Render the face's body text as raw HTML via foreignObject instead of markdown. TRUSTED-CONTENT ONLY: the HTML (including any Jinja-interpolated values) is rendered as-authored — this is NOT a security sandbox. mdsvg strips <script>/event-handlers as a best-effort guard, not a guarantee. Enable only on first-party faces you fully control. |
 | `sources` | [SourcesSection](#sourcessection) | ✓ | Database source configuration. Use 'default:' to set the default source for all queries. |
 | `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. |
@@ -71,7 +72,7 @@ AuthoredQuery definition from YAML.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `type` | enum: "sql", "metricflow", "dbt_model", "http", "csv", "values", "schema_resolver" | ✓ | Query adapter type. Defaults to 'sql'. Options: sql, metricflow, dbt_model, http, csv, values, schema_resolver. |
+| `type` | enum: "sql", "metricflow", "dbt_model", "http", "csv", "values", "schema" | ✓ | Query adapter type. Defaults to 'sql'. Options: sql, metricflow, dbt_model, http, csv, values, schema. |
 | `source` | str \| dict[str, Any] | ✓ | Database source reference (name string) or inline source config dict. |
 | `target` | str | ✓ | dbt target name for dbt_model queries (defaults to 'dev'). |
 | `sql` | str | ✓ | SQL query string. Supports Jinja2 templates referencing variables. |
@@ -91,9 +92,9 @@ AuthoredQuery definition from YAML.
 | `filter` | dict[str, Any] | ✓ | Row-level filter applied to CSV or values data. |
 | `delimiter` | str | ✓ | Column delimiter for CSV queries. Default: comma (','). |
 | `encoding` | str | ✓ | File encoding for CSV queries. Default: UTF-8. |
-| `schema` | str | ✓ | Schema name for schema_resolver queries (YAML key: schema). |
-| `table` | str | ✓ | Table name for schema_resolver queries. |
-| `column` | str | ✓ | Column name for schema_resolver queries. |
+| `schema` | str | ✓ | Schema name for schema queries (YAML key: schema). |
+| `table` | str | ✓ | Table name for schema queries. |
+| `column` | str | ✓ | Column name for schema queries. |
 | `rows` | list[dict[str, Any]] | ✓ | Inline data rows for values-type queries (list of row dicts). |
 | `values` | list[list[Any]] | ✓ | Inline column-oriented data for values-type queries (list of lists). |
 | `description` | str | ✓ | Human-readable description of the query. Used by AI search and tooling. |
@@ -490,6 +491,8 @@ Authored overlay for Style — all fields optional. Adds CSS shorthand coercers.
 | `layout` | [LayoutStyle](#layoutstyle) | ✓ | Layout container styles (rows, cols, grid, tabs, details). |
 | `variables` | [VariablesStyle](#variablesstyle) | ✓ | Variable controls chrome style. |
 | `page` | [PageStyle](#pagestyle) | ✓ | Page-level canvas style (behind the board). |
+| `footer` | [FooterStyle](#footerstyle) | ✓ | Page footer chrome visibility. |
+| `timestamp` | [TimestampStyle](#timestampstyle) | ✓ | Render-timestamp chrome: visibility, format, and font. |
 | `formats` | dict[str, str] | ✓ | Format alias map; None means no aliases at this cascade level. |
 | `palettes` | dict[str, str] | ✓ | Theme palette role assignments: open dict mapping role name to palette file name. Default seed: chrome, negative, positive, warning, category, sequence, diverge. |
 | `roles` | dict[str, str] | ✓ | Optional top-level theme role aliases: bare name → role.alias. e.g. ink: chrome.heading |
@@ -1063,8 +1066,7 @@ Authored overlay for BoardStyle. Face-level structural dimensions. Do NOT cascad
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `width` | float | ✓ | Board width in pixels. |
-| `default_height` | float | ✓ | Default row height in pixels. |
-| `min_height` | float | ✓ | Minimum row height in pixels. |
+| `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. |
 | `card_gap` | float | ✓ | Gap between cards in pixels. |
@@ -1221,6 +1223,24 @@ Authored overlay for PageStyle. Page-level (outer HTML canvas) styling.
 |-------|------|:--------:|-------------|
 | `background` | str | ✓ | Page canvas background color (behind the face board). |
 
+<a id="footerstyle"></a>
+## FooterStyle
+Authored overlay for FooterStyle. Authored visibility toggle for the page footer chrome.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show the footer attribution line. |
+
+<a id="timestampstyle"></a>
+## TimestampStyle
+Authored overlay for TimestampStyle. Authored timestamp chrome: visibility, strftime format, and font.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show the render-timestamp line. |
+| `format` | str | ✓ | strftime format string for the render timestamp. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Timestamp font style overrides (size, color, weight, ...). |
+
 <a id="spacingvalues"></a>
 ## SpacingValues
 Pre-parsed CSS spacing (margin/padding).

dataface/agent_api/files.py

@@ -0,0 +1,262 @@
+"""General project-file tools for the chat agent.
+
+Claude-Code-style primitives — read, write, edit, glob, grep — that let an
+agent author and save faces directly, rather than via a domain-specific
+"write a dashboard" verb. The agent composes these with the typed dft tools
+(``validate_dashboard``, ``render_dashboard``, ``schema``, ``execute_query``).
+
+Every path is resolved against and confined to the project root. A path that
+escapes the root (``..`` traversal, absolute path outside, symlink out) is
+refused — these tools never touch the wider filesystem.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+# Cap grep/glob payloads — read_file returns full content (model must handle size).
+_MAX_GREP_MATCHES = 200
+_MAX_GLOB_MATCHES = 500
+
+# Directory names to skip on whole-tree scans — avoids traversing .venv,
+# .git, node_modules, target, etc. which can be huge and contain no user code.
+_SKIP_DIRS = frozenset(
+    {".git", ".venv", "venv", "node_modules", "target", "__pycache__", ".tox"}
+)
+
+
+class ReadFileArgs(BaseModel):
+    """Read a UTF-8 text file from the project. Path is relative to the project root."""
+
+    path: str = Field(description="File path relative to the project root.")
+
+
+class WriteFileArgs(BaseModel):
+    """Write a UTF-8 text file in the project, creating parent directories.
+
+    Overwrites an existing file. To change part of an existing file, prefer
+    edit_file so you don't clobber content you haven't read. Path is relative
+    to the project root and may not escape it.
+    """
+
+    path: str = Field(description="File path relative to the project root.")
+    content: str = Field(description="Full file contents to write.")
+
+
+class EditFileArgs(BaseModel):
+    """Replace an exact string in a project file. old_string must occur exactly once.
+
+    Fails (writing nothing) if old_string is absent or appears more than once —
+    include enough surrounding context to make it unique. Path is relative to
+    the project root and may not escape it.
+    """
+
+    path: str = Field(description="File path relative to the project root.")
+    old_string: str = Field(description="Exact text to replace (must be unique).")
+    new_string: str = Field(description="Replacement text.")
+
+
+class GlobFilesArgs(BaseModel):
+    """List files matching a glob pattern under the project root (e.g. 'faces/*.yml')."""
+
+    pattern: str = Field(description="Glob pattern relative to the project root.")
+
+
+class GrepFilesArgs(BaseModel):
+    """Search file contents for a substring under the project root.
+
+    Optionally restrict to files matching a glob (e.g. only 'faces/**/*.yml').
+    Skips .git, .venv, node_modules, target, and other large non-user directories.
+    """
+
+    pattern: str = Field(description="Substring to search for (case-sensitive).")
+    glob: str | None = Field(
+        default=None, description="Optional glob to restrict which files are searched."
+    )
+
+
+class ReadFileResult(BaseModel):
+    success: bool
+    path: str
+    content: str | None = None
+    error: str | None = None
+
+
+class WriteFileResult(BaseModel):
+    success: bool
+    path: str
+    bytes_written: int = 0
+    error: str | None = None
+
+
+class EditFileResult(BaseModel):
+    success: bool
+    path: str
+    replacements: int = 0
+    error: str | None = None
+
+
+class GlobResult(BaseModel):
+    success: bool
+    matches: list[str] = Field(default_factory=list)
+    truncated: bool = False
+    error: str | None = None
+
+
+class GrepMatch(BaseModel):
+    path: str
+    line_number: int
+    line: str
+
+
+class GrepResult(BaseModel):
+    success: bool
+    matches: list[GrepMatch] = Field(default_factory=list)
+    truncated: bool = False
+    error: str | None = None
+
+
+def _resolve_within(project_dir: Path, raw: str) -> Path:
+    """Resolve ``raw`` against the project root, refusing anything that escapes it."""
+    root = project_dir.resolve()
+    candidate = Path(raw)
+    candidate = candidate if candidate.is_absolute() else root / candidate
+    resolved = candidate.resolve()
+    if resolved != root and root not in resolved.parents:
+        raise ValueError(f"path {raw!r} escapes the project root")
+    return resolved
+
+
+def _rel(project_dir: Path, p: Path) -> str:
+    return str(p.resolve().relative_to(project_dir.resolve()))
+
+
+def _walk_project(root: Path) -> list[Path]:
+    """Return files under root, skipping known large/irrelevant directories."""
+    result: list[Path] = []
+    for item in sorted(root.iterdir()):
+        if item.is_dir():
+            if item.name in _SKIP_DIRS or item.name.startswith("."):
+                continue
+            result.extend(_walk_project(item))
+        elif item.is_file():
+            result.append(item)
+    return result
+
+
+def read_file(path: str, project_dir: Path) -> ReadFileResult:
+    try:
+        target = _resolve_within(project_dir, path)
+    except ValueError as exc:
+        return ReadFileResult(success=False, path=path, error=str(exc))
+    if not target.is_file():
+        return ReadFileResult(success=False, path=path, error=f"file not found: {path}")
+    try:
+        content = target.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return ReadFileResult(success=False, path=path, error=str(exc))
+    return ReadFileResult(success=True, path=_rel(project_dir, target), content=content)
+
+
+def write_file(path: str, content: str, project_dir: Path) -> WriteFileResult:
+    try:
+        target = _resolve_within(project_dir, path)
+    except ValueError as exc:
+        return WriteFileResult(success=False, path=path, error=str(exc))
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        return WriteFileResult(success=False, path=path, error=str(exc))
+    return WriteFileResult(
+        success=True,
+        path=_rel(project_dir, target),
+        bytes_written=len(content.encode("utf-8")),
+    )
+
+
+def edit_file(
+    path: str, old_string: str, new_string: str, project_dir: Path
+) -> EditFileResult:
+    try:
+        target = _resolve_within(project_dir, path)
+    except ValueError as exc:
+        return EditFileResult(success=False, path=path, error=str(exc))
+    if not target.is_file():
+        return EditFileResult(success=False, path=path, error=f"file not found: {path}")
+    try:
+        original = target.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return EditFileResult(success=False, path=path, error=str(exc))
+    count = original.count(old_string)
+    if count == 0:
+        return EditFileResult(
+            success=False, path=path, error="old_string not found in file"
+        )
+    if count > 1:
+        return EditFileResult(
+            success=False,
+            path=path,
+            error=f"old_string is not unique ({count} occurrences) — add surrounding context",
+        )
+    try:
+        target.write_text(original.replace(old_string, new_string), encoding="utf-8")
+    except OSError as exc:
+        return EditFileResult(success=False, path=path, error=str(exc))
+    return EditFileResult(success=True, path=_rel(project_dir, target), replacements=1)
+
+
+def glob_files(pattern: str, project_dir: Path) -> GlobResult:
+    root = project_dir.resolve()
+    matches: list[str] = []
+    try:
+        candidates = root.glob(pattern)
+    except (ValueError, OSError, NotImplementedError) as exc:
+        return GlobResult(success=False, error=str(exc))
+    for p in sorted(candidates):
+        if not p.is_file():
+            continue
+        try:
+            rel = p.resolve().relative_to(root)
+        except ValueError:
+            continue  # symlink escaping the root
+        matches.append(str(rel))
+        if len(matches) >= _MAX_GLOB_MATCHES:
+            return GlobResult(success=True, matches=matches, truncated=True)
+    return GlobResult(success=True, matches=matches)
+
+
+def grep_files(pattern: str, project_dir: Path, glob: str | None = None) -> GrepResult:
+    root = project_dir.resolve()
+    matches: list[GrepMatch] = []
+    try:
+        candidates: list[Path] = (
+            sorted(root.glob(glob)) if glob else _walk_project(root)
+        )
+    except (ValueError, OSError, NotImplementedError) as exc:
+        return GrepResult(success=False, error=str(exc))
+    for p in candidates:
+        if not p.is_file():
+            continue
+        try:
+            rel = p.resolve().relative_to(root)
+        except ValueError:
+            continue
+        try:
+            with p.open(encoding="utf-8") as fh:
+                for i, line in enumerate(fh, start=1):
+                    if pattern in line:
+                        matches.append(
+                            GrepMatch(
+                                path=str(rel), line_number=i, line=line.rstrip("\n")
+                            )
+                        )
+                        if len(matches) >= _MAX_GREP_MATCHES:
+                            return GrepResult(
+                                success=True, matches=matches, truncated=True
+                            )
+        except (OSError, UnicodeDecodeError):
+            continue  # skip binary / unreadable files
+    return GrepResult(success=True, matches=matches)

dataface/agent_api/project.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import sys
 from dataclasses import dataclass
+from functools import cached_property
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -38,6 +39,7 @@ from dataface.core.execute.duckdb_cache import DuckDBCache
 
 if TYPE_CHECKING:
     from dataface.core.dashboard import RenderedDashboard, RenderFormat
+    from dataface.core.execute.source_resolver import SourceResolver
 
 
 @dataclass(init=False)
@@ -54,7 +56,6 @@ class Project:
     project_root: Path
     cache: DuckDBCache | None
     _owns_registry: bool
-    _adapter_registry: AdapterRegistry | None
     _read_only: bool
     _dbt_project_path: Path | None
     _connection_string: str | None
@@ -62,6 +63,9 @@ class Project:
     _target: str
     _duckdb_config: dict[str, Any] | None
     _allow_external_access_in_readonly: bool
+    _resolver: SourceResolver | None
+    _sources: ProjectSourcesConfig
+    _warnings_ignore: frozenset[str]
 
     def __init__(
         self,
@@ -74,7 +78,10 @@ class Project:
         # We own the registry only when we'll lazy-build it ourselves. An injected
         # registry belongs to the caller; we use it but don't close it on their behalf.
         self._owns_registry = adapter_registry is None
-        self._adapter_registry = adapter_registry
+        if adapter_registry is not None:
+            # cached_property stores in __dict__; pre-populating makes the descriptor
+            # short-circuit the build on first access.
+            self.__dict__["adapter_registry"] = adapter_registry
         self._read_only = True
         self._dbt_project_path = None
         self._connection_string = None
@@ -82,6 +89,9 @@ class Project:
         self._target = "dev"
         self._duckdb_config = None
         self._allow_external_access_in_readonly = False
+        self._resolver = None
+        self._sources = get_project_sources(self.project_root)
+        self._warnings_ignore = get_project_warnings_ignore(self.project_root)
 
     @classmethod
     def open(
@@ -96,6 +106,7 @@ class Project:
         target: str = "dev",
         duckdb_config: dict[str, Any] | None = None,
         allow_external_access_in_readonly: bool = False,
+        resolver: SourceResolver | None = None,
     ) -> Self:
         """Construct a Project rooted at *project_dir*.
 
@@ -116,6 +127,7 @@ class Project:
         project._target = target
         project._duckdb_config = duckdb_config
         project._allow_external_access_in_readonly = allow_external_access_in_readonly
+        project._resolver = resolver
         return project
 
     def __enter__(self) -> Self:
@@ -124,7 +136,7 @@ class Project:
     def __exit__(self, *exc_info: object) -> None:
         self.close()
 
-    @property
+    @cached_property
     def adapter_registry(self) -> AdapterRegistry:
         """Lazily build the registry on first access; cached thereafter.
 
@@ -132,56 +144,49 @@ class Project:
         own it (i.e. it was not injected at construction time).
         When constructed with an injected registry, returns it directly.
         """
-        if self._adapter_registry is None:
-            self._adapter_registry = build_adapter_registry(
-                self.project_root,
-                read_only=self._read_only,
-                dbt_project_path=self._dbt_project_path,
-                connection_string=self._connection_string,
-                profile_type=self._dialect,
-                target=self._target,
-                duckdb_config=self._duckdb_config,
-                allow_external_access_in_readonly=self._allow_external_access_in_readonly,
-            )
-        return self._adapter_registry
+        return build_adapter_registry(
+            self.project_root,
+            read_only=self._read_only,
+            dbt_project_path=self._dbt_project_path,
+            connection_string=self._connection_string,
+            profile_type=self._dialect,
+            target=self._target,
+            duckdb_config=self._duckdb_config,
+            allow_external_access_in_readonly=self._allow_external_access_in_readonly,
+            resolver=self._resolver,
+        )
 
     def refresh(self) -> None:
         """Policy-free rebuild primitive.
 
         For projects opened via ``open()``: closes the current registry (if built)
-        and clears it so the next access rebuilds from disk.
+        and clears it so the next access rebuilds from disk. Also re-reads
+        sources and warnings_ignore from disk.
 
-        For projects constructed with an injected ``adapter_registry``: no-op,
-        because the build arguments are not available to rebuild.
+        For projects constructed with an injected ``adapter_registry``: skips the
+        registry rebuild (build arguments are not available), but still re-reads
+        the config fields.
         """
-        if not self._owns_registry:
-            return
-        if self._adapter_registry is not None:
-            self._adapter_registry.close()
-            self._adapter_registry = None
+        if self._owns_registry and "adapter_registry" in self.__dict__:
+            self.adapter_registry.close()
+            del self.__dict__["adapter_registry"]
+        self._sources = get_project_sources(self.project_root)
+        self._warnings_ignore = get_project_warnings_ignore(self.project_root)
 
     def close(self) -> None:
         """Close the adapter registry iff we own it. The cache is the caller's to close."""
-        if self._owns_registry and self._adapter_registry is not None:
-            self._adapter_registry.close()
-            self._adapter_registry = None
-
-    # ── Config accessors ─────────────────────────────────────────────────────
+        if self._owns_registry and "adapter_registry" in self.__dict__:
+            self.adapter_registry.close()
+            del self.__dict__["adapter_registry"]
 
+    # Read-only views: project lifecycle owns these; external writers go through refresh().
+    @property
     def sources(self) -> ProjectSourcesConfig:
-        """Fresh read of _sources.yaml + dataface.yml sources section.
-
-        No instance-level cache: every call routes through the loader. The underlying
-        loader in `core/compile/config.py` currently warms a module-level cache keyed
-        by `project_dir`, so end-to-end disk freshness is gated on that cache being
-        deleted in a follow-up; this method's contract (fresh-per-call invocation
-        of the loader) is independent of that work.
-        """
-        return get_project_sources(self.project_root)
+        return self._sources
 
+    @property
     def warnings_ignore(self) -> frozenset[str]:
-        """Fresh read of dataface.yml warnings.ignore section. Forwards to the loader on every call."""
-        return get_project_warnings_ignore(self.project_root)
+        return self._warnings_ignore
 
     # ── Verb forwarders ──────────────────────────────────────────────────────
 
@@ -290,6 +295,7 @@ class Project:
             variables=variables,
             adapter_registry=self.adapter_registry,
             project_dir=self.project_root,
+            project_sources=self.sources,
             duckdb_cache=self.cache,
             format=format,
             use_cache=use_cache,
@@ -298,4 +304,5 @@ class Project:
             scale=scale,
             ignore_codes=ignore_codes,
             max_workers=max_workers,
+            warnings_ignore=self.warnings_ignore,
         )

dataface/agent_api/render_face.py

@@ -23,6 +23,8 @@ from dataface.core.render.face_api import compile_and_render
 
 def render_face(
     face_path: str | Path,
+    *,
+    warnings_ignore: frozenset[str],
     format: str = "svg",
     project_dir: str | Path | None = None,
     base_dir: str | Path | None = None,
@@ -35,6 +37,10 @@ def render_face(
 
     Args:
         face_path: Path to the .yml or .md face file to render.
+        warnings_ignore: Project-level warning codes to suppress. Caller
+            resolves this (typically via
+            ``get_project_warnings_ignore(project_root)``); render_face
+            does no disk I/O for warnings config.
         format: Output format — "svg", "html", "png", "pdf", etc.
         project_dir: Explicit project root. When omitted, auto-discovered
             upward from the face file's directory.
@@ -83,6 +89,7 @@ def render_face(
             project_root=project_root,
             adapter_registry=adapter_registry,
             cache=cache,
+            warnings_ignore=warnings_ignore,
             base_dir=resolved_base_dir,
             format=format,
             variables=variables,

dataface/agent_api/surface_aliases.yaml

@@ -53,6 +53,10 @@ schema_search:
   tool: "schema_search"
   dft: "dft schema -s"
 
+search_dashboards:
+  tool: "search_dashboards"
+  dft: "dft search"
+
 # ---- Inline skill-pointer references --------------------------------------
 
 skill_build:

dataface/ai/__init__.py

@@ -9,7 +9,7 @@ Modules:
     yaml_utils: YAML extraction from AI responses
 """
 
-from dataface.ai.prompts import PromptLoader, load_prompt
+from dataface.ai.prompts import load_prompt
 from dataface.ai.schema_context import get_schema_context
 from dataface.ai.tools import (
     TOOL_EXECUTE_QUERY,
@@ -24,7 +24,6 @@ from dataface.ai.yaml_utils import extract_yaml
 __all__ = [
     # Prompts
     "load_prompt",
-    "PromptLoader",
     # Tools
     "get_tools",
     "handle_tool_call",