dataspring-cli 0.4.2__tar.gz → 0.4.3__tar.gz

{dataspring_cli-0.4.2 → dataspring_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dataspring-cli
-Version: 0.4.2
+Version: 0.4.3
 Summary: DataSpring CLI - Query metrics and manage dashboards from the terminal
 Project-URL: Homepage, https://dataspring.app
 Project-URL: Documentation, https://dataspring.app/docs

{dataspring_cli-0.4.2 → dataspring_cli-0.4.3}/cli/bundled_manifest.py

@@ -6,7 +6,7 @@ the server's to say whether the server has operations this CLI does not
 know. tests/test_skills_surface.py asserts it is current.
 """
 
-MANIFEST_HASH = "b9fdc845fd9d3a22cea19e234b330e7e41d17f5d5ba6b5e1c713123d38109a6d"
+MANIFEST_HASH = "e61e4a47f3c193beb2f6d731efde82839f5e62788bfa18560277459487bb26a7"
 TOOL_KEYS = (
     "business_context_edit",
     "semantic_model_edit",

{dataspring_cli-0.4.2 → dataspring_cli-0.4.3}/cli/contract.py

@@ -54,6 +54,8 @@ _EXPECT_VERSION_DOC = (
 
 
 class CreateSemanticModelAction(DispatchParams):
+    """Create a semantic model (admin/owner)."""
+
     action: Literal["create"]
     model_data: dict = Field(
         description="Full semantic-model definition (name, measures, dimensions, entities)"
@@ -62,6 +64,8 @@ class CreateSemanticModelAction(DispatchParams):
 
 
 class UpdateSemanticModelAction(DispatchParams):
+    """Change a semantic model (admin/owner). On an imported one a change to how it computes answers a dbt YAML proposal and writes nothing; descriptions write at once."""
+
     action: Literal["update"]
     name: str
     updates: dict
@@ -77,6 +81,8 @@ class UpdateSemanticModelAction(DispatchParams):
 
 
 class DeleteSemanticModelAction(DispatchParams):
+    """Delete a semantic model (admin/owner)."""
+
     action: Literal["delete"]
     name: str
     expect_version: str | None = Field(default=None, description=_EXPECT_VERSION_DOC)
@@ -113,12 +119,16 @@ class SemanticModelEditParams(DispatchParams):
 
 
 class CreateMetricAction(DispatchParams):
+    """Create a metric, native to DataSpring (admin/owner). A ratio's numerator and denominator, a derived metric's inputs and a cumulative or conversion metric's base are metrics, not measures."""
+
     action: Literal["create"]
     metric_data: dict = Field(description="Metric definition (name, type, type_params)")
     expect_version: str | None = Field(default=None, description=_EXPECT_VERSION_DOC)
 
 
 class UpdateMetricAction(DispatchParams):
+    """Change a metric (admin/owner). On an imported one a change to how it computes answers a dbt YAML proposal and writes nothing; descriptions write at once."""
+
     action: Literal["update"]
     name: str
     updates: dict
@@ -134,12 +144,16 @@ class UpdateMetricAction(DispatchParams):
 
 
 class DeleteMetricAction(DispatchParams):
+    """Delete a metric (admin/owner; irreversible)."""
+
     action: Literal["delete"]
     name: str
     expect_version: str | None = Field(default=None, description=_EXPECT_VERSION_DOC)
 
 
 class PreviewMetricAction(DispatchParams):
+    """Test a metric before saving (any role; writes nothing): sample query results or validation errors, plus the `dbt_yaml` that would be committed for it."""
+
     action: Literal["preview"]
     metric_data: dict = Field(description="Metric definition to preview")
     sample_query: dict | None = Field(
@@ -178,6 +192,8 @@ class MetricEditParams(DispatchParams):
 
 
 class CreateQuickMetricAction(DispatchParams):
+    """Save a personal quick metric: arithmetic over existing metrics, queried as `qm:<name>`."""
+
     action: Literal["create"]
     name: str = Field(description='Metric name (e.g., "revenue_per_order")')
     expression: str = Field(
@@ -187,6 +203,8 @@ class CreateQuickMetricAction(DispatchParams):
 
 
 class UpdateQuickMetricAction(DispatchParams):
+    """Change one of your quick metrics."""
+
     action: Literal["update"]
     metric_id: str
     name: str | None = None
@@ -195,6 +213,8 @@ class UpdateQuickMetricAction(DispatchParams):
 
 
 class DeleteQuickMetricAction(DispatchParams):
+    """Delete one of your quick metrics."""
+
     action: Literal["delete"]
     metric_id: str
 
@@ -565,9 +585,11 @@ DatacoreKind = Literal["connection", "pipeline", "model"]
 
 
 class ApplyDatacoreFileAction(DispatchParams):
-    """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``."""
+    """Write one workspace file whole (create or replace): a dbt project file
+    as ``content``; a connection or pipeline as ``content`` (its YAML text,
+    stored exactly as sent, comments and layout kept) or as a ``document``
+    (an object, stored as a fresh dump), validated against its schema and
+    the catalog either way."""
 
     action: Literal["apply"]
     kind: DatacoreKind = Field(description="connection (admin), pipeline (admin) or model (member)")
@@ -582,14 +604,24 @@ class ApplyDatacoreFileAction(DispatchParams):
             "Secrets are named, never valued; every name must exist"
         ),
     )
-    content: str | None = Field(default=None, description="kind model: the whole file content")
+    content: str | None = Field(
+        default=None,
+        description=(
+            "The whole file as text. kind model: required. kind connection or pipeline: the YAML "
+            "text, validated like a document and stored byte for byte (comments and layout kept); "
+            "give content or document, not both"
+        ),
+    )
     expect_version: str | None = Field(default=None, description=_DATACORE_VERSION_DOC)
 
 
 class PatchDatacoreFileAction(DispatchParams):
     """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)."""
+    check), or a YAML file under models/ (not SQL). Only the lines of the
+    keys the patch changes are rewritten; every other line, comments and
+    indentation included, stays as written (an answer with ``reformatted``
+    says the file had to be rewritten whole)."""
 
     action: Literal["patch"]
     kind: DatacoreKind = Field(description="connection (admin), pipeline (admin) or model (member)")
@@ -620,13 +652,15 @@ class DatacoreEditParams(DispatchParams):
 
 
 class CheckDatacoreAction(DispatchParams):
-    """Check the current draft; no arguments beyond an optional note."""
+    """Check the current draft (member): compile every pipeline, build the changed dbt models into <org>_dev with their tests, and validate the semantic manifest per metric. Nothing reaches production."""
 
     action: Literal["check"]
     note: str | None = Field(default=None, description="Optional note, recorded on the check run")
 
 
 class DeployDatacoreAction(DispatchParams):
+    """Promote the checked draft to deployed (admin), or roll back to an earlier deployed snapshot; then_build also rebuilds changed models."""
+
     action: Literal["deploy"]
     snapshot: str | None = Field(
         default=None,
@@ -664,6 +698,8 @@ class RunCursorParams(DispatchParams):
 
 
 class RunPipelineAction(DispatchParams):
+    """Load a pipeline now (admin): its own window, a given window, or a chunked backfill whose chunks run back to back."""
+
     action: Literal["run"]
     pipeline: str = Field(description="Pipeline name (a deployed pipelines/<name>.yaml)")
     window: RunWindowParams | None = Field(
@@ -677,7 +713,11 @@ class RunPipelineAction(DispatchParams):
     cursor: RunCursorParams | None = Field(default=None, description="{from: <value>}: a cursor to re-pull from")
     backfill_chunk: str | None = Field(
         default=None,
-        description="Chunk size for a windowed run: 7d, 2w or 1M (calendar months, the default)",
+        description=(
+            "Chunk size for a windowed run: 7d, 2w or 1M (calendar months, the default). Every chunk before the last "
+            "loads only the windowed resources (and the ones they read rows from) and skips its dbt step, each skip "
+            "recorded with its reason on the child run; the last chunk loads every resource and builds the models once"
+        ),
     )
 
 
@@ -703,6 +743,8 @@ class BuildModelsAction(DispatchParams):
 
 
 class ResetPipelineAction(DispatchParams):
+    """Delete a pipeline's dlt state and drop its raw tables (admin; irreversible)."""
+
     action: Literal["reset"]
     pipeline: str = Field(description="The pipeline whose dlt state and raw tables to remove")
     approve: bool = Field(
@@ -712,6 +754,8 @@ class ResetPipelineAction(DispatchParams):
 
 
 class CancelRunAction(DispatchParams):
+    """Stop a queued or running run, or a whole backfill (admin); the schedule fires again at its next slot."""
+
     action: Literal["cancel"]
     run_id: str = Field(
         description=(
@@ -1160,12 +1204,17 @@ class RunSqlParams(DispatchParams):
 
     sql: str = Field(
         description=(
-            "One SQL statement (BigQuery Standard SQL on a managed warehouse). "
-            "Name tables as <org>_marts.<table>, <org>_core.<table> or "
-            "<org>_staging.<table>, <org> being the organization id with every "
-            "hyphen as an underscore (acme-dk is acme_dk_marts); the identity it runs as can read those and "
-            "nothing else, so a write or a reach outside them is refused by "
-            "the warehouse."
+            "One SQL statement (BigQuery Standard SQL on a managed warehouse), or a "
+            "script of several separated by ';' whose last statement's rows are "
+            "returned (CREATE TEMP TABLE ... ; SELECT ... works: temp tables are the "
+            "scratch space, gone when the script ends). Name tables as "
+            "<org>_marts.<table>, <org>_core.<table>, <org>_staging.<table>, "
+            "<org>_raw.<table> (what the loads wrote) or <org>_dev.<table> (what the "
+            "last datacore check built; expire after 7 days), <org> being the "
+            "organization id with every hyphen as an underscore (acme-dk is "
+            "acme_dk_marts); the identity it runs as can read those five datasets of "
+            "its own org and nothing else, so a write to a dataset or a reach outside "
+            "them is refused by the warehouse."
         )
     )
     warehouse: str | None = Field(

{dataspring_cli-0.4.2 → dataspring_cli-0.4.3}/cli/generated.py

@@ -135,18 +135,18 @@ def business_context_edit__append(
 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.')
+@semantic_model_edit.command('create', short_help='Create a semantic model (admin/owner).')
 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."""
+    """Create a semantic model (admin/owner)."""
     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.')
+@semantic_model_edit.command('update', short_help='Change a semantic model (admin/owner). On an imported one a change to how it computes answers a dbt YAML proposal and writes nothing; descriptions write at once.')
 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)')],
@@ -155,18 +155,18 @@ def semantic_model_edit__update(
     from_file: FromFile = None,
     output: Output = None,
 ) -> None:
-    """`semantic_model_edit` update."""
+    """Change a semantic model (admin/owner). On an imported one a change to how it computes answers a dbt YAML proposal and writes nothing; descriptions write at once."""
     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.')
+@semantic_model_edit.command('delete', short_help='Delete a semantic model (admin/owner).')
 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."""
+    """Delete a semantic model (admin/owner)."""
     run_tool('semantic_model_edit', contract.SemanticModelEditParams, 'delete', {'name': name, 'expect_version': expect_version}, from_file=from_file, output=output)
 
 
@@ -188,18 +188,18 @@ def semantic_model_edit__preview(
 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.')
+@metric_edit.command('create', short_help="Create a metric, native to DataSpring (admin/owner). A ratio's numerator and denominator, a derived metric's inputs and a cumulative or conversion metric's base are metrics, not measures.")
 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."""
+    """Create a metric, native to DataSpring (admin/owner). A ratio's numerator and denominator, a derived metric's inputs and a cumulative or conversion metric's base are metrics, not measures."""
     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.')
+@metric_edit.command('update', short_help='Change a metric (admin/owner). On an imported one a change to how it computes answers a dbt YAML proposal and writes nothing; descriptions write at once.')
 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)')],
@@ -208,29 +208,29 @@ def metric_edit__update(
     from_file: FromFile = None,
     output: Output = None,
 ) -> None:
-    """`metric_edit` update."""
+    """Change a metric (admin/owner). On an imported one a change to how it computes answers a dbt YAML proposal and writes nothing; descriptions write at once."""
     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.')
+@metric_edit.command('delete', short_help='Delete a metric (admin/owner; irreversible).')
 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."""
+    """Delete a metric (admin/owner; irreversible)."""
     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.')
+@metric_edit.command('preview', short_help='Test a metric before saving (any role; writes nothing): sample query results or validation errors, plus the `dbt_yaml` that would be committed for it.')
 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."""
+    """Test a metric before saving (any role; writes nothing): sample query results or validation errors, plus the `dbt_yaml` that would be committed for it."""
     run_tool('metric_edit', contract.MetricEditParams, 'preview', {'metric_data': J(metric_data), 'sample_query': J(sample_query)}, from_file=from_file, output=output)
 
 
@@ -253,7 +253,7 @@ def metric_edit__impact(
 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.')
+@quick_metric_edit.command('create', short_help='Save a personal quick metric: arithmetic over existing metrics, queried as `qm:<name>`.')
 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")')],
@@ -261,11 +261,11 @@ def quick_metric_edit__create(
     from_file: FromFile = None,
     output: Output = None,
 ) -> None:
-    """`quick_metric_edit` create."""
+    """Save a personal quick metric: arithmetic over existing metrics, queried as `qm:<name>`."""
     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.')
+@quick_metric_edit.command('update', short_help='Change one of your quick metrics.')
 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,
@@ -274,17 +274,17 @@ def quick_metric_edit__update(
     from_file: FromFile = None,
     output: Output = None,
 ) -> None:
-    """`quick_metric_edit` update."""
+    """Change one of your quick metrics."""
     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.')
+@quick_metric_edit.command('delete', short_help='Delete one of your quick metrics.')
 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."""
+    """Delete one of your quick metrics."""
     run_tool('quick_metric_edit', contract.QuickMetricEditParams, 'delete', {'metric_id': metric_id}, from_file=from_file, output=output)
 
 
@@ -556,6 +556,13 @@ def query_metrics(
     A ``where`` you send on the same dimension overrides that standing
     filter and nothing is reported for it — say that too.
 
+    A grouped query is clamped to the window asked for. When that cuts a
+    bucket short (a year to date at year grain is one row labelled with the
+    whole year), the answer carries ``effective_window``: ``covered`` (the
+    days the numbers cover) and ``partial_periods`` (each short bucket and
+    the days it holds). Name those days beside the number, and compare with
+    ``compare_to``, which measures the same days, never with a whole period.
+
     Examples:
     - Monthly revenue: metrics=['total_revenue'], grain='month', start_date='2024-01-01'
     - Revenue by region: metrics=['total_revenue'], dimensions=['region']
@@ -770,7 +777,7 @@ def secret_edit__reveal(
 
 
 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>, <org> being the organization id with every hyphen as an underscore (acme-dk is acme_dk_marts); the identity it runs as can read those and nothing else, so a write or a reach outside them is refused by the warehouse.')],
+    sql: Annotated[str, typer.Option('--sql', help="One SQL statement (BigQuery Standard SQL on a managed warehouse), or a script of several separated by ';' whose last statement's rows are returned (CREATE TEMP TABLE ... ; SELECT ... works: temp tables are the scratch space, gone when the script ends). Name tables as <org>_marts.<table>, <org>_core.<table>, <org>_staging.<table>, <org>_raw.<table> (what the loads wrote) or <org>_dev.<table> (what the last datacore check built; expire after 7 days), <org> being the organization id with every hyphen as an underscore (acme-dk is acme_dk_marts); the identity it runs as can read those five datasets of its own org and nothing else, so a write to a dataset 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,
@@ -778,21 +785,27 @@ def run_sql(
     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.
+    """Run read-only SQL (one statement, or a script whose last statement
+    answers) 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).
+    look at a mart, a join the models do not make, checking a load, the
+    rows a staging model or a datacore check produced. 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;
+    identity (``t-<org>-reader@``), which reads the org's own marts, core,
+    staging, raw (what the loads wrote) and dev (what the last
+    ``datacore_run check`` built; tables there expire after 7 days) and
+    nothing else, so a write to a dataset, an export or a reach outside
+    those is refused by BigQuery itself. A script of several statements
+    runs as one job and answers the last one's rows; ``CREATE TEMP TABLE``
+    in it is scratch space that ends with the script. 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.
@@ -808,24 +821,26 @@ def run_sql(
 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``.')
+@datacore_edit.command('apply', short_help='Write one workspace file whole (create or replace): a dbt project file as ``content``; a connection or pipeline as ``content`` (its YAML text, stored exactly as sent, comments and layout kept) or as a ``document`` (an object, stored as a fresh dump), validated against its schema and the catalog either way.')
 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,
+    content: Annotated[Optional[str], typer.Option('--content', help='The whole file as text. kind model: required. kind connection or pipeline: the YAML text, validated like a document and stored byte for byte (comments and layout kept); give content or document, not both')] = 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``.
+    """Write one workspace file whole (create or replace): a dbt project file
+    as ``content``; a connection or pipeline as ``content`` (its YAML text,
+    stored exactly as sent, comments and layout kept) or as a ``document``
+    (an object, stored as a fresh dump), validated against its schema and
+    the catalog either way.
     """
     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).')
+@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). Only the lines of the keys the patch changes are rewritten; every other line, comments and indentation included, stays as written (an answer with ``reformatted`` says the file had to be rewritten whole).')
 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/')],
@@ -836,7 +851,10 @@ def datacore_edit__patch(
 ) -> 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).
+    check), or a YAML file under models/ (not SQL). Only the lines of the
+    keys the patch changes are rewritten; every other line, comments and
+    indentation included, stays as written (an answer with ``reformatted``
+    says the file had to be rewritten whole).
     """
     run_tool('datacore_edit', contract.DatacoreEditParams, 'patch', {'kind': kind, 'name': name, 'patch': J(patch), 'expect_version': expect_version}, from_file=from_file, output=output)
 
@@ -861,17 +879,17 @@ def datacore_edit__delete(
 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.')
+@datacore_run.command('check', short_help='Check the current draft (member): compile every pipeline, build the changed dbt models into <org>_dev with their tests, and validate the semantic manifest per metric. Nothing reaches production.')
 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."""
+    """Check the current draft (member): compile every pipeline, build the changed dbt models into <org>_dev with their tests, and validate the semantic manifest per metric. Nothing reaches production."""
     run_tool('datacore_run', contract.DatacoreRunParams, 'check', {'note': note}, from_file=from_file, output=output)
 
 
-@datacore_run.command('deploy', short_help='`datacore_run` deploy.')
+@datacore_run.command('deploy', short_help='Promote the checked draft to deployed (admin), or roll back to an earlier deployed snapshot; then_build also rebuilds changed models.')
 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,
@@ -880,20 +898,20 @@ def datacore_run__deploy(
     from_file: FromFile = None,
     output: Output = None,
 ) -> None:
-    """`datacore_run` deploy."""
+    """Promote the checked draft to deployed (admin), or roll back to an earlier deployed snapshot; then_build also rebuilds changed models."""
     run_tool('datacore_run', contract.DatacoreRunParams, 'deploy', {'snapshot': snapshot, 'note': note, 'then_build': then_build, 'build_select': build_select}, from_file=from_file, output=output)
 
 
-@datacore_run.command('run', short_help='`datacore_run` run.')
+@datacore_run.command('run', short_help='Load a pipeline now (admin): its own window, a given window, or a chunked backfill whose chunks run back to back.')
 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. Both ends are inclusive days, and so is every chunk; a resource whose API reads its end bound as exclusive declares `window.end: exclusive` in the pipeline and is sent the day after each chunk's last day (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,
+    backfill_chunk: Annotated[Optional[str], typer.Option('--backfill-chunk', help='Chunk size for a windowed run: 7d, 2w or 1M (calendar months, the default). Every chunk before the last loads only the windowed resources (and the ones they read rows from) and skips its dbt step, each skip recorded with its reason on the child run; the last chunk loads every resource and builds the models once')] = None,
     from_file: FromFile = None,
     output: Output = None,
 ) -> None:
-    """`datacore_run` run."""
+    """Load a pipeline now (admin): its own window, a given window, or a chunked backfill whose chunks run back to back."""
     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)
 
 
@@ -908,24 +926,24 @@ def datacore_run__build(
     run_tool('datacore_run', contract.DatacoreRunParams, 'build', {'pipeline': pipeline, 'select': select}, from_file=from_file, output=output)
 
 
-@datacore_run.command('reset', short_help='`datacore_run` reset.')
+@datacore_run.command('reset', short_help="Delete a pipeline's dlt state and drop its raw tables (admin; irreversible).")
 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."""
+    """Delete a pipeline's dlt state and drop its raw tables (admin; irreversible)."""
     run_tool('datacore_run', contract.DatacoreRunParams, 'reset', {'pipeline': pipeline, 'approve': approve}, from_file=from_file, output=output)
 
 
-@datacore_run.command('cancel', short_help='`datacore_run` cancel.')
+@datacore_run.command('cancel', short_help='Stop a queued or running run, or a whole backfill (admin); the schedule fires again at its next slot.')
 def datacore_run__cancel(
     run_id: Annotated[str, typer.Option('--run-id', help="The queued or running run to stop, or a backfill's parent run (its running child is stopped and no further chunk starts); ids from dataspring://datacore/runs")],
     from_file: FromFile = None,
     output: Output = None,
 ) -> None:
-    """`datacore_run` cancel."""
+    """Stop a queued or running run, or a whole backfill (admin); the schedule fires again at its next slot."""
     run_tool('datacore_run', contract.DatacoreRunParams, 'cancel', {'run_id': run_id}, from_file=from_file, output=output)
 
 
@@ -1167,7 +1185,7 @@ def mount(app: typer.Typer) -> None:
     app.command('import_manifest', short_help='Import a semantic manifest using replace semantics.')(import_manifest)
     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.command('run_sql', short_help="Run read-only SQL (one statement, or a script whose last statement answers) 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')
     app.add_typer(tenant_edit, name='tenant_edit')