dataface 0.2.1.dev691__py3-none-any.whl → 0.3.0__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -676,7 +676,7 @@ style:
       label: Amount
       format: currency_whole
       align: right                       # left | center | right
-      header_overflow: wrap-two          # clip | truncate | wrap-two | wrap
+      header_overflow: wrap-two          # clip | truncate | wrap-two (default) | wrap
       header_link: "/columns/amount"
       link: "/orders?id={{ order_id }}"
       background: "#fafafa"

dataface/agent_api/dashboards.py

@@ -115,11 +115,20 @@ class RenderDashboardArgs(BaseModel):
     variables: dict[str, Any] | None = Field(
         None, description="Variable values to apply to the dashboard"
     )
-    format: Literal["json", "text", "yaml", "svg", "terminal"] | None = Field(
+    format: Literal["json", "text", "yaml", "svg", "terminal", "data"] | None = Field(
         None,
         description=(
-            "Output format. 'json' (default) returns resolved chart "
-            "semantics and executed data as structured JSON. 'text' "
+            "Output format. 'json' (default) returns the full resolved chart "
+            "semantics and executed data as structured JSON, nested by "
+            "layout. 'data' returns a flatter, narrower view: 'queries' "
+            "keyed by query name (sql, plus one copy of the rows) and "
+            "'charts' keyed by slug carrying title/description/type and "
+            "encoding, each referencing its query by name. It drops the "
+            "layout nesting, repeats no rows across charts that share a "
+            "query, and reports the variable values the rows were produced "
+            "with — but emits only the authored chart fields, not every "
+            "resolved one, so prefer 'json' when you need the full chart. "
+            "'text' "
             "returns a compact markdown summary of charts and data "
             "(most token-efficient). 'yaml' returns resolved Dataface "
             "YAML with inline data — valid input for re-compilation, "
@@ -165,7 +174,7 @@ def list_dashboards(
                 continue
             if not any(key in content for key in DASHBOARD_KEYS):
                 continue
-            stem = Path(pf.relpath).stem
+            stem = pf.stem
             dashboards.append(
                 DashboardSummary(
                     file=pf,

dataface/agent_api/describe.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from pathlib import Path, PurePosixPath
+from pathlib import Path
 from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -352,17 +352,11 @@ def _describe_one_path(
         return [_describe_resolved(resolved, project=project)]
 
     faces = sorted(
-        (
-            pf
-            for pf in project.iter_faces(under=resolved.relpath, recursive=True)
-            if pf.is_yaml
-            and not pf.is_private
-            and not (pf.parent / INSPECT_TEMPLATE_MANIFEST).exists()
-        ),
-        # Relpaths under `under` share a common prefix, so a PurePosixPath key
-        # reproduces the old absolute-Path sort order exactly on 3.10 and
-        # 3.13 — don't "simplify" this to a str/.parts key.
-        key=lambda pf: PurePosixPath(pf.relpath),
+        pf
+        for pf in project.iter_faces(under=resolved.relpath, recursive=True)
+        if pf.is_yaml
+        and not pf.is_private
+        and not (pf.parent / INSPECT_TEMPLATE_MANIFEST).exists()
     )
     if not faces:
         return [

dataface/agent_api/docs/yaml-reference.md

@@ -533,7 +533,7 @@ Authored overlay for Style — all fields optional. Adds CSS shorthand coercers.
 | `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, placement, format, and font. |
+| `timestamp` | [TimestampStyle](#timestampstyle) | ✓ | Data-freshness chrome: visibility, placement, 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, info, 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 |
@@ -1126,6 +1126,7 @@ Authored overlay for TextStyle. Markdown / plain text content.
 | `column` | [TextColumnStyle](#textcolumnstyle) | ✓ | Multi-column layout for the face body-text block. |
 | `code` | [TextCodeStyle](#textcodestyle) | ✓ | Inline + fenced code box styling (font, background, border). |
 | `blockquote` | [TextBlockquoteStyle](#textblockquotestyle) | ✓ | Blockquote box styling (font, background, border/left-rule). |
+| `bold` | [TextBoldStyle](#textboldstyle) | ✓ | Inline bold-run styling (weight), distinct from heading weight. |
 
 <a id="placeholderstyle"></a>
 ## PlaceholderStyle
@@ -1241,14 +1242,14 @@ Authored overlay for FooterStyle. Page footer chrome: visibility, attribution te
 
 <a id="timestampstyle"></a>
 ## TimestampStyle
-Authored overlay for TimestampStyle. Authored timestamp chrome: visibility, placement, strftime format, font, and y-offset.
+Authored overlay for TimestampStyle. Authored data-freshness chrome: visibility, placement, strftime format, font, and y-offset.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `visible` | bool | ✓ | Show the render-timestamp line. |
+| `visible` | bool | ✓ | Show the data-freshness line. |
 | `position` | enum: "top", "footer" | ✓ | Timestamp row: top page chrome or footer baseline. |
 | `align` | enum: "left", "right" | ✓ | Timestamp horizontal alignment within its row. |
-| `format` | str | ✓ | strftime format string for the render timestamp. |
+| `format` | str | ✓ | strftime format for the data-freshness line, including any literal label text (e.g. '%H:%M %Z on %-d %b %Y'). The value is always UTC; a format that prints a clock must disclose the zone (%Z or a literal 'UTC'), else compile rejects it — an unlabeled clock reads as local. |
 | `y` | float | ✓ | Y-coordinate for top-positioned timestamp in pixels. |
 | `font` | [FontStyle](#fontstyle) | ✓ | Timestamp font style overrides (size, color, weight, ...). |
 
@@ -1937,6 +1938,14 @@ Authored overlay for TextBlockquoteStyle. Blockquote prose. Box group; border is
 | `background` | str | ✓ | Box background fill. |
 | `border` | [BorderStyle](#borderstyle) | ✓ | Box border (width, color, radius). |
 
+<a id="textboldstyle"></a>
+## TextBoldStyle
+Authored overlay for TextBoldStyle. Inline **bold** text runs in markdown prose, distinct from heading weight.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `weight` | str \| float | ✓ | CSS font-weight for bold text runs and bold table cells. |
+
 <a id="placeholderoverlay"></a>
 ## PlaceholderOverlay
 Authored overlay for PlaceholderOverlay.
@@ -2237,7 +2246,7 @@ Authored overlay for AxisElementStyle. Axis label or title: font + padding + VL-
 | `angle` | float | ✓ | Label rotation angle in degrees; None uses Vega-Lite's default. |
 | `align` | enum: "left", "right", "center", "inward", "outward" | ✓ | Horizontal text alignment of labels. 'left'/'right'/'center' are absolute. 'inward' hugs the plot (own-side: left on a left axis, right on a right axis); 'outward' hugs away from the plot (Vega-Lite's default growth direction). inward/outward are a no-op on an axis with no left/right edge. None uses Vega-Lite's default. |
 | `baseline` | str | ✓ | Vertical text baseline of labels; None uses Vega-Lite's default. |
-| `overlap` | [AxisLabelOverlapConfig](#axislabeloverlapconfig) | ✓ | Label overlap strategy enablement. None inherits from the theme cascade. Set individual bools to enable/disable; the resolver applies them in fixed order tilt→skip. Temporal-bucketed axes ignore this and step the label cadence instead. |
+| `overlap` | [AxisLabelOverlapConfig](#axislabeloverlapconfig) | ✓ | Label overlap strategy enablement. None inherits from the theme cascade. Set individual bools to enable/disable; the resolver applies them in fixed order skip→tilt. On bucketed temporal axes, skip thins label visibility to a coarser calendar period without changing the axis or label time unit. |
 | `separation` | float | ✓ | Minimum pixel separation between labels; None uses Vega-Lite's default (0px). |
 | `visible` | bool | ✓ | Show axis labels; None uses Vega-Lite's default (labels shown). |
 | `time_unit` | enum: "auto", "year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate", "monthofyear", "dayofweek", "dayofmonth", "dayofyear", "hourofday", "none" | ✓ | Label cadence for temporal axes; None inherits from the parent axis time_unit. |
@@ -2654,12 +2663,12 @@ Authored overlay for AxisGridZeroStyle. Zero-baseline gridline color and width o
 
 <a id="axislabeloverlapconfig"></a>
 ## AxisLabelOverlapConfig
-Authored overlay for AxisLabelOverlapConfig. Two-bool overlap strategy enablement for CATEGORICAL axis labels.
+Authored overlay for AxisLabelOverlapConfig. Two-bool overlap strategy enablement for x-axis labels.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `tilt` | bool | ✓ | Enable label tilt strategy; None inherits from parent axis. |
-| `skip` | bool | ✓ | Enable parity-skip strategy (drops every other label); None inherits from parent axis. |
+| `skip` | bool | ✓ | Enable temporal label thinning; ignored on categorical axes; None inherits from parent axis. |
 
 <a id="datatablerowpaddingstyle"></a>
 ## DataTableRowPaddingStyle
@@ -2804,15 +2813,25 @@ Postgres source configuration.
 |-------|------|:--------:|-------------|
 | `type` | enum: "postgres" |  | Source type identifier. |
 | `host` | str |  | Database host name or IP address. |
-| `dbname` | str |  | Database name (matches dbt 'dbname'). |
+| `dbname` | str |  | Database name (dbt accepts database as an input alias). |
 | `user` | str |  | Database user name. |
-| `password` | str |  | Database password. |
+| `password` | str |  | Database password (dbt accepts pass as an input alias). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
+| `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `port` | int | ✓ | Database port number. |
 | `schema` | str | ✓ | Default schema for queries. |
+| `connect_timeout` | int | ✓ | Connection timeout in seconds. |
+| `role` | str | ✓ | PostgreSQL role to assume after connecting. |
+| `search_path` | str | ✓ | PostgreSQL search_path for the connection. |
+| `keepalives_idle` | int | ✓ | Idle seconds before TCP keepalives begin. |
 | `sslmode` | enum: "disable", "allow", "prefer", "require", "verify-ca", "verify-full" | ✓ | libpq SSL mode forwarded to psycopg2. None lets libpq decide its default. |
+| `sslcert` | str | ✓ | Path to the client SSL certificate. |
+| `sslkey` | str | ✓ | Path to the client SSL private key. |
+| `sslrootcert` | str | ✓ | Path to the trusted SSL certificate authority file. |
+| `application_name` | str | ✓ | Application name reported to PostgreSQL. |
+| `retries` | int | ✓ | Number of connection retry attempts. |
 
 <a id="snowflakesourceconfig"></a>
 ## SnowflakeSourceConfig
@@ -2822,15 +2841,38 @@ Snowflake source configuration.
 |-------|------|:--------:|-------------|
 | `type` | enum: "snowflake" |  | Source type identifier. |
 | `account` | str |  | Snowflake account identifier (e.g. xy12345.us-east-1). |
-| `user` | str |  | Snowflake user name. |
 | `database` | str |  | Snowflake database name. |
-| `warehouse` | str |  | Snowflake virtual warehouse name. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
+| `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
+| `user` | str | ✓ | Snowflake user name. Omit for token-based authentication when supported. |
 | `password` | str | ✓ | Snowflake password. Omit when using OAuth or key-pair auth. |
+| `warehouse` | str | ✓ | Snowflake virtual warehouse name. |
 | `schema` | str | ✓ | Default schema for queries. |
 | `role` | str | ✓ | Snowflake role to assume for the session. |
+| `authenticator` | str | ✓ | Snowflake authenticator name or external-browser mode. |
+| `private_key` | str | ✓ | PEM private key used for key-pair authentication. |
+| `private_key_path` | str | ✓ | Path to a PEM private key for key-pair authentication. |
+| `private_key_passphrase` | str | ✓ | Passphrase for the configured private key. |
+| `token` | str | ✓ | OAuth access token for token authentication. |
+| `oauth_client_id` | str | ✓ | OAuth client identifier. |
+| `oauth_client_secret` | str | ✓ | OAuth client secret. |
+| `query_tag` | str | ✓ | Snowflake query tag applied to statements. |
+| `client_session_keep_alive` | bool | ✓ | Whether Snowflake keeps the client session alive. |
+| `host` | str | ✓ | Snowflake host override. |
+| `port` | int | ✓ | Snowflake port override. |
+| `proxy_host` | str | ✓ | HTTP proxy host for Snowflake connections. |
+| `proxy_port` | int | ✓ | HTTP proxy port for Snowflake connections. |
+| `protocol` | str | ✓ | Network protocol for the Snowflake connection. |
+| `connect_retries` | int | ✓ | Number of retries while opening a connection. |
+| `connect_timeout` | int | ✓ | Connection timeout in seconds. |
+| `retry_on_database_errors` | bool | ✓ | Whether database errors are retried. |
+| `retry_all` | bool | ✓ | Whether all connection errors are retried. |
+| `insecure_mode` | bool | ✓ | Whether TLS certificate verification is disabled. |
+| `reuse_connections` | bool | ✓ | Whether dbt reuses Snowflake connections. |
+| `s3_stage_vpce_dns_name` | str | ✓ | Private VPC endpoint DNS name for S3 staging. |
+| `platform_detection_timeout_seconds` | float | ✓ | Timeout for Snowflake platform detection. |
 
 <a id="bigquerysourceconfig"></a>
 ## BigQuerySourceConfig
@@ -2842,12 +2884,37 @@ BigQuery source configuration.
 | `project` | str |  | GCP project ID. |
 | `dataset` | str |  | BigQuery dataset name (equivalent to schema). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
+| `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `keyfile` | str | ✓ | Path to service account JSON key file. |
-| `keyfile_json` | dict[str, Any] | ✓ | Inline service account JSON dict. |
+| `keyfile_json` | dict[str, str \| int \| float \| bool] | ✓ | Inline service account JSON dict. |
 | `location` | str | ✓ | Dataset location (e.g. US, EU). |
-| `method` | enum: "oauth", "service-account", "service-account-json" | ✓ | dbt-bigquery authentication method. Inferred from keyfile/keyfile_json when omitted: 'service-account-json' if keyfile_json set, 'service-account' if keyfile set, 'oauth' (Application Default Credentials) otherwise. |
+| `method` | enum: "oauth", "oauth-secrets", "service-account", "service-account-json", "external-oauth-wif" | ✓ | dbt-bigquery authentication method. Inferred from keyfile/keyfile_json when omitted: 'service-account-json' if keyfile_json set, 'service-account' if keyfile set, 'oauth' (Application Default Credentials) otherwise. |
+| `execution_project` | str | ✓ | GCP project billed for BigQuery execution. |
+| `quota_project` | str | ✓ | GCP project used for quota attribution. |
+| `api_endpoint` | str | ✓ | BigQuery API endpoint override. |
+| `priority` | enum: "interactive", "batch" | ✓ | BigQuery job priority. |
+| `maximum_bytes_billed` | int | ✓ | Maximum bytes a BigQuery job may bill. |
+| `impersonate_service_account` | str | ✓ | Service account to impersonate for BigQuery jobs. |
+| `job_retry_deadline_seconds` | int | ✓ | Deadline in seconds for retrying a BigQuery job. |
+| `job_retries` | int | ✓ | Number of BigQuery job retry attempts (dbt accepts retries as an input alias). |
+| `job_creation_timeout_seconds` | int | ✓ | Timeout in seconds while creating a BigQuery job. |
+| `job_execution_timeout_seconds` | int | ✓ | Timeout in seconds while executing a BigQuery job. |
+| `token` | str | ✓ | OAuth access token. |
+| `refresh_token` | str | ✓ | OAuth refresh token. |
+| `client_id` | str | ✓ | OAuth client identifier. |
+| `client_secret` | str | ✓ | OAuth client secret. |
+| `token_uri` | str | ✓ | OAuth token endpoint URI. |
+| `workload_pool_provider_path` | str | ✓ | Workload identity pool provider resource path. |
+| `service_account_impersonation_url` | str | ✓ | Service-account impersonation endpoint URL. |
+| `token_endpoint` | dict[str, str] | ✓ | OAuth token endpoint configuration. |
+| `compute_region` | str | ✓ | Dataproc compute region. |
+| `dataproc_cluster_name` | str | ✓ | Dataproc cluster name. |
+| `gcs_bucket` | str | ✓ | Cloud Storage bucket for Dataproc submission. |
+| `submission_method` | str | ✓ | dbt-bigquery Dataproc submission method. |
+| `dataproc_batch` | dict[str, str \| int \| float \| bool] | ✓ | Dataproc batch configuration. |
+| `scopes` | list[str] | ✓ | OAuth scopes requested for BigQuery credentials. |
 
 <a id="redshiftsourceconfig"></a>
 ## RedshiftSourceConfig
@@ -2857,14 +2924,43 @@ Redshift source configuration.
 |-------|------|:--------:|-------------|
 | `type` | enum: "redshift" |  | Source type identifier. |
 | `host` | str |  | Redshift cluster host name. |
-| `dbname` | str |  | Redshift database name. |
-| `user` | str |  | Redshift user name. |
-| `password` | str |  | Redshift password. |
+| `dbname` | str |  | Redshift database name (dbt accepts database as an input alias). |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
+| `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `port` | int | ✓ | Redshift port number. |
 | `schema` | str | ✓ | Default schema for queries. |
+| `user` | str | ✓ | Redshift user name. Omit for IAM-based authentication when supported. |
+| `password` | str | ✓ | Redshift password. Omit for IAM-based authentication when supported. |
+| `method` | str | ✓ | Redshift authentication method. |
+| `cluster_id` | str | ✓ | Redshift cluster identifier for IAM authentication. |
+| `iam_profile` | str | ✓ | IAM profile ARN used for Redshift authentication. |
+| `autocreate` | bool | ✓ | Whether dbt may create the database user. |
+| `db_groups` | list[str] | ✓ | Redshift database groups assigned to the user. |
+| `ra3_node` | bool | ✓ | Whether the target uses Redshift RA3 nodes. |
+| `connect_timeout` | int | ✓ | Connection timeout in seconds. |
+| `role` | str | ✓ | IAM role ARN used for Redshift operations. |
+| `sslmode` | str | ✓ | SSL verification mode for the Redshift connection. |
+| `retries` | int | ✓ | Number of Redshift connection retry attempts. |
+| `retry_all` | bool | ✓ | Whether all connection errors are retried. |
+| `region` | str | ✓ | AWS region containing the Redshift target. |
+| `autocommit` | bool | ✓ | Whether Redshift statements autocommit. |
+| `access_key_id` | str | ✓ | AWS access key identifier. |
+| `secret_access_key` | str | ✓ | AWS secret access key. |
+| `idc_region` | str | ✓ | AWS IAM Identity Center region. |
+| `issuer_url` | str | ✓ | Identity-provider issuer URL. |
+| `idp_listen_port` | int | ✓ | Local port used for identity-provider callbacks. |
+| `idc_client_display_name` | str | ✓ | IAM Identity Center client display name. |
+| `idp_response_timeout` | int | ✓ | Identity-provider response timeout in seconds. |
+| `token_endpoint` | dict[str, str] | ✓ | Identity-provider token endpoint configuration. |
+| `is_serverless` | bool | ✓ | Whether the target is Redshift Serverless. |
+| `serverless_work_group` | str | ✓ | Redshift Serverless workgroup name. |
+| `serverless_acct_id` | str | ✓ | AWS account identifier for Redshift Serverless. |
+| `tcp_keepalive` | bool | ✓ | Whether TCP keepalives are enabled. |
+| `tcp_keepalive_idle` | int | ✓ | Idle seconds before TCP keepalives begin. |
+| `tcp_keepalive_interval` | int | ✓ | Seconds between TCP keepalive probes. |
+| `tcp_keepalive_count` | int | ✓ | Number of TCP keepalive probes before failure. |
 
 <a id="mysqlsourceconfig"></a>
 ## MySQLSourceConfig
@@ -2878,6 +2974,7 @@ MySQL source configuration.
 | `user` | str |  | MySQL user name. |
 | `password` | str |  | MySQL password. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
+| `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `port` | int | ✓ | MySQL port number. |
@@ -2891,10 +2988,26 @@ DuckDB source configuration.
 |-------|------|:--------:|-------------|
 | `type` | enum: "duckdb" |  | Source type identifier. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy default for every query against this source, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts them out. |
+| `max_query_duration_seconds` | int | ✓ | Maximum execution time for one query in seconds. Overrides execution.max_query_duration_seconds for this source. |
 | `lookml_path` | str | ✓ | Relative path to the directory of .lkml files backing this source's models. |
 | `models` | dict[str, [LookMLModelConfig](#lookmlmodelconfig)] | ✓ | Named LookML model collections nested under this source. |
 | `path` | str | ✓ | DuckDB file path or ':memory:' for an in-memory database. |
 | `schema` | str | ✓ | Default schema for unqualified table names (sets search_path). |
+| `duckdb_config` | dict[str, str \| int \| float \| bool] | ✓ | DuckDB connection configuration values, such as enable_external_access. |
+| `extensions` | list[str \| dict[str, str]] | ✓ | DuckDB extensions to install and load. |
+| `settings` | dict[str, str \| int \| float \| bool] | ✓ | DuckDB settings and pragma values. |
+| `secrets` | list[dict[str, str \| int \| float \| bool]] | ✓ | DuckDB secret definitions for external services. |
+| `external_root` | str | ✓ | Root path for dbt-duckdb external materializations. |
+| `use_credential_provider` | str | ✓ | Credential-provider chain used for external services. |
+| `attach` | list[DuckDBAttachmentConfig] | ✓ | Databases to attach to the DuckDB connection. |
+| `filesystems` | list[dict[str, str \| int \| float \| bool]] | ✓ | fsspec filesystem configurations attached to DuckDB. |
+| `remote` | DuckDBRemoteConfig | ✓ | Remote DuckDB connection configuration. |
+| `plugins` | list[DuckDBPluginConfig] | ✓ | dbt-duckdb plugin configurations. |
+| `disable_transactions` | bool | ✓ | Whether dbt-duckdb disables statement transactions. |
+| `keep_open` | bool | ✓ | Whether dbt-duckdb keeps its connection open. |
+| `module_paths` | list[str] | ✓ | Python module paths dbt-duckdb loads. |
+| `retries` | DuckDBRetriesConfig | ✓ | dbt-duckdb connection and query retry configuration. |
+| `is_ducklake` | bool | ✓ | Whether this source uses DuckLake. |
 
 <a id="sqlitesourceconfig"></a>
 ## SQLiteSourceConfig

dataface/agent_api/pack.py

@@ -24,7 +24,6 @@ from dataface.core.inspect.resolver import LayeredSchemaResolver
 from dataface.core.pack.models import PackProposal, ProposedDashboard
 from dataface.core.pack.planner import SourceEntry, plan_pack
 from dataface.core.pack.proposal_store import dump_proposal
-from dataface.core.project import Project
 
 if TYPE_CHECKING:
     from dataface.cli.filesystem_project import FilesystemProject
@@ -413,7 +412,7 @@ def _validate_scaffold_targets(
 
 def apply_proposal(
     proposal: PackProposal,
-    project: Project,
+    project: FilesystemProject,
     overwrite: bool = False,
 ) -> ScaffoldResult:
     """Apply an approved PackProposal, writing a sparse ``faces/`` folder tree.

dataface/agent_api/project_session.py

@@ -64,8 +64,8 @@ class ProjectSession:
     Composition roots (CLI, MCP, dft serve, Cloud, A lIe, Playground) construct
     one ProjectSession at their documented boundary and pass it (or its component
     resources) into core. Verb methods on ProjectSession are thin forwarders to
-    agent_api functions — they unpack self.project.root so callers don't
-    re-thread it at every call site.
+    agent_api functions — they unpack self.project so callers don't re-thread
+    it at every call site.
     """
 
     project: Project
@@ -206,15 +206,13 @@ class ProjectSession:
         # from_project(adapter_registry=...)) never reach here. But
         # from_project() can also be called WITHOUT an injected registry
         # against a non-filesystem Project (e.g. rendering a query-less face
-        # through an in-memory Project in tests) — that's a supported path,
-        # because build_adapter_registry only reads `.root` / `.sources` off
-        # the project, never `.data_path()`. The cast's promise only breaks
-        # if an adapter actually materializes a data file via
-        # `FilesystemProject.data_path()`, which no non-filesystem caller
-        # reaches (a non-filesystem Project has no data files to open on
-        # local disk in the first place).
+        # through an in-memory Project in tests) — that's a supported path:
+        # build_adapter_registry takes a base Project and only special-cases
+        # FilesystemProject internally (data_dir / dbt-sibling detection fall
+        # back to None for any other host), so no data file is ever
+        # materialized via a non-filesystem Project's disk.
         return build_adapter_registry(
-            cast("FilesystemProject", self.project),
+            self.project,
             read_only=self._read_only,
             profile_type=self._dialect,
             duckdb_config=self._duckdb_config,
@@ -244,7 +242,7 @@ class ProjectSession:
         # Cloud-managed sources on every refresh-driven path. Popping the
         # cached keys preserves the instance (and its class) while forcing the
         # next access to re-run each property body.
-        for key in ("config_file", "sources", "warnings_ignore"):
+        for key in ("sources", "warnings_ignore"):
             vars(self.project).pop(key, None)
 
     def close(self) -> None:
@@ -264,7 +262,11 @@ class ProjectSession:
 
     @property
     def faces_dir(self) -> Path:
-        return self.project.faces_dir
+        # ProjectSession is FS-only-meaningful here: `.open()` always builds a
+        # FilesystemProject, and this property's only caller
+        # (ai/context.py's resolve_dashboard_path) is a CLI/MCP-only path.
+        # Same reasoning as the adapter_registry cast above.
+        return cast("FilesystemProject", self.project).faces_dir
 
     @cached_property
     def _relationship_context(self) -> RelationshipContext | None:
@@ -285,14 +287,7 @@ class ProjectSession:
 
     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)
-
-    def _source_names(self) -> frozenset[str]:
-        """Return the configured source names for /data/ alias validation.
-
-        Reads from the project config file — no adapter registry or DB connection needed.
-        """
-        return frozenset(self.sources.sources.keys())
+        return _validate.annotate_with_data_lint(results, project=self.project)
 
     @overload
     def validate_query(

dataface/agent_api/search.py

@@ -240,19 +240,16 @@ def _build_index(project: Project, *, under: str) -> list[dict[str, Any]]:
             continue
         if not isinstance(content, dict):
             continue
-        title = content.get("title", PurePosixPath(pf.relpath).stem)
-        relpath = pf.relpath
-        prefix = f"{FACES_SUBDIR}/"
-        # iter_faces(under=FACES_SUBDIR) guarantees relpath starts with
-        # "faces/", but the fallback keeps face_path sane if that ever changes.
-        face_path = (
-            Path(relpath.removeprefix(prefix))
-            if relpath.startswith(prefix)
-            else Path(relpath)
+        title = content.get("title", pf.stem)
+        rel = PurePosixPath(pf.relpath)
+        # iter_faces(under=FACES_SUBDIR) guarantees relpath is under "faces/",
+        # but the fallback keeps face_path sane if that ever changes.
+        face_path = Path(
+            rel.relative_to(FACES_SUBDIR) if rel.is_relative_to(FACES_SUBDIR) else rel
         )
         entry = _index_entry_from_content(
             face_path=face_path,
-            file_path=Path(relpath),
+            file_path=Path(pf.relpath),
             title=title,
             description=content.get("description", ""),
             content=content,

dataface/agent_api/skill_install.py

@@ -49,7 +49,11 @@ class InstallSkillsResult(BaseModel):
 
 
 def skills_for_file_install() -> list[Skill]:
-    """Workflow skills exposed on the CLI surface."""
+    """Workflow skills exposed on the CLI surface.
+
+    All file-backed by construction: no ``project``/``extra_skills`` is passed,
+    so only wheel built-ins are listed.
+    """
     return sorted(
         (s for s in list_skills(surface="cli").skills if s.kind == "workflow"),
         key=lambda s: s.name,
@@ -87,6 +91,9 @@ def detect_legacy_skill_dirs(
 
 
 def _rendered_skill_md(skill: Skill) -> str:
+    # Narrowing only — skills_for_file_install lists built-ins, which always
+    # have a directory; a file-less one would raise on the `/` below anyway.
+    assert skill.directory is not None
     raw = (skill.directory / "SKILL.md").read_text(encoding="utf-8")
     if not raw.startswith("---"):
         raise ValueError(f"{skill.directory / 'SKILL.md'}: missing frontmatter")