dataspring-cli 0.3.0__py3-none-any.whl

cli/generated.py

@@ -0,0 +1,1297 @@
+"""GENERATED by `python -m services.cli_generate`; do not edit.
+
+The dispatch registry as Typer commands (decision D19, step 4): one
+command per flat tool (``dataspring <key> --<field> ...``) and one group
+per edit family (``dataspring <key> <verb> --<field> ...``), each flag a
+field of the entry's model in ``cli/contract.py``, help text the models'
+own. ``services/cli_generate.py`` is the generator and the only place that
+knows how a model becomes a command; ``tests/test_cli_generated.py``
+asserts this file equals its output. ``cli/runtime.py`` is what every
+command calls: the body from the flags (and ``--from-file``), validated
+against the model, the manifest skew hint, ``POST /api/dispatch/<key>``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from cli import contract
+from cli.runtime import J, run_tool
+
+FromFile = Annotated[
+    Optional[Path],
+    typer.Option("--from-file", help="A YAML or JSON file holding the fields; flags given on the command line override its keys"),
+]
+Output = Annotated[
+    Optional[Path],
+    typer.Option("--output", "-o", help="Write the answer's document (`content`) or rendered file (`data_base64`) here instead of printing the JSON answer"),
+]
+
+#: The contract model of every registry key, for the alias layer and the tests.
+MODELS: dict[str, type[contract.DispatchParams]] = {
+    'dashboard_edit': contract.DashboardEditParams,
+    'widget_edit': contract.WidgetEditParams,
+    'page_edit': contract.PageEditParams,
+    'section_edit': contract.SectionEditParams,
+    'business_context_edit': contract.BusinessContextEditParams,
+    'semantic_model_edit': contract.SemanticModelEditParams,
+    'metric_edit': contract.MetricEditParams,
+    'quick_metric_edit': contract.QuickMetricEditParams,
+    'report_edit': contract.ReportEditParams,
+    'learned_edit': contract.LearnedEditParams,
+    'verified_query_edit': contract.VerifiedQueryEditParams,
+    'warehouse_edit': contract.WarehouseEditParams,
+    'query_metrics': contract.QueryMetricsParams,
+    'explain_query': contract.ExplainQueryParams,
+    'update_context': contract.UpdateContextParams,
+    'export_data': contract.ExportDataParams,
+    'import_manifest': contract.ImportManifestParams,
+    'render_dashboard': contract.RenderDashboardParams,
+    'render_widget': contract.RenderWidgetParams,
+    'switch_organization': contract.SwitchOrganizationParams,
+    'submit_error_report': contract.SubmitErrorReportParams,
+    'secret_edit': contract.SecretEditParams,
+    'run_sql': contract.RunSqlParams,
+    'datacore_edit': contract.DatacoreEditParams,
+    'datacore_run': contract.DatacoreRunParams,
+}
+
+#: The verbs of every edit family, in the order the action union declares them.
+VERBS: dict[str, tuple[str, ...]] = {
+    'dashboard_edit': ('create', 'update', 'delete', 'duplicate', 'share', 'set_controls'),
+    'widget_edit': ('add', 'update', 'remove', 'reorder', 'move', 'copy', 'swap'),
+    'page_edit': ('create', 'delete', 'rename', 'reorder'),
+    'section_edit': ('create', 'delete', 'rename', 'move'),
+    'business_context_edit': ('get', 'show_size', 'set', 'append'),
+    'semantic_model_edit': ('create', 'update', 'delete', 'preview'),
+    'metric_edit': ('create', 'update', 'delete', 'preview', 'impact'),
+    'quick_metric_edit': ('create', 'update', 'delete'),
+    'report_edit': ('create', 'update', 'delete'),
+    'learned_edit': ('list', 'undo'),
+    'verified_query_edit': ('list', 'record', 'delete'),
+    'warehouse_edit': ('activate', 'add_external', 'remove'),
+    'secret_edit': ('set', 'reveal'),
+    'datacore_edit': ('apply', 'patch', 'delete'),
+    'datacore_run': ('check', 'deploy', 'run', 'reset'),
+}
+
+
+# ---------------------------------------------------------------------------
+# dashboard_edit
+# ---------------------------------------------------------------------------
+
+
+dashboard_edit = typer.Typer(name='dashboard_edit', help='Edit dashboards via a single dispatch tool with a discriminated action.', no_args_is_help=True)
+
+
+@dashboard_edit.command('create', short_help='Create a new dashboard.')
+def dashboard_edit__create(
+    title: Annotated[str, typer.Option('--title', help='Dashboard title')],
+    description: Annotated[Optional[str], typer.Option('--description', help='Optional description')] = None,
+    visibility: Annotated[Optional[str], typer.Option('--visibility', help='"private" (only you) or "org" (shared with organization) (one of: private, org) (default: private)')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Create a new dashboard."""
+    run_tool('dashboard_edit', contract.DashboardEditParams, 'create', {'title': title, 'description': description, 'visibility': visibility}, from_file=from_file, output=output)
+
+
+@dashboard_edit.command('update', short_help="Update an existing dashboard's metadata (title/description/visibility).")
+def dashboard_edit__update(
+    id: Annotated[str, typer.Option('--id', help='Dashboard ID')],
+    title: Annotated[Optional[str], typer.Option('--title', help='title')] = None,
+    description: Annotated[Optional[str], typer.Option('--description', help='description')] = None,
+    visibility: Annotated[Optional[str], typer.Option('--visibility', help='visibility (one of: private, org)')] = None,
+    expected_version: Annotated[Optional[int], typer.Option('--expected-version', help='Optimistic lock — if provided, update fails on mismatch. Use the version from get_dashboard to prevent overwriting concurrent changes.')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Update an existing dashboard's metadata (title/description/visibility)."""
+    run_tool('dashboard_edit', contract.DashboardEditParams, 'update', {'id': id, 'title': title, 'description': description, 'visibility': visibility, 'expected_version': expected_version}, from_file=from_file, output=output)
+
+
+@dashboard_edit.command('delete', short_help='Delete a dashboard. Cannot be undone.')
+def dashboard_edit__delete(
+    id: Annotated[str, typer.Option('--id', help='Dashboard ID')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Delete a dashboard. Cannot be undone."""
+    run_tool('dashboard_edit', contract.DashboardEditParams, 'delete', {'id': id}, from_file=from_file, output=output)
+
+
+@dashboard_edit.command('duplicate', short_help='Duplicate a dashboard with all pages, sections, and widgets (new IDs).')
+def dashboard_edit__duplicate(
+    id: Annotated[str, typer.Option('--id', help='Source dashboard ID')],
+    new_title: Annotated[Optional[str], typer.Option('--new-title', help='Title for the copy (default: "Copy of {original}")')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Duplicate a dashboard with all pages, sections, and widgets (new IDs)."""
+    run_tool('dashboard_edit', contract.DashboardEditParams, 'duplicate', {'id': id, 'new_title': new_title}, from_file=from_file, output=output)
+
+
+@dashboard_edit.command('share', short_help='Toggle dashboard visibility between private and shared (org).')
+def dashboard_edit__share(
+    id: Annotated[str, typer.Option('--id', help='Dashboard ID')],
+    visibility: Annotated[str, typer.Option('--visibility', help='visibility (one of: private, org)')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Toggle dashboard visibility between private and shared (org)."""
+    run_tool('dashboard_edit', contract.DashboardEditParams, 'share', {'id': id, 'visibility': visibility}, from_file=from_file, output=output)
+
+
+@dashboard_edit.command('set_controls', short_help="Update a dashboard's date-range, grain, and comparison controls.")
+def dashboard_edit__set_controls(
+    id: Annotated[str, typer.Option('--id', help='Dashboard ID')],
+    date_range: Annotated[Optional[str], typer.Option('--date-range-json', help='Date range config. Relative: {"mode": "relative", "preset": "last_30_days"}. Absolute: {"mode": "absolute", "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD"}. (JSON, or @path to a .json/.yaml file)')] = None,
+    grain: Annotated[Optional[str], typer.Option('--grain', help='grain (one of: day, week, month, quarter, year)')] = None,
+    comparison: Annotated[Optional[str], typer.Option('--comparison', help='comparison (one of: none, previous_period, same_period_last_year)')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Update a dashboard's date-range, grain, and comparison controls."""
+    run_tool('dashboard_edit', contract.DashboardEditParams, 'set_controls', {'id': id, 'date_range': J(date_range), 'grain': grain, 'comparison': comparison}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# widget_edit
+# ---------------------------------------------------------------------------
+
+
+widget_edit = typer.Typer(name='widget_edit', help='Edit dashboard widgets via a single dispatch tool.', no_args_is_help=True)
+
+
+@widget_edit.command('add', short_help='Add a widget to a dashboard section.')
+def widget_edit__add(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    widget: Annotated[Optional[str], typer.Option('--widget-json', help='Widget definition. Required: type (kpi|area_chart|bar_chart|line_chart|table|donut|heatmap), title, query. Optional: format, width (1-10), time_scope (range|latest|latest_complete), pivot (for table widgets). (JSON, or @path to a .json/.yaml file)')],
+    page_index: Annotated[Optional[int], typer.Option('--page-index', help='page index (default: 0)')] = None,
+    section_index: Annotated[Optional[int], typer.Option('--section-index', help='section index (default: 0)')] = None,
+    expected_version: Annotated[Optional[int], typer.Option('--expected-version', help='expected version')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Add a widget to a dashboard section."""
+    run_tool('widget_edit', contract.WidgetEditParams, 'add', {'dashboard_id': dashboard_id, 'widget': J(widget), 'page_index': page_index, 'section_index': section_index, 'expected_version': expected_version}, from_file=from_file, output=output)
+
+
+@widget_edit.command('update', short_help="Update a widget's fields (title, type, query, format, width, time_scope, pivot).")
+def widget_edit__update(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    page_index: Annotated[int, typer.Option('--page-index', help='page index')],
+    section_index: Annotated[int, typer.Option('--section-index', help='section index')],
+    widget_index: Annotated[int, typer.Option('--widget-index', help='widget index')],
+    updates: Annotated[Optional[str], typer.Option('--updates-json', help='Fields to patch — only provided keys are changed (JSON, or @path to a .json/.yaml file)')],
+    expected_version: Annotated[Optional[int], typer.Option('--expected-version', help='expected version')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Update a widget's fields (title, type, query, format, width, time_scope, pivot)."""
+    run_tool('widget_edit', contract.WidgetEditParams, 'update', {'dashboard_id': dashboard_id, 'page_index': page_index, 'section_index': section_index, 'widget_index': widget_index, 'updates': J(updates), 'expected_version': expected_version}, from_file=from_file, output=output)
+
+
+@widget_edit.command('remove', short_help='Remove a widget from a dashboard section (irreversible).')
+def widget_edit__remove(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    page_index: Annotated[int, typer.Option('--page-index', help='page index')],
+    section_index: Annotated[int, typer.Option('--section-index', help='section index')],
+    widget_index: Annotated[int, typer.Option('--widget-index', help='widget index')],
+    expected_version: Annotated[Optional[int], typer.Option('--expected-version', help='expected version')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Remove a widget from a dashboard section (irreversible)."""
+    run_tool('widget_edit', contract.WidgetEditParams, 'remove', {'dashboard_id': dashboard_id, 'page_index': page_index, 'section_index': section_index, 'widget_index': widget_index, 'expected_version': expected_version}, from_file=from_file, output=output)
+
+
+@widget_edit.command('reorder', short_help='Reorder widgets within a section. All widget IDs in the section must be listed.')
+def widget_edit__reorder(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    page_index: Annotated[int, typer.Option('--page-index', help='page index')],
+    section_index: Annotated[int, typer.Option('--section-index', help='section index')],
+    widget_ids: Annotated[list[str], typer.Option('--widget-ids', help='Full list of widget IDs in desired order')],
+    expected_version: Annotated[Optional[int], typer.Option('--expected-version', help='expected version')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Reorder widgets within a section. All widget IDs in the section must be listed."""
+    run_tool('widget_edit', contract.WidgetEditParams, 'reorder', {'dashboard_id': dashboard_id, 'page_index': page_index, 'section_index': section_index, 'widget_ids': widget_ids, 'expected_version': expected_version}, from_file=from_file, output=output)
+
+
+@widget_edit.command('move', short_help='Move a widget to a different page/section (keeps the same ID).')
+def widget_edit__move(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    widget_id: Annotated[str, typer.Option('--widget-id', help='widget id')],
+    target_page_id: Annotated[str, typer.Option('--target-page-id', help='target page id')],
+    target_section_index: Annotated[int, typer.Option('--target-section-index', help='target section index')],
+    position: Annotated[Optional[int], typer.Option('--position', help='Position within target section (None = append)')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Move a widget to a different page/section (keeps the same ID)."""
+    run_tool('widget_edit', contract.WidgetEditParams, 'move', {'dashboard_id': dashboard_id, 'widget_id': widget_id, 'target_page_id': target_page_id, 'target_section_index': target_section_index, 'position': position}, from_file=from_file, output=output)
+
+
+@widget_edit.command('copy', short_help='Copy a widget with a new ID.')
+def widget_edit__copy(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    widget_id: Annotated[str, typer.Option('--widget-id', help='widget id')],
+    target_page_id: Annotated[str, typer.Option('--target-page-id', help='target page id')],
+    target_section_index: Annotated[int, typer.Option('--target-section-index', help='target section index')],
+    new_title: Annotated[Optional[str], typer.Option('--new-title', help='new title')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Copy a widget with a new ID."""
+    run_tool('widget_edit', contract.WidgetEditParams, 'copy', {'dashboard_id': dashboard_id, 'widget_id': widget_id, 'target_page_id': target_page_id, 'target_section_index': target_section_index, 'new_title': new_title}, from_file=from_file, output=output)
+
+
+@widget_edit.command('swap', short_help='Swap the positions of two widgets (may be in different sections).')
+def widget_edit__swap(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    widget_id_1: Annotated[str, typer.Option('--widget-id-1', help='widget id 1')],
+    widget_id_2: Annotated[str, typer.Option('--widget-id-2', help='widget id 2')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Swap the positions of two widgets (may be in different sections)."""
+    run_tool('widget_edit', contract.WidgetEditParams, 'swap', {'dashboard_id': dashboard_id, 'widget_id_1': widget_id_1, 'widget_id_2': widget_id_2}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# page_edit
+# ---------------------------------------------------------------------------
+
+
+page_edit = typer.Typer(name='page_edit', help='Edit dashboard pages via a single dispatch tool.', no_args_is_help=True)
+
+
+@page_edit.command('create', short_help='`page_edit` create.')
+def page_edit__create(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    title: Annotated[str, typer.Option('--title', help='title')],
+    position: Annotated[Optional[int], typer.Option('--position', help='Insert position (None = append)')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`page_edit` create."""
+    run_tool('page_edit', contract.PageEditParams, 'create', {'dashboard_id': dashboard_id, 'title': title, 'position': position}, from_file=from_file, output=output)
+
+
+@page_edit.command('delete', short_help='`page_edit` delete.')
+def page_edit__delete(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    page_id: Annotated[str, typer.Option('--page-id', help='page id')],
+    cascade: Annotated[Optional[bool], typer.Option('--cascade/--no-cascade', help='Delete even if page has widgets')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`page_edit` delete."""
+    run_tool('page_edit', contract.PageEditParams, 'delete', {'dashboard_id': dashboard_id, 'page_id': page_id, 'cascade': cascade}, from_file=from_file, output=output)
+
+
+@page_edit.command('rename', short_help='`page_edit` rename.')
+def page_edit__rename(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    page_id: Annotated[str, typer.Option('--page-id', help='page id')],
+    title: Annotated[str, typer.Option('--title', help='title')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`page_edit` rename."""
+    run_tool('page_edit', contract.PageEditParams, 'rename', {'dashboard_id': dashboard_id, 'page_id': page_id, 'title': title}, from_file=from_file, output=output)
+
+
+@page_edit.command('reorder', short_help='`page_edit` reorder.')
+def page_edit__reorder(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    page_ids: Annotated[list[str], typer.Option('--page-ids', help='Full list of page IDs in desired order')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`page_edit` reorder."""
+    run_tool('page_edit', contract.PageEditParams, 'reorder', {'dashboard_id': dashboard_id, 'page_ids': page_ids}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# section_edit
+# ---------------------------------------------------------------------------
+
+
+section_edit = typer.Typer(name='section_edit', help='Edit dashboard sections via a single dispatch tool.', no_args_is_help=True)
+
+
+@section_edit.command('create', short_help='`section_edit` create.')
+def section_edit__create(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    page_id: Annotated[str, typer.Option('--page-id', help='page id')],
+    title: Annotated[Optional[str], typer.Option('--title', help='title')] = None,
+    position: Annotated[Optional[int], typer.Option('--position', help='position')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`section_edit` create."""
+    run_tool('section_edit', contract.SectionEditParams, 'create', {'dashboard_id': dashboard_id, 'page_id': page_id, 'title': title, 'position': position}, from_file=from_file, output=output)
+
+
+@section_edit.command('delete', short_help='`section_edit` delete.')
+def section_edit__delete(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    page_id: Annotated[str, typer.Option('--page-id', help='page id')],
+    section_index: Annotated[int, typer.Option('--section-index', help='section index')],
+    cascade: Annotated[Optional[bool], typer.Option('--cascade/--no-cascade', help='cascade')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`section_edit` delete."""
+    run_tool('section_edit', contract.SectionEditParams, 'delete', {'dashboard_id': dashboard_id, 'page_id': page_id, 'section_index': section_index, 'cascade': cascade}, from_file=from_file, output=output)
+
+
+@section_edit.command('rename', short_help='`section_edit` rename.')
+def section_edit__rename(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    page_id: Annotated[str, typer.Option('--page-id', help='page id')],
+    section_index: Annotated[int, typer.Option('--section-index', help='section index')],
+    title: Annotated[str, typer.Option('--title', help='New title (None to clear)')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`section_edit` rename."""
+    run_tool('section_edit', contract.SectionEditParams, 'rename', {'dashboard_id': dashboard_id, 'page_id': page_id, 'section_index': section_index, 'title': title}, from_file=from_file, output=output)
+
+
+@section_edit.command('move', short_help='`section_edit` move.')
+def section_edit__move(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='dashboard id')],
+    source_page_id: Annotated[str, typer.Option('--source-page-id', help='source page id')],
+    section_index: Annotated[int, typer.Option('--section-index', help='section index')],
+    target_page_id: Annotated[str, typer.Option('--target-page-id', help='target page id')],
+    target_position: Annotated[Optional[int], typer.Option('--target-position', help='target position')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`section_edit` move."""
+    run_tool('section_edit', contract.SectionEditParams, 'move', {'dashboard_id': dashboard_id, 'source_page_id': source_page_id, 'section_index': section_index, 'target_page_id': target_page_id, 'target_position': target_position}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# business_context_edit
+# ---------------------------------------------------------------------------
+
+
+business_context_edit = typer.Typer(name='business_context_edit', help="Edit the org's cross-cutting business_context document.", no_args_is_help=True)
+
+
+@business_context_edit.command('get', short_help='Read the current org business_context document.')
+def business_context_edit__get(
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Read the current org business_context document."""
+    run_tool('business_context_edit', contract.BusinessContextEditParams, 'get', {}, from_file=from_file, output=output)
+
+
+@business_context_edit.command('show_size', short_help='Report current size and remaining room within the 2000-byte UTF-8 cap.')
+def business_context_edit__show_size(
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Report current size and remaining room within the 2000-byte UTF-8 cap."""
+    run_tool('business_context_edit', contract.BusinessContextEditParams, 'show_size', {}, from_file=from_file, output=output)
+
+
+@business_context_edit.command('set', short_help="Replace the org's business_context with ``content`` (admin/owner).")
+def business_context_edit__set(
+    content: Annotated[str, typer.Option('--content', help='Full document content to save')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Replace the org's business_context with ``content`` (admin/owner)."""
+    run_tool('business_context_edit', contract.BusinessContextEditParams, 'set', {'content': content}, from_file=from_file, output=output)
+
+
+@business_context_edit.command('append', short_help='Append ``content`` to the existing business_context (admin/owner).')
+def business_context_edit__append(
+    content: Annotated[str, typer.Option('--content', help='Text to append to the current document')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Append ``content`` to the existing business_context (admin/owner).
+
+    Reads the current value, concatenates, and writes the combined text.
+    Useful for incremental edits where the agent doesn't already have
+    the prior content in scope.
+    """
+    run_tool('business_context_edit', contract.BusinessContextEditParams, 'append', {'content': content}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# semantic_model_edit
+# ---------------------------------------------------------------------------
+
+
+semantic_model_edit = typer.Typer(name='semantic_model_edit', help='Edit semantic models in the org manifest. Admin/owner only for writes.', no_args_is_help=True)
+
+
+@semantic_model_edit.command('create', short_help='`semantic_model_edit` create.')
+def semantic_model_edit__create(
+    model_data: Annotated[Optional[str], typer.Option('--model-data-json', help='Full semantic-model definition (name, measures, dimensions, entities) (JSON, or @path to a .json/.yaml file)')],
+    expect_version: Annotated[Optional[str], typer.Option('--expect-version', help="Managed tenants only: the datacore version (draft snapshot id) this edit was written against, from the previous edit's `version` or dataspring://datacore/files; refused with the current one when stale")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`semantic_model_edit` create."""
+    run_tool('semantic_model_edit', contract.SemanticModelEditParams, 'create', {'model_data': J(model_data), 'expect_version': expect_version}, from_file=from_file, output=output)
+
+
+@semantic_model_edit.command('update', short_help='`semantic_model_edit` update.')
+def semantic_model_edit__update(
+    name: Annotated[str, typer.Option('--name', help='name')],
+    updates: Annotated[Optional[str], typer.Option('--updates-json', help='updates (JSON, or @path to a .json/.yaml file)')],
+    confirmed: Annotated[Optional[bool], typer.Option('--confirmed/--no-confirmed', help='set true only after the user confirmed a redefinition of a NATIVE entity whose impact you showed them; has no effect on imported entities')] = None,
+    expect_version: Annotated[Optional[str], typer.Option('--expect-version', help="Managed tenants only: the datacore version (draft snapshot id) this edit was written against, from the previous edit's `version` or dataspring://datacore/files; refused with the current one when stale")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`semantic_model_edit` update."""
+    run_tool('semantic_model_edit', contract.SemanticModelEditParams, 'update', {'name': name, 'updates': J(updates), 'confirmed': confirmed, 'expect_version': expect_version}, from_file=from_file, output=output)
+
+
+@semantic_model_edit.command('delete', short_help='`semantic_model_edit` delete.')
+def semantic_model_edit__delete(
+    name: Annotated[str, typer.Option('--name', help='name')],
+    expect_version: Annotated[Optional[str], typer.Option('--expect-version', help="Managed tenants only: the datacore version (draft snapshot id) this edit was written against, from the previous edit's `version` or dataspring://datacore/files; refused with the current one when stale")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`semantic_model_edit` delete."""
+    run_tool('semantic_model_edit', contract.SemanticModelEditParams, 'delete', {'name': name, 'expect_version': expect_version}, from_file=from_file, output=output)
+
+
+@semantic_model_edit.command('preview', short_help='Validate a semantic model without writing it or touching the warehouse.')
+def semantic_model_edit__preview(
+    model_data: Annotated[Optional[str], typer.Option('--model-data-json', help='Full semantic-model definition to validate (name, measures, dimensions, entities) (JSON, or @path to a .json/.yaml file)')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Validate a semantic model without writing it or touching the warehouse."""
+    run_tool('semantic_model_edit', contract.SemanticModelEditParams, 'preview', {'model_data': J(model_data)}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# metric_edit
+# ---------------------------------------------------------------------------
+
+
+metric_edit = typer.Typer(name='metric_edit', help='Edit metrics in the org manifest. Admin/owner only for writes.', no_args_is_help=True)
+
+
+@metric_edit.command('create', short_help='`metric_edit` create.')
+def metric_edit__create(
+    metric_data: Annotated[Optional[str], typer.Option('--metric-data-json', help='Metric definition (name, type, type_params) (JSON, or @path to a .json/.yaml file)')],
+    expect_version: Annotated[Optional[str], typer.Option('--expect-version', help="Managed tenants only: the datacore version (draft snapshot id) this edit was written against, from the previous edit's `version` or dataspring://datacore/files; refused with the current one when stale")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`metric_edit` create."""
+    run_tool('metric_edit', contract.MetricEditParams, 'create', {'metric_data': J(metric_data), 'expect_version': expect_version}, from_file=from_file, output=output)
+
+
+@metric_edit.command('update', short_help='`metric_edit` update.')
+def metric_edit__update(
+    name: Annotated[str, typer.Option('--name', help='name')],
+    updates: Annotated[Optional[str], typer.Option('--updates-json', help='updates (JSON, or @path to a .json/.yaml file)')],
+    confirmed: Annotated[Optional[bool], typer.Option('--confirmed/--no-confirmed', help='set true only after the user confirmed a redefinition of a NATIVE entity whose impact you showed them; has no effect on imported entities')] = None,
+    expect_version: Annotated[Optional[str], typer.Option('--expect-version', help="Managed tenants only: the datacore version (draft snapshot id) this edit was written against, from the previous edit's `version` or dataspring://datacore/files; refused with the current one when stale")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`metric_edit` update."""
+    run_tool('metric_edit', contract.MetricEditParams, 'update', {'name': name, 'updates': J(updates), 'confirmed': confirmed, 'expect_version': expect_version}, from_file=from_file, output=output)
+
+
+@metric_edit.command('delete', short_help='`metric_edit` delete.')
+def metric_edit__delete(
+    name: Annotated[str, typer.Option('--name', help='name')],
+    expect_version: Annotated[Optional[str], typer.Option('--expect-version', help="Managed tenants only: the datacore version (draft snapshot id) this edit was written against, from the previous edit's `version` or dataspring://datacore/files; refused with the current one when stale")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`metric_edit` delete."""
+    run_tool('metric_edit', contract.MetricEditParams, 'delete', {'name': name, 'expect_version': expect_version}, from_file=from_file, output=output)
+
+
+@metric_edit.command('preview', short_help='`metric_edit` preview.')
+def metric_edit__preview(
+    metric_data: Annotated[Optional[str], typer.Option('--metric-data-json', help='Metric definition to preview (JSON, or @path to a .json/.yaml file)')],
+    sample_query: Annotated[Optional[str], typer.Option('--sample-query-json', help='Optional query params (start_date, end_date, grain, limit) (JSON, or @path to a .json/.yaml file)')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`metric_edit` preview."""
+    run_tool('metric_edit', contract.MetricEditParams, 'preview', {'metric_data': J(metric_data), 'sample_query': J(sample_query)}, from_file=from_file, output=output)
+
+
+@metric_edit.command('impact', short_help='What applying ``updates`` to this metric would touch, without writing.')
+def metric_edit__impact(
+    name: Annotated[str, typer.Option('--name', help='name')],
+    updates: Annotated[Optional[str], typer.Option('--updates-json', help='The updates whose impact to assess (JSON, or @path to a .json/.yaml file)')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """What applying ``updates`` to this metric would touch, without writing."""
+    run_tool('metric_edit', contract.MetricEditParams, 'impact', {'name': name, 'updates': J(updates)}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# quick_metric_edit
+# ---------------------------------------------------------------------------
+
+
+quick_metric_edit = typer.Typer(name='quick_metric_edit', help='Edit user-defined quick metrics (arithmetic expressions over existing metrics).', no_args_is_help=True)
+
+
+@quick_metric_edit.command('create', short_help='`quick_metric_edit` create.')
+def quick_metric_edit__create(
+    name: Annotated[str, typer.Option('--name', help='Metric name (e.g., "revenue_per_order")')],
+    expression: Annotated[str, typer.Option('--expression', help='Arithmetic expression over existing metrics (e.g., "total_revenue / order_count")')],
+    description: Annotated[Optional[str], typer.Option('--description', help='description')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`quick_metric_edit` create."""
+    run_tool('quick_metric_edit', contract.QuickMetricEditParams, 'create', {'name': name, 'expression': expression, 'description': description}, from_file=from_file, output=output)
+
+
+@quick_metric_edit.command('update', short_help='`quick_metric_edit` update.')
+def quick_metric_edit__update(
+    metric_id: Annotated[str, typer.Option('--metric-id', help='metric id')],
+    name: Annotated[Optional[str], typer.Option('--name', help='name')] = None,
+    expression: Annotated[Optional[str], typer.Option('--expression', help='expression')] = None,
+    description: Annotated[Optional[str], typer.Option('--description', help='description')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`quick_metric_edit` update."""
+    run_tool('quick_metric_edit', contract.QuickMetricEditParams, 'update', {'metric_id': metric_id, 'name': name, 'expression': expression, 'description': description}, from_file=from_file, output=output)
+
+
+@quick_metric_edit.command('delete', short_help='`quick_metric_edit` delete.')
+def quick_metric_edit__delete(
+    metric_id: Annotated[str, typer.Option('--metric-id', help='metric id')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`quick_metric_edit` delete."""
+    run_tool('quick_metric_edit', contract.QuickMetricEditParams, 'delete', {'metric_id': metric_id}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# report_edit
+# ---------------------------------------------------------------------------
+
+
+report_edit = typer.Typer(name='report_edit', help='Edit scheduled reports (recurring email delivery of dashboards or queries).', no_args_is_help=True)
+
+
+@report_edit.command('create', short_help='`report_edit` create.')
+def report_edit__create(
+    name: Annotated[str, typer.Option('--name', help='name')],
+    frequency_type: Annotated[str, typer.Option('--frequency-type', help='frequency type (one of: daily, weekly, monthly)')],
+    time: Annotated[str, typer.Option('--time', help='HH:MM in UTC, 24-hour')],
+    recipients: Annotated[list[str], typer.Option('--recipients', help='recipients')],
+    dashboard_id: Annotated[Optional[str], typer.Option('--dashboard-id', help='For dashboard reports (PDF/PNG)')] = None,
+    metrics: Annotated[Optional[list[str]], typer.Option('--metrics', help='For query reports (CSV/JSON)')] = None,
+    dimensions: Annotated[Optional[list[str]], typer.Option('--dimensions', help='dimensions')] = None,
+    format: Annotated[Optional[str], typer.Option('--format', help='"pdf"|"png" for dashboards, "csv"|"json" for queries (default: pdf)')] = None,
+    day_of_week: Annotated[Optional[int], typer.Option('--day-of-week', help='0=Mon … 6=Sun (weekly)')] = None,
+    day_of_month: Annotated[Optional[int], typer.Option('--day-of-month', help='1-28 (monthly)')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`report_edit` create."""
+    run_tool('report_edit', contract.ReportEditParams, 'create', {'name': name, 'frequency_type': frequency_type, 'time': time, 'recipients': recipients, 'dashboard_id': dashboard_id, 'metrics': metrics, 'dimensions': dimensions, 'format': format, 'day_of_week': day_of_week, 'day_of_month': day_of_month}, from_file=from_file, output=output)
+
+
+@report_edit.command('update', short_help='`report_edit` update.')
+def report_edit__update(
+    schedule_id: Annotated[str, typer.Option('--schedule-id', help='schedule id')],
+    name: Annotated[Optional[str], typer.Option('--name', help='name')] = None,
+    enabled: Annotated[Optional[bool], typer.Option('--enabled/--no-enabled', help='Set False to pause without deleting')] = None,
+    frequency_type: Annotated[Optional[str], typer.Option('--frequency-type', help='frequency type (one of: daily, weekly, monthly)')] = None,
+    time: Annotated[Optional[str], typer.Option('--time', help='time')] = None,
+    day_of_week: Annotated[Optional[int], typer.Option('--day-of-week', help='day of week')] = None,
+    day_of_month: Annotated[Optional[int], typer.Option('--day-of-month', help='day of month')] = None,
+    recipients: Annotated[Optional[list[str]], typer.Option('--recipients', help='recipients')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`report_edit` update."""
+    run_tool('report_edit', contract.ReportEditParams, 'update', {'schedule_id': schedule_id, 'name': name, 'enabled': enabled, 'frequency_type': frequency_type, 'time': time, 'day_of_week': day_of_week, 'day_of_month': day_of_month, 'recipients': recipients}, from_file=from_file, output=output)
+
+
+@report_edit.command('delete', short_help='`report_edit` delete.')
+def report_edit__delete(
+    schedule_id: Annotated[str, typer.Option('--schedule-id', help='schedule id')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`report_edit` delete."""
+    run_tool('report_edit', contract.ReportEditParams, 'delete', {'schedule_id': schedule_id}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# learned_edit
+# ---------------------------------------------------------------------------
+
+
+learned_edit = typer.Typer(name='learned_edit', help='Browse and undo the learned trail — what DataSpring learned for this org.', no_args_is_help=True)
+
+
+@learned_edit.command('list', short_help='List what DataSpring learned for this org (plus your personal entries).')
+def learned_edit__list(
+    limit: Annotated[Optional[int], typer.Option('--limit', help='limit (default: 20)')] = None,
+    include_reverted: Annotated[Optional[bool], typer.Option('--include-reverted/--no-include-reverted', help='include reverted')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """List what DataSpring learned for this org (plus your personal entries)."""
+    run_tool('learned_edit', contract.LearnedEditParams, 'list', {'limit': limit, 'include_reverted': include_reverted}, from_file=from_file, output=output)
+
+
+@learned_edit.command('undo', short_help='Revert one learning (or, with no id, your most recent reversible one).')
+def learned_edit__undo(
+    learning_id: Annotated[Optional[str], typer.Option('--learning-id', help='Learning to revert; omit for your most recent reversible entry')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Revert one learning (or, with no id, your most recent reversible one)."""
+    run_tool('learned_edit', contract.LearnedEditParams, 'undo', {'learning_id': learning_id}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# verified_query_edit
+# ---------------------------------------------------------------------------
+
+
+verified_query_edit = typer.Typer(name='verified_query_edit', help='Curate verified queries — confirmed (question, query) pairs.', no_args_is_help=True)
+
+
+@verified_query_edit.command('list', short_help="The org's verified queries plus your own personal ones.")
+def verified_query_edit__list(
+    limit: Annotated[Optional[int], typer.Option('--limit', help='limit (default: 20)')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """The org's verified queries plus your own personal ones."""
+    run_tool('verified_query_edit', contract.VerifiedQueryEditParams, 'list', {'limit': limit}, from_file=from_file, output=output)
+
+
+@verified_query_edit.command('record', short_help='Record one confirmed (question, query) pair.')
+def verified_query_edit__record(
+    question: Annotated[str, typer.Option('--question', help="The user's question, verbatim")],
+    params: Annotated[Optional[str], typer.Option('--params-json', help='The query that answers it, in the query_metrics wire shape: metrics, dimensions, grain, start_date, end_date, where, order_by, limit (JSON, or @path to a .json/.yaml file)')],
+    note: Annotated[Optional[str], typer.Option('--note', help='One line on WHY this is the right query for that question')] = None,
+    scope: Annotated[Optional[str], typer.Option('--scope', help="'user' (the default) records it in this user's personal set; 'org' curates it for everyone and requires admin/owner (one of: org, user) (default: user)")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Record one confirmed (question, query) pair."""
+    run_tool('verified_query_edit', contract.VerifiedQueryEditParams, 'record', {'question': question, 'params': J(params), 'note': note, 'scope': scope}, from_file=from_file, output=output)
+
+
+@verified_query_edit.command('delete', short_help='Remove one verified query by id.')
+def verified_query_edit__delete(
+    id: Annotated[str, typer.Option('--id', help='id')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Remove one verified query by id."""
+    run_tool('verified_query_edit', contract.VerifiedQueryEditParams, 'delete', {'id': id}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# warehouse_edit
+# ---------------------------------------------------------------------------
+
+
+warehouse_edit = typer.Typer(name='warehouse_edit', help='Manage the org\'s warehouses (admin/owner). Read them with ``dataspring://warehouses`` / ``read(kind="warehouses")``: each entry has id, kind (external | managed), label, active flag, manifest counts and import time.', no_args_is_help=True)
+
+
+@warehouse_edit.command('activate', short_help="Make one warehouse the org's default: every query that names no ``warehouse`` runs against it.")
+def warehouse_edit__activate(
+    id: Annotated[str, typer.Option('--id', help="Warehouse id, e.g. 'managed' or 'external'")],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Make one warehouse the org's default: every query that names no
+    ``warehouse`` runs against it.
+    """
+    run_tool('warehouse_edit', contract.WarehouseEditParams, 'activate', {'id': id}, from_file=from_file, output=output)
+
+
+@warehouse_edit.command('add_external', short_help='Register a customer-owned BigQuery project as an external warehouse.')
+def warehouse_edit__add_external(
+    label: Annotated[str, typer.Option('--label', help='Display name, e.g. "Noon\'s BigQuery"')],
+    project: Annotated[str, typer.Option('--project', help="The customer's GCP project id")],
+    dataset: Annotated[str, typer.Option('--dataset', help='The dataset the semantic manifest points at')],
+    location: Annotated[str, typer.Option('--location', help="BigQuery location of that dataset, e.g. 'europe-north2'")],
+    key_secret: Annotated[str, typer.Option('--key-secret', help="NAME of the Secret Manager secret holding the customer's service-account key (t-<org>-external-bigquery-key). Never the key itself.")],
+    id: Annotated[Optional[str], typer.Option('--id', help="Warehouse id to create (default 'external') (default: external)")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Register a customer-owned BigQuery project as an external warehouse.
+
+    The customer's key is NOT an argument: it lives in Secret Manager in the
+    data project and is only named here (``key_secret``).
+    """
+    run_tool('warehouse_edit', contract.WarehouseEditParams, 'add_external', {'label': label, 'project': project, 'dataset': dataset, 'location': location, 'key_secret': key_secret, 'id': id}, from_file=from_file, output=output)
+
+
+@warehouse_edit.command('remove', short_help='Delete a warehouse and its manifest. Refused for the active warehouse and for the managed one.')
+def warehouse_edit__remove(
+    id: Annotated[str, typer.Option('--id', help='Warehouse id to remove')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Delete a warehouse and its manifest. Refused for the active warehouse
+    and for the managed one.
+    """
+    run_tool('warehouse_edit', contract.WarehouseEditParams, 'remove', {'id': id}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# query_metrics
+# ---------------------------------------------------------------------------
+
+
+def query_metrics(
+    metrics: Annotated[list[str], typer.Option('--metrics', help="List of metric names to query (e.g., ['total_revenue', 'order_count'])")],
+    dimensions: Annotated[Optional[list[str]], typer.Option('--dimensions', help="Dimensions to group by. Use qualified names from dataspring://dimensions (e.g., ['customer__segment', 'order__region'])")] = None,
+    grain: Annotated[Optional[str], typer.Option('--grain', help="Time granularity: 'day', 'week', 'month', 'quarter', or 'year'")] = None,
+    start_date: Annotated[Optional[str], typer.Option('--start-date', help='Start date in YYYY-MM-DD format')] = None,
+    end_date: Annotated[Optional[str], typer.Option('--end-date', help='End date in YYYY-MM-DD format')] = None,
+    limit: Annotated[Optional[int], typer.Option('--limit', help='Maximum number of rows to return')] = None,
+    order_by: Annotated[Optional[str], typer.Option('--order-by', help="Column to sort by, append ' desc' for descending (e.g., 'total_revenue desc')")] = None,
+    where: Annotated[Optional[list[str]], typer.Option('--where', help='Row filters in MetricFlow\'s constraint syntax, one string each, e.g. "{{ Dimension(\'customer__segment\') }} NOT IN (\'Direct\')". Use qualified names from dataspring://dimensions - an unresolvable name comes back as an error whose suggestion names the qualified form. `where` decides WHICH ROWS the numbers cover; `dimensions` breaks the numbers OUT by a column; send both for a breakdown of a filtered slice. A `where` on a dimension also overrides the user\'s standing filter on that same dimension for this call.')] = None,
+    warehouse: Annotated[Optional[str], typer.Option('--warehouse', help="Which of the org's warehouses to run against - an id from dataspring://warehouses ('managed', 'external', ...). Omit for the active one. During a migration ask both and compare.")] = None,
+    suggest_visualization: Annotated[Optional[bool], typer.Option('--suggest-visualization/--no-suggest-visualization', help='Also return a suggested visualization type for the result.')] = None,
+    format: Annotated[Optional[str], typer.Option('--format', help="'json' (default) answers rows in `data`; 'csv' answers the same result as one CSV document in `content` (header row first) for a file or a spreadsheet, with `columns` and `row_count` alongside. (one of: json, csv) (default: json)")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Fetch metric data from the warehouse.
+
+    Consult ``list_metrics`` first: each metric's description is
+    authoritative for unit, source rollup, filter rules, and caveats — apply
+    them unless the user explicitly overrides. Segment the query around a
+    description's temporal discontinuity (system migration, ETL bug fix) and
+    say so; follow a derived-dimension pointer; refuse honestly rather than
+    query the closest-named metric when the catalog can't answer.
+
+    ``where`` decides WHICH ROWS the numbers cover; ``dimensions`` breaks
+    those numbers OUT by a column. Send both for a breakdown of a slice.
+    ``warehouse`` picks one of the org's warehouses (see
+    ``dataspring://warehouses``); omit it for the active one.
+    ``format="csv"`` returns the result as one CSV document in ``content``
+    instead of rows, for a file or a spreadsheet.
+
+    If the response carries ``applied_defaults`` (the query was rewritten
+    from saved preferences), state every entry's ``echo_text`` in the
+    answer, next to the number it changed ("Revenue $94k, excluding Direct —
+    your standing filter") — a defaulted number is not the unqualified one.
+    A ``where`` you send on the same dimension overrides that standing
+    filter and nothing is reported for it — say that too.
+
+    Examples:
+    - Monthly revenue: metrics=['total_revenue'], grain='month', start_date='2024-01-01'
+    - Revenue by region: metrics=['total_revenue'], dimensions=['region']
+    - Top 10: metrics=['total_revenue'], dimensions=['customer_name'], order_by='total_revenue desc', limit=10
+    """
+    run_tool('query_metrics', contract.QueryMetricsParams, None, {'metrics': metrics, 'dimensions': dimensions, 'grain': grain, 'start_date': start_date, 'end_date': end_date, 'limit': limit, 'order_by': order_by, 'where': where, 'warehouse': warehouse, 'suggest_visualization': suggest_visualization, 'format': format}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# explain_query
+# ---------------------------------------------------------------------------
+
+
+def explain_query(
+    metrics: Annotated[list[str], typer.Option('--metrics', help="List of metric names to query (e.g., ['total_revenue', 'order_count'])")],
+    dimensions: Annotated[Optional[list[str]], typer.Option('--dimensions', help="Dimensions to group by. Use qualified names from dataspring://dimensions (e.g., ['customer__segment', 'order__region'])")] = None,
+    grain: Annotated[Optional[str], typer.Option('--grain', help="Time granularity: 'day', 'week', 'month', 'quarter', or 'year'")] = None,
+    start_date: Annotated[Optional[str], typer.Option('--start-date', help='Start date in YYYY-MM-DD format')] = None,
+    end_date: Annotated[Optional[str], typer.Option('--end-date', help='End date in YYYY-MM-DD format')] = None,
+    limit: Annotated[Optional[int], typer.Option('--limit', help='Maximum number of rows to return')] = None,
+    order_by: Annotated[Optional[str], typer.Option('--order-by', help="Column to sort by, append ' desc' for descending (e.g., 'total_revenue desc')")] = None,
+    where: Annotated[Optional[list[str]], typer.Option('--where', help='Row filters in MetricFlow\'s constraint syntax, one string each, e.g. "{{ Dimension(\'customer__segment\') }} NOT IN (\'Direct\')". Use qualified names from dataspring://dimensions - an unresolvable name comes back as an error whose suggestion names the qualified form. `where` decides WHICH ROWS the numbers cover; `dimensions` breaks the numbers OUT by a column; send both for a breakdown of a filtered slice. A `where` on a dimension also overrides the user\'s standing filter on that same dimension for this call.')] = None,
+    warehouse: Annotated[Optional[str], typer.Option('--warehouse', help="Which of the org's warehouses to run against - an id from dataspring://warehouses ('managed', 'external', ...). Omit for the active one. During a migration ask both and compare.")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Show what a query computes without running it: the resolved metrics and
+    dimensions, the effective time window, the filters (including any standing
+    preference folded in) and the compiled SQL. Use it when the user asks what
+    you actually computed, disputes a number, or before proposing a correction.
+    ``warehouse`` picks one of the org's warehouses; omit it for the active one.
+    """
+    run_tool('explain_query', contract.ExplainQueryParams, None, {'metrics': metrics, 'dimensions': dimensions, 'grain': grain, 'start_date': start_date, 'end_date': end_date, 'limit': limit, 'order_by': order_by, 'where': where, 'warehouse': warehouse}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# update_context
+# ---------------------------------------------------------------------------
+
+
+def update_context(
+    updates: Annotated[Optional[str], typer.Option('--updates-json', help='Fields to update; only these change. Presentation: default_currency, default_grain, decimal_places, preferred_chart_type. Lists and maps REPLACE what is stored: favorite_metrics, standing_filters ([{dimension, operator: in|not_in|eq|neq, values}]), metric_substitutions ({asked: preferred}), default_segment ({dimension, value} or null). (JSON, or @path to a .json/.yaml file)')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Update user preferences (merge, not replace).
+
+    Use this when you learn a user preference in conversation. Only
+    provided fields are updated; others remain unchanged.
+
+    Args:
+        updates: Fields to update. Supported fields:
+            - default_currency, default_grain, decimal_places,
+              preferred_chart_type: presentation prefs.
+            - favorite_metrics: list of metric names. REPLACES the stored
+              list — read current favourites first (``dataspring://context`` /
+              ``get_context``) and send them back with the new one, or the
+              ones left out are dropped.
+            - standing_filters: filters applied to every query, as
+              [{"dimension": "customer__segment", "operator": "not_in",
+              "values": ["Direct"]}]. Operators: in, not_in, eq, neq
+              (eq/neq take exactly one value). REPLACES the stored list.
+            - metric_substitutions: {asked_metric: preferred_metric}, e.g.
+              {"revenue": "total_revenue_ex_vat"} — what to query when the
+              user asks by that word. REPLACES the stored map.
+            - default_segment: {"dimension": ..., "value": ...} (or null to
+              clear) — the slice to assume when the user names none.
+
+        Dimension/metric names in the last three must exist in this org's
+        semantic layer, or the write is rejected, naming them. Bare
+        dimension names are stored qualified.
+
+    Example: update_context({"default_currency": "EUR", "default_grain": "month"})
+    """
+    run_tool('update_context', contract.UpdateContextParams, None, {'updates': J(updates)}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# export_data
+# ---------------------------------------------------------------------------
+
+
+def export_data(
+    format: Annotated[Optional[str], typer.Option('--format', help="Output format: 'csv' or 'json'. (one of: csv, json) (default: csv)")] = None,
+    metrics: Annotated[Optional[list[str]], typer.Option('--metrics', help='Metric names to query (query export).')] = None,
+    dimensions: Annotated[Optional[list[str]], typer.Option('--dimensions', help='Dimensions to group by (query export).')] = None,
+    grain: Annotated[Optional[str], typer.Option('--grain', help="Time granularity: 'day', 'week', 'month', 'quarter' or 'year' (query export).")] = None,
+    start_date: Annotated[Optional[str], typer.Option('--start-date', help='Start date, YYYY-MM-DD (query export).')] = None,
+    end_date: Annotated[Optional[str], typer.Option('--end-date', help='End date, YYYY-MM-DD (query export).')] = None,
+    dashboard_id: Annotated[Optional[str], typer.Option('--dashboard-id', help='Dashboard id for a dashboard export; takes precedence over the query fields.')] = None,
+    output_path: Annotated[Optional[str], typer.Option('--output-path', help='If given, save to this file path instead of returning the content.')] = None,
+    warehouse: Annotated[Optional[str], typer.Option('--warehouse', help="One of the org's warehouses (see dataspring://warehouses); omit for the active one (query export only).")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Export query results or dashboard data to CSV or JSON.
+
+    You can either:
+    - Export query results by specifying metrics, dimensions, etc.
+    - Export all data from a dashboard by specifying dashboard_id
+
+    Args:
+        format: Output format - "csv" or "json" (default: csv)
+        metrics: List of metric names to query (for query export)
+        dimensions: Dimensions to group by (for query export)
+        grain: Time granularity (for query export)
+        start_date: Start date YYYY-MM-DD (for query export)
+        end_date: End date YYYY-MM-DD (for query export)
+        dashboard_id: Dashboard ID (for dashboard export, overrides query params)
+        output_path: If provided, save to this file path
+        warehouse: One of the org's warehouses (see dataspring://warehouses);
+            omit for the active one (query export only)
+
+    Returns the data content (CSV or JSON) or file path if saved.
+    """
+    run_tool('export_data', contract.ExportDataParams, None, {'format': format, 'metrics': metrics, 'dimensions': dimensions, 'grain': grain, 'start_date': start_date, 'end_date': end_date, 'dashboard_id': dashboard_id, 'output_path': output_path, 'warehouse': warehouse}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# import_manifest
+# ---------------------------------------------------------------------------
+
+
+def import_manifest(
+    manifest_data: Annotated[Optional[str], typer.Option('--manifest-data-json', help='The semantic manifest to import (semantic models, metrics), as a JSON object. (JSON, or @path to a .json/.yaml file)')],
+    warehouse: Annotated[Optional[str], typer.Option('--warehouse', help="Which of the org's warehouses the manifest belongs to (see dataspring://warehouses); omit for the active one.")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Import a semantic manifest using replace semantics.
+
+    The manifest is the source of truth for the imported namespace. Items
+    absent from the upload are hard-deleted. User-created (DataSpring UI/MCP)
+    metrics and models are never touched. A name collision with a
+    user-created item is reported as a conflict; the user-created version
+    wins and the upload entry is skipped.
+
+    The upload is rejected if the uploaded manifest is internally
+    inconsistent or would leave the org with unresolved metric→measure /
+    metric→metric / quick-metric references.
+
+    ``warehouse`` names which of the org's warehouses the manifest belongs
+    to (each has its own); omit it for the active one. Requires admin or
+    owner role.
+    """
+    run_tool('import_manifest', contract.ImportManifestParams, None, {'manifest_data': J(manifest_data), 'warehouse': warehouse}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# render_dashboard
+# ---------------------------------------------------------------------------
+
+
+def render_dashboard(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='ID of the dashboard to render.')],
+    format: Annotated[Optional[str], typer.Option('--format', help="'app' for an interactive iframe payload (default), 'pdf' or 'png' for a static export. (one of: pdf, png, app) (default: app)")] = None,
+    page_id: Annotated[Optional[str], typer.Option('--page-id', help='(pdf/png only) One page to render; default: all pages.')] = None,
+    width: Annotated[Optional[int], typer.Option('--width', help='(pdf/png only) Viewport width in pixels. (default: 1200)')] = None,
+    height: Annotated[Optional[int], typer.Option('--height', help='(pdf/png only) Viewport height in pixels. (default: 800)')] = None,
+    output_path: Annotated[Optional[str], typer.Option('--output-path', help='(pdf/png only) Save to this file path instead of returning base64.')] = None,
+    warehouse: Annotated[Optional[str], typer.Option('--warehouse', help="One of the org's warehouses (see dataspring://warehouses) the widgets query; omit for the active one.")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Render a dashboard.
+
+    Modes:
+    - **app** (default): returns an interactive iframe payload that hosts
+      with the MCP UI extension (Claude.ai, Claude Code, `fastmcp dev apps`)
+      render inline. Hosts without UI support receive the JSON payload and
+      can open ``embed_url`` in a browser tab.
+    - **pdf** / **png**: headless-Chrome static export (legacy path).
+
+    Args:
+        dashboard_id: ID of the dashboard to render
+        format: "app" for interactive iframe (default), "pdf"/"png" for
+                static export.
+        page_id: (pdf/png only) Optional page ID to render (default: all pages)
+        width: (pdf/png only) Viewport width in pixels (default: 1200)
+        height: (pdf/png only) Viewport height in pixels (default: 800)
+        output_path: (pdf/png only) If provided, save to this file path instead
+                     of returning base64.
+        warehouse: One of the org's warehouses (see dataspring://warehouses)
+                   the widgets query; omit for the active one.
+
+    App mode is iframed by hosts that advertise the MCP UI extension.
+    PDF/PNG modes require headless Chrome.
+    """
+    run_tool('render_dashboard', contract.RenderDashboardParams, None, {'dashboard_id': dashboard_id, 'format': format, 'page_id': page_id, 'width': width, 'height': height, 'output_path': output_path, 'warehouse': warehouse}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# render_widget
+# ---------------------------------------------------------------------------
+
+
+def render_widget(
+    dashboard_id: Annotated[str, typer.Option('--dashboard-id', help='ID of the dashboard containing the widget.')],
+    widget_id: Annotated[str, typer.Option('--widget-id', help='ID of the widget to render.')],
+    format: Annotated[Optional[str], typer.Option('--format', help="'app' for an interactive iframe payload (default), 'png' for a static snapshot. (one of: png, app) (default: app)")] = None,
+    width: Annotated[Optional[int], typer.Option('--width', help='(png only) Viewport width in pixels. (default: 600)')] = None,
+    height: Annotated[Optional[int], typer.Option('--height', help='(png only) Viewport height in pixels. (default: 400)')] = None,
+    output_path: Annotated[Optional[str], typer.Option('--output-path', help='(png only) Save to this file path instead of returning base64.')] = None,
+    warehouse: Annotated[Optional[str], typer.Option('--warehouse', help="One of the org's warehouses (see dataspring://warehouses) the widget queries; omit for the active one.")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Render a single widget.
+
+    Modes:
+    - **app** (default): interactive iframe payload; hosts with the MCP UI
+      extension render it inline.
+    - **png**: headless-Chrome static snapshot as base64 PNG.
+
+    Args:
+        dashboard_id: ID of the dashboard containing the widget
+        widget_id: ID of the widget to render
+        format: "app" for interactive iframe (default), "png" for static snapshot.
+        width: (png only) Viewport width in pixels (default: 600)
+        height: (png only) Viewport height in pixels (default: 400)
+        output_path: (png only) Save to this file path instead of returning base64.
+        warehouse: One of the org's warehouses (see dataspring://warehouses)
+                   the widget queries; omit for the active one.
+
+    App mode is iframed by hosts that advertise the MCP UI extension.
+    PNG mode requires headless Chrome.
+    """
+    run_tool('render_widget', contract.RenderWidgetParams, None, {'dashboard_id': dashboard_id, 'widget_id': widget_id, 'format': format, 'width': width, 'height': height, 'output_path': output_path, 'warehouse': warehouse}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# switch_organization
+# ---------------------------------------------------------------------------
+
+
+def switch_organization(
+    org_id: Annotated[str, typer.Option('--org-id', help='The organization ID to switch to (see read(kind="organizations")).')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Switch this Claude Code (stdio) session or CLI login to a different
+    organization: it becomes the account's default org and the next call
+    runs in it. Browse ids via ``read(kind="organizations")``.
+
+    Over HTTP (Claude.ai and other remote hosts) an organization is chosen
+    per connection by ``?org=<id>`` on the MCP URL, never by a call, so this
+    tool is refused there: the error names the exact URL to connect with for
+    the target org.
+
+    Raises:
+        DispatchError: the org does not exist, or the switch failed. This one
+            fails loudly rather than returning ``{"error": …}`` — a surface
+            that silently kept the old org would answer the next question
+            against the wrong warehouse.
+    """
+    run_tool('switch_organization', contract.SwitchOrganizationParams, None, {'org_id': org_id}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# submit_error_report
+# ---------------------------------------------------------------------------
+
+
+def submit_error_report(
+    command: Annotated[str, typer.Option('--command', help="The tool, resource, or action that failed (e.g. 'query_metrics', 'dataspring://dashboards', 'dashboard_edit').")],
+    error_message: Annotated[str, typer.Option('--error-message', help='The exact error message received.')],
+    expected: Annotated[Optional[str], typer.Option('--expected', help='What you expected to happen.')] = None,
+    context_info: Annotated[Optional[str], typer.Option('--context-info', help='What you were trying to achieve.')] = None,
+    source: Annotated[Optional[str], typer.Option('--source', help="Which surface sent the report: 'mcp', 'cli' or 'api'. (default: mcp)")] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Submit an error report to help improve DataSpring.
+
+    Use this when a tool returns an unexpected error or incorrect result.
+
+    Args:
+        command: The tool, resource, or action that failed (e.g. 'query_metrics', 'dataspring://dashboards', 'dashboard_edit')
+        error_message: The exact error message received
+        expected: What you expected to happen (optional)
+        context_info: What you were trying to achieve (optional)
+    """
+    run_tool('submit_error_report', contract.SubmitErrorReportParams, None, {'command': command, 'error_message': error_message, 'expected': expected, 'context_info': context_info, 'source': source}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# secret_edit
+# ---------------------------------------------------------------------------
+
+
+secret_edit = typer.Typer(name='secret_edit', help='Customer secrets, both directions, as one-time LINKS (admin/owner). A value never passes through a model: hand the person the ``link`` (valid 15 minutes, this organization only, works once).', no_args_is_help=True)
+
+
+@secret_edit.command('set', short_help='Get a one-time link where a PERSON pastes a credential. The value never comes through here; the same name rotates a credential.')
+def secret_edit__set(
+    name: Annotated[str, typer.Option('--name', help='The secret to set or rotate: t-<org>-<connection>-<field> for your organization, lower-case (t-acme-kanpla-api_key, t-acme-external-bigquery-key). A connection file names it.')],
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Get a one-time link where a PERSON pastes a credential. The value
+    never comes through here; the same name rotates a credential.
+    """
+    run_tool('secret_edit', contract.SecretEditParams, 'set', {'name': name}, from_file=from_file, output=output)
+
+
+@secret_edit.command('reveal', short_help='Get a one-time link that shows a credential DataSpring ISSUED to this organization (the Airbyte destination key today), once.')
+def secret_edit__reveal(
+    name: Annotated[Optional[str], typer.Option('--name', help='The issued credential, by secret name. Omit for the Airbyte destination key (t-<org>-airbyte-key). Only issued credentials can be revealed, never ones you gave DataSpring.')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Get a one-time link that shows a credential DataSpring ISSUED to this
+    organization (the Airbyte destination key today), once.
+    """
+    run_tool('secret_edit', contract.SecretEditParams, 'reveal', {'name': name}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# run_sql
+# ---------------------------------------------------------------------------
+
+
+def run_sql(
+    sql: Annotated[str, typer.Option('--sql', help='One SQL statement (BigQuery Standard SQL on a managed warehouse). Name tables as <org>_marts.<table>, <org>_core.<table> or <org>_staging.<table>; the identity it runs as can read those and nothing else, so a write or a reach outside them is refused by the warehouse.')],
+    warehouse: Annotated[Optional[str], typer.Option('--warehouse', help="One of the org's warehouses (see dataspring://warehouses); omit for the active one.")] = None,
+    max_rows: Annotated[Optional[int], typer.Option('--max-rows', help='Rows to return at most (default 1000, cap 10000). Aggregate in SQL rather than paging. (default: 1000)')] = None,
+    format: Annotated[Optional[str], typer.Option('--format', help="'json' answers rows in `data`; 'csv' or 'markdown' answer one document in `content`. (one of: json, csv, markdown) (default: json)")] = None,
+    dry_run: Annotated[Optional[bool], typer.Option('--dry-run/--no-dry-run', help='Only estimate the bytes the statement would process (and check it parses); run nothing.')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Run ONE read-only SQL statement against the org's warehouse and get
+    the rows back, ungoverned.
+
+    Metrics first: ``list_metrics`` / ``query_metrics`` answer with the
+    org's own definitions (units, filters, caveats) and are what a number
+    in an answer should come from. Use ``run_sql`` for what the semantic
+    layer does not expose: a column it has no dimension for, a row-level
+    look at a mart, a join the models do not make, checking a load. Say in
+    the answer that such numbers are not metric definitions (every result
+    carries ``governed: false`` and a note).
+
+    On a managed warehouse the statement runs as the tenant's read-only
+    identity (``t-<org>-reader@``: marts, core and staging, nothing else),
+    so any write, export or reach outside those datasets is refused by
+    BigQuery itself. It is dry-run first and refused over the byte cap;
+    the timeout and ``max_rows`` bound it further. On an external
+    warehouse it runs with the customer's own key. Every call is logged
+    with the statement and the caller.
+    """
+    run_tool('run_sql', contract.RunSqlParams, None, {'sql': sql, 'warehouse': warehouse, 'max_rows': max_rows, 'format': format, 'dry_run': dry_run}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# datacore_edit
+# ---------------------------------------------------------------------------
+
+
+datacore_edit = typer.Typer(name='datacore_edit', help='Edit the datacore workspace: connections, pipelines and the dbt project of a managed tenant, as files. ``kind`` picks the family:', no_args_is_help=True)
+
+
+@datacore_edit.command('apply', short_help='Write one workspace file whole (create or replace): a connection or pipeline as a ``document`` (validated against its schema and the catalog), a dbt project file as ``content``.')
+def datacore_edit__apply(
+    kind: Annotated[str, typer.Option('--kind', help='connection (admin), pipeline (admin) or model (member) (one of: connection, pipeline, model)')],
+    name: Annotated[str, typer.Option('--name', help='For kind connection or pipeline: the name, i.e. the file name without .yaml (connections/<name>.yaml, pipelines/<name>.yaml). For kind model: the path under models/, the dbt project (models/models/marts/orders.sql, models/models/staging/schema.yml, models/seeds/x.csv, models/dbt_project.yml); no traversal, .sql .yml .yaml .csv .md .txt .json, never target/ or dbt_packages/')],
+    document: Annotated[Optional[str], typer.Option('--document-json', help='kind connection: the whole document (connection.schema.json: kind, base_url, auth with secret NAMES). kind pipeline: the whole document (pipeline.schema.json: a catalog `connector` with config, secrets, overrides; or a `connection` reference, an inline `source` or named `sources`, with `resources`; schedule, checks, then). Secrets are named, never valued; every name must exist (JSON, or @path to a .json/.yaml file)')] = None,
+    content: Annotated[Optional[str], typer.Option('--content', help='kind model: the whole file content')] = None,
+    expect_version: Annotated[Optional[str], typer.Option('--expect-version', help='The datacore version this edit was written against: the `version` the previous edit returned, or dataspring://datacore/files. An edit against a stale version is refused with the current one. Omit to skip the check.')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Write one workspace file whole (create or replace): a connection or
+    pipeline as a ``document`` (validated against its schema and the
+    catalog), a dbt project file as ``content``.
+    """
+    run_tool('datacore_edit', contract.DatacoreEditParams, 'apply', {'kind': kind, 'name': name, 'document': J(document), 'content': content, 'expect_version': expect_version}, from_file=from_file, output=output)
+
+
+@datacore_edit.command('patch', short_help='Apply a JSON merge patch (RFC 7386: a key set to null is removed) to an existing YAML file: a connection, a pipeline (a schedule, a window, a check), or a YAML file under models/ (not SQL).')
+def datacore_edit__patch(
+    kind: Annotated[str, typer.Option('--kind', help='connection (admin), pipeline (admin) or model (member) (one of: connection, pipeline, model)')],
+    name: Annotated[str, typer.Option('--name', help='For kind connection or pipeline: the name, i.e. the file name without .yaml (connections/<name>.yaml, pipelines/<name>.yaml). For kind model: the path under models/, the dbt project (models/models/marts/orders.sql, models/models/staging/schema.yml, models/seeds/x.csv, models/dbt_project.yml); no traversal, .sql .yml .yaml .csv .md .txt .json, never target/ or dbt_packages/')],
+    patch: Annotated[Optional[str], typer.Option('--patch-json', help='JSON merge patch over the current document (JSON, or @path to a .json/.yaml file)')],
+    expect_version: Annotated[Optional[str], typer.Option('--expect-version', help='The datacore version this edit was written against: the `version` the previous edit returned, or dataspring://datacore/files. An edit against a stale version is refused with the current one. Omit to skip the check.')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Apply a JSON merge patch (RFC 7386: a key set to null is removed) to an
+    existing YAML file: a connection, a pipeline (a schedule, a window, a
+    check), or a YAML file under models/ (not SQL).
+    """
+    run_tool('datacore_edit', contract.DatacoreEditParams, 'patch', {'kind': kind, 'name': name, 'patch': J(patch), 'expect_version': expect_version}, from_file=from_file, output=output)
+
+
+@datacore_edit.command('delete', short_help='Remove one workspace file.')
+def datacore_edit__delete(
+    kind: Annotated[str, typer.Option('--kind', help='connection (admin), pipeline (admin) or model (member) (one of: connection, pipeline, model)')],
+    name: Annotated[str, typer.Option('--name', help='For kind connection or pipeline: the name, i.e. the file name without .yaml (connections/<name>.yaml, pipelines/<name>.yaml). For kind model: the path under models/, the dbt project (models/models/marts/orders.sql, models/models/staging/schema.yml, models/seeds/x.csv, models/dbt_project.yml); no traversal, .sql .yml .yaml .csv .md .txt .json, never target/ or dbt_packages/')],
+    expect_version: Annotated[Optional[str], typer.Option('--expect-version', help='The datacore version this edit was written against: the `version` the previous edit returned, or dataspring://datacore/files. An edit against a stale version is refused with the current one. Omit to skip the check.')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Remove one workspace file."""
+    run_tool('datacore_edit', contract.DatacoreEditParams, 'delete', {'kind': kind, 'name': name, 'expect_version': expect_version}, from_file=from_file, output=output)
+
+
+# ---------------------------------------------------------------------------
+# datacore_run
+# ---------------------------------------------------------------------------
+
+
+datacore_run = typer.Typer(name='datacore_run', help="The datacore's check-then-deploy loop and its operations.", no_args_is_help=True)
+
+
+@datacore_run.command('check', short_help='Check the current draft; no arguments beyond an optional note.')
+def datacore_run__check(
+    note: Annotated[Optional[str], typer.Option('--note', help='Optional note, recorded on the check run')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """Check the current draft; no arguments beyond an optional note."""
+    run_tool('datacore_run', contract.DatacoreRunParams, 'check', {'note': note}, from_file=from_file, output=output)
+
+
+@datacore_run.command('deploy', short_help='`datacore_run` deploy.')
+def datacore_run__deploy(
+    snapshot: Annotated[Optional[str], typer.Option('--snapshot', help='Omit to promote the current draft (needs a green check bound to it). A previously deployed snapshot id rolls back to it')] = None,
+    note: Annotated[Optional[str], typer.Option('--note', help='Why, recorded on the learned trail')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`datacore_run` deploy."""
+    run_tool('datacore_run', contract.DatacoreRunParams, 'deploy', {'snapshot': snapshot, 'note': note}, from_file=from_file, output=output)
+
+
+@datacore_run.command('run', short_help='`datacore_run` run.')
+def datacore_run__run(
+    pipeline: Annotated[str, typer.Option('--pipeline', help='Pipeline name (a deployed pipelines/<name>.yaml)')],
+    window: Annotated[Optional[str], typer.Option('--window-json', help="A date window to load instead of the pipeline's own; wider than backfill_chunk becomes a chunked backfill (JSON object with keys: start, end, or @path to a .json/.yaml file)")] = None,
+    cursor: Annotated[Optional[str], typer.Option('--cursor-json', help='{from: <value>}: a cursor to re-pull from (JSON object with keys: from, or @path to a .json/.yaml file)')] = None,
+    backfill_chunk: Annotated[Optional[str], typer.Option('--backfill-chunk', help='Chunk size for a windowed run: 7d, 2w or 1M (calendar months, the default)')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`datacore_run` run."""
+    run_tool('datacore_run', contract.DatacoreRunParams, 'run', {'pipeline': pipeline, 'window': J(window), 'cursor': J(cursor), 'backfill_chunk': backfill_chunk}, from_file=from_file, output=output)
+
+
+@datacore_run.command('reset', short_help='`datacore_run` reset.')
+def datacore_run__reset(
+    pipeline: Annotated[str, typer.Option('--pipeline', help='The pipeline whose dlt state and raw tables to remove')],
+    approve: Annotated[Optional[bool], typer.Option('--approve/--no-approve', help='Must be true: the reset is irreversible. Ask the user first')] = None,
+    from_file: FromFile = None,
+    output: Output = None,
+) -> None:
+    """`datacore_run` reset."""
+    run_tool('datacore_run', contract.DatacoreRunParams, 'reset', {'pipeline': pipeline, 'approve': approve}, from_file=from_file, output=output)
+
+
+def mount(app: typer.Typer) -> None:
+    """Add every generated command to ``app``: flat tools at the root, families as groups."""
+    app.add_typer(dashboard_edit, name='dashboard_edit')
+    app.add_typer(widget_edit, name='widget_edit')
+    app.add_typer(page_edit, name='page_edit')
+    app.add_typer(section_edit, name='section_edit')
+    app.add_typer(business_context_edit, name='business_context_edit')
+    app.add_typer(semantic_model_edit, name='semantic_model_edit')
+    app.add_typer(metric_edit, name='metric_edit')
+    app.add_typer(quick_metric_edit, name='quick_metric_edit')
+    app.add_typer(report_edit, name='report_edit')
+    app.add_typer(learned_edit, name='learned_edit')
+    app.add_typer(verified_query_edit, name='verified_query_edit')
+    app.add_typer(warehouse_edit, name='warehouse_edit')
+    app.command('query_metrics', short_help='Fetch metric data from the warehouse.')(query_metrics)
+    app.command('explain_query', short_help="Show what a query computes without running it: the resolved metrics and dimensions, the effective time window, the filters (including any standing preference folded in) and the compiled SQL. Use it when the user asks what you actually computed, disputes a number, or before proposing a correction. ``warehouse`` picks one of the org's warehouses; omit it for the active one.")(explain_query)
+    app.command('update_context', short_help='Update user preferences (merge, not replace).')(update_context)
+    app.command('export_data', short_help='Export query results or dashboard data to CSV or JSON.')(export_data)
+    app.command('import_manifest', short_help='Import a semantic manifest using replace semantics.')(import_manifest)
+    app.command('render_dashboard', short_help='Render a dashboard.')(render_dashboard)
+    app.command('render_widget', short_help='Render a single widget.')(render_widget)
+    app.command('switch_organization', short_help='Switch this Claude Code (stdio) session or CLI login to a different organization: it becomes the account\'s default org and the next call runs in it. Browse ids via ``read(kind="organizations")``.')(switch_organization)
+    app.command('submit_error_report', short_help='Submit an error report to help improve DataSpring.')(submit_error_report)
+    app.add_typer(secret_edit, name='secret_edit')
+    app.command('run_sql', short_help="Run ONE read-only SQL statement against the org's warehouse and get the rows back, ungoverned.")(run_sql)
+    app.add_typer(datacore_edit, name='datacore_edit')
+    app.add_typer(datacore_run, name='datacore_run')