dataface 0.2.1.dev47__py3-none-any.whl → 0.2.1.dev164__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -26,17 +26,17 @@ A successful result means your data source is reachable.
 
 ### Step 2 — Browse your schema
 
-Use `dft schema` to explore available tables and columns before writing SQL:
+Explore available tables and columns with metadata SQL before writing queries:
 
 ```bash
-dft schema                      # list configured data sources
-dft schema mydb                 # list schemas in that source
-dft schema mydb main            # list tables in that schema
-dft schema mydb main orders     # profile the orders table (columns, types, samples)
-dft schema mydb main orders id  # profile one column (distribution, sample values)
+dft query mydb "SELECT table_schema, table_name FROM INFORMATION_SCHEMA.TABLES"
+dft query mydb "SELECT column_name, data_type FROM INFORMATION_SCHEMA.COLUMNS WHERE table_name = 'orders'"
 ```
 
-Never invent column names — always verify them with `dft schema` first.
+(DuckDB also supports `DESCRIBE orders`; SQLite uses `sqlite_master` and
+`PRAGMA table_info(orders)`.)
+
+Never invent column names — always verify them against the schema first.
 
 ### Step 3 — Build one chart
 
@@ -573,7 +573,7 @@ All chart types accept the channels and style fields below — but each type rej
 | `theta` | string | Angular field (pie/donut/arc) |
 | `style.inner_radius` | float 0–1 | Donut hole ratio (hole/outer disk; pie/donut only); `type: donut` sets it to `0.6` automatically |
 | `total` | object | `{label, format}` — center total for donut |
-| `labels` | object | `{template, where}` — per-row Jinja annotations near anchors |
+| `style.marks.slice.labels` | object | `{template, where}` — per-row Jinja annotations near slice callouts |
 | `x_label` | string | X-axis title override |
 | `y_label` | string | Y-axis title override |
 | `message` | string | Static text for `type: callout` |
@@ -648,11 +648,13 @@ theta: revenue
 color: segment
 style:
   inner_radius: 0.6    # 0 = solid pie; >0 = donut (type: donut sets 0.6 by default)
+  marks:
+    slice:
+      labels:
+        template: "{{ segment }}\n{{ revenue | format(',.0f') }}"
 total:
   label: Total
   format: integer
-labels:
-  template: "{{ segment }}\n{{ revenue | format(',.0f') }}"
 
 # kpi — requires exactly 1 row; value: is a column reference
 type: kpi
@@ -1136,38 +1138,12 @@ Active code categories (see `dataface/core/errors/codes_*.py` for the authoritat
 | `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-SERVE-*` | Server startup errors (invalid theme, launch failures) |
 | `DF-UNKNOWN-*` | Fallback codes for legacy string-message errors not yet migrated |
 
-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`) or at the face level (`source: my_db` at the top of the face YAML).
-- **`DF-COMPILE-SOURCE-INLINE-FORBIDDEN`** — a query's `source:` is an inline connection dict (e.g. `{type: postgres, ...}`). Reference a named source instead (`source: my_db`); connection details live only in `dataface.yml`.
-- **`DF-COMPILE-SOURCE-CREDENTIAL-LITERAL`** — a `dataface.yml` source holds a raw secret literal in a known-secret field (`password`, `private_key`, `keyfile_json`, `token`, `secret`). `dataface.yml` is git-committed, so use `{{ env_var('SECRET_NAME') }}` or a `type: dbt_profile` source instead.
-- **`DF-COMPILE-SOURCE-CONFIG-INVALID`** — a `dataface.yml` `sources:` entry fails typed validation for its `type:` (unknown/missing field, wrong shape).
-- **`DF-COMPILE-SOURCE-NOT-FOUND`** — a query's `source:` names a source that is not in the loaded registry. Check for a typo, or declare the source under `sources:` 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-WRONG-SHAPE`** — a YAML field that expects a mapping (nested block) received a scalar or sequence instead. The error hint lists the available keys. For example, `axis_x.label: "hi"` must be a mapping: `axis_x:\n  label:\n    angle: -45`.
-- **`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.
-- **`DF-EXECUTE-SOURCE-INVALID-TYPE`** / **`-MISSING-TYPE`** — a source definition has an unknown or missing `type:` field.
+The registry is being filled out incrementally — some compile-time and variable-resolution errors still raise as plain `DatafaceError` without a structured code.
 
-Run `dft validate <face>` to validate a face and see structured error details.
+Run `dft docs error-reference` for the full generated reference — every registered code, its message template, and its docs pointer, straight from `dataface.core.errors.REGISTRY`. Run `dft validate <face>` to validate a face and see structured error details.
 
 **See also:** `dft docs queries`, `dft docs charts`, `dft docs variables` (where most errors originate),
 `dft docs all` (whole reference for context).

dataface/__init__.py

@@ -22,8 +22,8 @@ Quick Start:
     ...     face = result.face
     ...
     ...     # Create executor and render
-    ...     from dataface.core.project import Project
-    ...     registry = build_adapter_registry(Project(Path.cwd()))
+    ...     from dataface.core.project import FilesystemProject
+    ...     registry = build_adapter_registry(FilesystemProject(Path.cwd()))
     ...     executor = Executor(face, registry, query_registry=result.query_registry)
     ...     svg = render(face, executor, format="svg")
 """

dataface/agent_api/dashboards.py

@@ -13,10 +13,14 @@ from typing import Any, Literal
 import yaml
 from pydantic import BaseModel, ConfigDict, Field, field_serializer
 
-from dataface.agent_api._paths import resolve_scoped_path
+from dataface.agent_api._paths import no_project_hint, resolve_scoped_path
 from dataface.core.compile import Face, compile_file
 from dataface.core.dashboard import RenderedDashboard as RenderedDashboard
-from dataface.core.errors import DF_UNKNOWN_INTERNAL, StructuredError
+from dataface.core.errors import (
+    DF_COMPILE_FILE_NOT_FOUND,
+    DF_UNKNOWN_INTERNAL,
+    StructuredError,
+)
 from dataface.core.errors.base import DatafaceError
 from dataface.core.project import FACES_SUBDIR, Project, ProjectPath
 from dataface.core.warnings.base import RenderWarning
@@ -89,9 +93,6 @@ class RenderDashboardArgs(BaseModel):
     yaml_content: str | None = Field(
         None, description="YAML content to render directly (use this OR path)"
     )
-    project_dir: Path | None = Field(
-        None, description="Project root for resolving relative paths"
-    )
     variables: dict[str, Any] | None = Field(
         None, description="Variable values to apply to the dashboard"
     )
@@ -190,12 +191,14 @@ def get_dashboard(
         )
 
     if not file_path.exists():
+        hint = no_project_hint(project.root)
         return CompiledDashboard(
             success=False,
             errors=[
                 DatafaceError.from_code(
-                    DF_UNKNOWN_INTERNAL,
-                    message=f"File not found: {path}",
+                    DF_COMPILE_FILE_NOT_FOUND,
+                    path=str(file_path),
+                    hint=hint,
                 ).to_structured(file=str(file_path))
             ],
         )

dataface/agent_api/data_paths.py

@@ -1,107 +1,16 @@
-"""Data URL surfacing and alias typo lint.
-
-Provides:
-- DataPathInfo: the agent-facing wire shape for a canonical data URL
-  (url, resolves_to: "generic" | "authored", face)
-- data_paths_for_source/schema/table: compute data URLs and check the
-  alias index to determine whether a face overrides the generic system view
-- data_paths_list: flat list of DataPathInfo (source + schema + table level)
-  from a SchemaResponse — used for --data-paths CLI flag and agent discovery
-- validate_data_aliases: typo lint for /data/ prefixed aliases — checks
-  source names only (config only, no DB connection required).
+"""Data-alias typo lint for /data/ prefixed face aliases.
+
+Checks source names only (config only, no DB connection required) — called
+from the validate path, which must stay connection-free.
 """
 
 from __future__ import annotations
 
-from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal
-
-from dataface.core.registered_views.data_urls import (
-    data_schema_url,
-    data_source_url,
-    data_table_url,
-)
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from dataface.agent_api.schema import SchemaResponse
     from dataface.core.project import Project
-    from dataface.core.serve.alias_index import AliasIndex
-
-
-@dataclass
-class DataPathInfo:
-    """Canonical data URL with resolution status.
-
-    Wire shape (pinned by contract test — any change is a breaking API change):
-        {"url": "/data/src/schema/table/", "resolves_to": "generic"}
-        {"url": "...", "resolves_to": "authored", "face": "/sales/"}
-    """
-
-    url: str
-    resolves_to: Literal["generic", "authored"]
-    face: str | None = None
-
-    def to_dict(self) -> dict[str, Any]:
-        """Serialize to the agent wire shape, omitting face when generic."""
-        d: dict[str, Any] = {"url": self.url, "resolves_to": self.resolves_to}
-        if self.face is not None:
-            d["face"] = self.face
-        return d
-
-
-def data_paths_for_source(
-    source: str,
-    *,
-    alias_index: AliasIndex,
-) -> DataPathInfo:
-    """Return the data URL info for a source.
-
-    The canonical URL is /data/<source>/. When a face aliases it the
-    resolves_to is 'authored' and face is the canonical face URL.
-    """
-    url = data_source_url(source)
-    face = alias_index.lookup(url)
-    if face is not None:
-        return DataPathInfo(url=url, resolves_to="authored", face=face)
-    return DataPathInfo(url=url, resolves_to="generic")
-
-
-def data_paths_for_schema(
-    source: str,
-    schema: str,
-    *,
-    alias_index: AliasIndex,
-) -> DataPathInfo:
-    """Return the data URL info for a schema.
-
-    The canonical URL is /data/<source>/<schema>/. When a face aliases it
-    the resolves_to is 'authored' and face is the canonical face URL.
-    """
-    url = data_schema_url(source, schema)
-    face = alias_index.lookup(url)
-    if face is not None:
-        return DataPathInfo(url=url, resolves_to="authored", face=face)
-    return DataPathInfo(url=url, resolves_to="generic")
-
-
-def data_paths_for_table(
-    source: str,
-    schema: str,
-    table: str,
-    *,
-    alias_index: AliasIndex,
-) -> DataPathInfo:
-    """Return the data URL info for a table.
-
-    The canonical URL is /data/<source>/<schema>/<table>/. When a face
-    aliases it the resolves_to is 'authored' and face is the canonical face URL.
-    """
-    url = data_table_url(source, schema, table)
-    face = alias_index.lookup(url)
-    if face is not None:
-        return DataPathInfo(url=url, resolves_to="authored", face=face)
-    return DataPathInfo(url=url, resolves_to="generic")
 
 
 def validate_data_aliases(
@@ -157,47 +66,6 @@ def validate_data_aliases(
     return errors
 
 
-def data_paths_list(
-    schema_response: SchemaResponse,
-    *,
-    alias_index: AliasIndex,
-) -> list[DataPathInfo]:
-    """Build a flat list of DataPathInfo from a SchemaResponse.
-
-    Iterates all sources → schemas → tables in the response and returns one
-    DataPathInfo per source, per schema, and per table, checking the alias
-    index for author overrides at each level.
-    """
-    result: list[DataPathInfo] = []
-    for source_name, source_data in schema_response.sources.items():
-        result.append(data_paths_for_source(source_name, alias_index=alias_index))
-        for schema_name, schema_data in (source_data.get("schemas") or {}).items():
-            result.append(
-                data_paths_for_schema(source_name, schema_name, alias_index=alias_index)
-            )
-            for table_name in schema_data.get("tables") or {}:
-                result.append(
-                    data_paths_for_table(
-                        source_name,
-                        schema_name,
-                        table_name,
-                        alias_index=alias_index,
-                    )
-                )
-    return result
-
-
-def build_alias_index_for_project(project: Project) -> AliasIndex:
-    """Build an AliasIndex from a project.
-
-    Intended for CLI commands (dft schema --data-paths) that need alias lookup
-    without starting a server.
-    """
-    from dataface.core.serve.alias_index import AliasIndex
-
-    return AliasIndex.build(project)
-
-
 def data_alias_errors_for_file(
     face_file: Path,
     source_names: frozenset[str],

dataface/agent_api/describe.py

@@ -18,7 +18,11 @@ from dataface.core.compile.models.query.normalized import (
     SqlQuery,
     ValuesQuery,
 )
-from dataface.core.errors import DF_UNKNOWN_INTERNAL, StructuredError
+from dataface.core.errors import (
+    DF_COMPILE_FILE_NOT_FOUND,
+    DF_UNKNOWN_INTERNAL,
+    StructuredError,
+)
 from dataface.core.project import Project
 
 # Chart-encoding fields surfaced to agents. Covers the stable channel fields
@@ -90,13 +94,6 @@ class DescribeFaceArgs(BaseModel):
     """Describe the structure of a face file: queries (with type and source), charts (with query bindings and encoding), variables, and layout. Use this for orientation when picking up an unfamiliar dashboard — it reads the YAML and returns a curated narrative summary without executing any queries."""
 
     path: Path = Field(description="Path to the dashboard YAML file to describe")
-    project_dir: Path | None = Field(
-        default=None,
-        description=(
-            "Project root for resolving relative paths. Optional on the wire; "
-            "the MCP server injects the project root when omitted."
-        ),
-    )
 
 
 class DescribeFaceResult(BaseModel):
@@ -208,15 +205,16 @@ def describe_face(path: Path, *, project: Project) -> DescribeFaceResult:
             ],
         )
 
-    if not resolved.exists():
+    if not project.path_for_fspath(resolved).exists():
         hint = no_project_hint(project.root)
         return DescribeFaceResult(
             success=False,
             path=path,
             errors=[
                 DatafaceError.from_code(
-                    DF_UNKNOWN_INTERNAL,
-                    message=f"File not found: {resolved}{hint}",
+                    DF_COMPILE_FILE_NOT_FOUND,
+                    path=str(resolved),
+                    hint=hint,
                 ).to_structured()
             ],
         )

dataface/agent_api/docs/_loader.py

@@ -5,6 +5,8 @@ are slugified headings. Bare `docs()` returns the topic index (slug + one-line
 description per H2). `docs(topic="<slug>")` returns one slice.
 `docs(topic="all")` returns the whole file. `docs(topic="reference")` returns
 the auto-generated field spec from yaml-reference.md.
+`docs(topic="error-reference")` returns the auto-generated error reference from
+error-reference.md.
 `docs(search=...)` substring-matches across topics.
 """
 
@@ -25,9 +27,15 @@ _REFERENCE_FILE = (
     importlib.resources.files("dataface.agent_api.docs") / "yaml-reference.md"
 )
 
+# Generated error reference ships inside the wheel at dataface/agent_api/docs/error-reference.md.
+_ERROR_REFERENCE_FILE = (
+    importlib.resources.files("dataface.agent_api.docs") / "error-reference.md"
+)
+
 _TOPIC_RE = re.compile(r"^[a-z0-9-]+$")
 _ALL_TOPIC = "all"
 _REFERENCE_TOPIC = "reference"
+_ERROR_REFERENCE_TOPIC = "error-reference"
 
 DocsMode = Literal["index", "topic", "search"]
 
@@ -68,7 +76,7 @@ class DocsArgs(BaseModel):
 
     topic: str | None = Field(
         None,
-        description="Topic slug from the `dft docs` topic index (e.g. 'face', 'charts', 'all', 'reference')",
+        description="Topic slug from the `dft docs` topic index (e.g. 'face', 'charts', 'all', 'reference', 'error-reference')",
     )
     search: str | None = Field(
         None, description="Full-text query — runs substring search across all topics"
@@ -101,6 +109,7 @@ def docs(
     - ``docs(topic="face")`` — return content for one H2 section.
     - ``docs(topic="all")`` — return the full ``DATAFACE_SYNTAX.md`` unsliced.
     - ``docs(topic="reference")`` — return the auto-generated field spec.
+    - ``docs(topic="error-reference")`` — return the auto-generated error reference.
     - ``docs(search="grid")`` — substring search across H2 sections.
     """
     if topic is not None and search is not None:
@@ -145,6 +154,24 @@ def docs(
             ),
         )
 
+    if topic == _ERROR_REFERENCE_TOPIC:
+        try:
+            content = _ERROR_REFERENCE_FILE.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return DocsResult(
+                success=False,
+                mode="topic",
+                errors=["error-reference.md is missing from the installed package."],
+            )
+        return DocsResult(
+            mode="topic",
+            topic=Topic(
+                id=_ERROR_REFERENCE_TOPIC,
+                title="Dataface Error Reference (generated)",
+                content=content,
+            ),
+        )
+
     if not _TOPIC_RE.fullmatch(topic):
         return DocsResult(
             success=False,

dataface/agent_api/docs/yaml-reference.md

@@ -348,7 +348,6 @@ Authored patch for pie and donut charts.
 | `subtitle` | str | ✓ | Chart subtitle displayed below the title. |
 | `color` | str | ✓ | Color data channel: bare column name only. |
 | `total` | [ChartTotal](#charttotal) | ✓ | Donut center total. |
-| `labels` | [ChartLabels](#chartlabels) | ✓ | Per-row text annotations near each data anchor. |
 | `style` | [PieChartStyle](#piechartstyle) | ✓ | Chart-local style overrides. |
 
 <a id="kpichart"></a>
@@ -805,15 +804,6 @@ Donut center total — auto-rendered sum at the center of a donut, with author o
 | `label` | str | ✓ | Caption text displayed below the center total value. |
 | `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format (D3 spec, preset, or FormatConfig). |
 
-<a id="chartlabels"></a>
-## ChartLabels
-Per-row text annotations rendered near each data anchor.
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `template` | str |  | Jinja2 template for the label text. Row fields are available as variables. |
-| `where` | str | ✓ | Jinja2 boolean filter expression. Labels only render on rows where this is truthy. |
-
 <a id="piechartstyle"></a>
 ## PieChartStyle
 Authored overlay for PieChartStyle. Pie/donut chart style: geometry + total (flat) + marks sub-block.
@@ -1290,6 +1280,7 @@ Authored overlay for FooterStyle. Page footer chrome: visibility, attribution te
 |-------|------|:--------:|-------------|
 | `visible` | bool | ✓ | Show the footer attribution line. |
 | `text` | str | ✓ | Attribution text shown in the footer. |
+| `link` | str | ✓ | URL the footer brand word 'dataface' links to; null renders plain text. |
 | `font` | [FontStyle](#fontstyle) | ✓ | Footer text font style (size and color required). |
 | `y_offset` | float | ✓ | Vertical offset from bottom edge in pixels. |
 | `rule` | [FooterRule](#footerrule) | ✓ | Hairline rule above footer text; null disables the rule. |
@@ -1451,7 +1442,7 @@ Authored overlay for AxisStyle.
 | `title` | [AxisElementStyle](#axiselementstyle) | ✓ | Axis title style. |
 | `position` | enum: "left", "right", "top", "bottom", "auto" | ✓ | Axis position; auto flips y-axis when endpoint labels are present. |
 | `categorical_orient` | str | ✓ | Orientation for categorical y-axis (e.g. 'left'); None skips this VL property. |
-| `mirror` | bool | ✓ | Draw the y-scale on both left and right edges (wide charts). Only meaningful on axis_y. |
+| `mirror` | bool \| [AxisMirrorStyle](#axismirrorstyle) | ✓ | Draw the y-scale on both left and right edges (wide charts). true mirrors the primary axis's label verbatim; an object (format/expr) relabels only the mirrored edge — e.g. a percent-of-total right axis next to an absolute-value left axis — while ticks stay aligned to the single shared scale. Only meaningful on axis_y. |
 | `band_position` | float | ✓ | Band position within the step (0–1); None uses Vega-Lite's default. |
 | `offset` | float | ✓ | Pixel offset of the axis from its default position; None means no offset. |
 | `format` | str | ✓ | Tick value format string; None uses auto-format. |
@@ -1480,8 +1471,8 @@ Authored overlay for ScaleStyle. Scale configuration primitive.
 | `quantize_count` | int | ✓ | Number of quantize buckets; None uses Vega-Lite's default. |
 | `use_unaggregated_domain` | bool | ✓ | Use unaggregated domain for scale extent; None uses Vega-Lite's default. |
 | `x_reverse` | bool | ✓ | Reverse the x-axis scale direction; None means no reversal. |
-| `type` | str | ✓ | Scale type override; None lets Vega-Lite infer from field type. |
-| `domain` | list[Any] | ✓ | Explicit scale domain values; None lets Vega-Lite auto-determine from data. |
+| `type` | enum: "linear", "log", "pow", "sqrt", "symlog", "temporal" | ✓ | Scale type override. 'linear'/'log'/'pow'/'sqrt'/'symlog' pass straight through to Vega-Lite's quantitative scale.type. 'temporal' is a Dataface escape hatch for a cartesian x-axis: it forces a continuous temporal scale instead of the auto-inferred ordinal/nominal bucketed type, which is required before an authored ``domain`` of ISO dates can extend the visible range past the data extent. None lets Dataface/Vega-Lite infer from the field type. |
+| `domain` | list[Any] | ✓ | Explicit [low, high] scale domain; None lets Vega-Lite auto-determine from data. Must have exactly 2 elements — Dataface only wires a continuous range override through to Vega-Lite, not an explicit category enumeration. When ``type: temporal`` is set, both elements must be ISO-8601 date/datetime strings. |
 | `nice` | bool | ✓ | Round scale domain to nice values; None uses Vega-Lite's default. |
 | `padding` | float | ✓ | Unified scale padding shortcut; dispatches to band, point, or continuous padding per scale type. |
 
@@ -2205,7 +2196,7 @@ Authored overlay for AxisTicksStyle.
 | `color` | str | ✓ | Tick color; None uses Vega-Lite's default. |
 | `size` | float | ✓ | Tick length in pixels; None uses Vega-Lite's default. |
 | `width` | float | ✓ | Tick stroke width in pixels; None uses Vega-Lite's default. |
-| `count` | int | ✓ | Target number of quantitative y-axis ticks. When set, the renderer computes explicit tickValues so VL emits exactly this many ticks — VL's tickCount is advisory and frequently ignored. |
+| `count` | int | ✓ | Target number of axis ticks. On a quantitative axis the renderer computes explicit tickValues so VL emits exactly this many ticks — VL's tickCount is advisory and frequently ignored there. On a temporal axis_x, count is passed through as VL's axis.tickCount, which VL's time-scale tick logic honours as a target. |
 
 <a id="axiselementstyle"></a>
 ## AxisElementStyle
@@ -2231,6 +2222,15 @@ Authored overlay for AxisElementStyle. Axis label or title: font + padding + VL-
 | `anchor` | enum: "start", "middle", "end" | ✓ | Label anchor position; None uses Vega-Lite's default. |
 | `tilt_increments` | list[float] | ✓ | Descending tilt angles for smart label overlap on discrete x-axes; None disables the picker. |
 
+<a id="axismirrorstyle"></a>
+## AxisMirrorStyle
+Per-edge label override for the mirrored ``axis_y.mirror`` ghost axis.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `format` | str | ✓ | Tick value format string for the mirrored edge; None reuses the primary axis's format. |
+| `expr` | str | ✓ | Custom Vega expression for the mirrored edge's label text; None reuses the primary axis's label expression. |
+
 <a id="scalebandstyle"></a>
 ## ScaleBandStyle
 Authored overlay for ScaleBandStyle. Band mark size constraints (min/max pixel width for band-scale marks).
@@ -2645,7 +2645,9 @@ Authored overlay for SliceLabelsStyle. Pie labels: typography + positioning offs
 | `offset` | float | ✓ | Radial offset of slice labels from the arc in pixels. |
 | `line_height` | float | ✓ | Line height for slice labels in pixels. Reserved vertical space above the disk is ``line_height × &lt;rendered lines&gt;`` per row, so the same value handles 1-line, 2-line, and multi-line templates. |
 | `font` | [FontStyle](#fontstyle) | ✓ | Slice label font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
-| `default_template` | [LabelsDefaultTemplate](#labelsdefaulttemplate) | ✓ | Default Jinja templates for per-slice labels when the chart author omits ``labels:`` on a pie/donut. |
+| `default_template` | [LabelsDefaultTemplate](#labelsdefaulttemplate) | ✓ | Default Jinja templates for per-slice labels when template is not authored. |
+| `template` | str | ✓ | Jinja2 label template. Overrides default_template when authored. |
+| `where` | str | ✓ | Jinja2 boolean filter — labels only render on rows where this is truthy. |
 
 <a id="tablerowrolestyle"></a>
 ## TableRowRoleStyle