mammoth-cli 2.2.75__tar.gz → 2.2.77__tar.gz

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.75
+Version: 2.2.77
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -18,7 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.9,>=0.8.39
+Requires-Dist: mammoth-io<0.9,>=0.8.41
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.2.75"
+__version__ = "2.2.77"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/app.py

@@ -14,6 +14,7 @@ positionals and options are added per family as each handler is implemented.
 
 from __future__ import annotations
 
+import importlib
 import inspect
 import json
 import re
@@ -202,6 +203,7 @@ _SUBGROUP_DESCRIPTIONS = {
     "dashboard video": "Export a dashboard as a video.",
     "data-app user": "List and remove the users of a data app.",
     "dataset broken-rows": "List and resolve rows that failed to load.",
+    "dataset definition": "List, save and remove what terms mean for a dataset.",
     "dataset file-settings": "Read, update and undo a dataset's file settings.",
     "dataset interpretation": "Preview and confirm how a file is interpreted.",
     "parameter group": "Create, list, update, reorder and delete parameter groups.",
@@ -1178,7 +1180,8 @@ def _dry_run(handler: Handler, invocation: Invocation) -> tuple[Any, dict[str, A
 
 
 #: One-line help for commands that share the generic ``generated_dashboard`` handler, whose
-#: docstring describes the dispatch, not the command.
+#: docstring describes the dispatch, not the command. A command listed here overrides
+#: the SDK method summary :func:`_sdk_method_summary` gives every other generated command.
 _GENERATED_SUMMARIES = {
     "auth.connected-apps.list": "List the apps connected to your account; each id is a grant id.",
     "auth.connected-apps.revoke": (
@@ -1246,6 +1249,24 @@ _GENERATED_SUMMARIES = {
 }
 
 
+def _sdk_method_summary(command_id: str) -> str:
+    """First docstring line of the SDK method a generated command calls.
+
+    The generic ``generated_dashboard`` handler's own docstring describes the
+    dispatch, so these commands take their help from the SDK method instead.
+    Raises when the manifest has no such method or it has no docstring.
+    """
+    record = command_by_id(command_id)
+    if record is None:
+        raise LookupError(f"{command_id}: no manifest record")
+    module_name, class_name, method_name = str(record["sdk_symbol"]).rsplit(".", 2)
+    method = getattr(getattr(importlib.import_module(module_name), class_name), method_name)
+    doc = inspect.getdoc(method)
+    if not doc:
+        raise LookupError(f"{command_id}: {record['sdk_symbol']} has no docstring")
+    return doc.splitlines()[0].strip().replace("``", "'")
+
+
 def live_command_summary(command_id: str) -> str | None:
     """The backing handler's docstring first line, the lead of a command's help.
 
@@ -1255,6 +1276,8 @@ def live_command_summary(command_id: str) -> str | None:
     if command_id in _GENERATED_SUMMARIES:
         return _GENERATED_SUMMARIES[command_id]
     handler = HANDLERS.get(command_id) or BESPOKE.get(command_id)
+    if getattr(handler, "__name__", None) == "generated_dashboard":
+        return _sdk_method_summary(command_id)
     doc = inspect.getdoc(handler) if handler is not None else None
     if not doc:
         return None

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities.md

@@ -1,7 +1,7 @@
 # What is proven on release
 
 Generated from `docs/release-capability-matrix.json`; do not edit by hand.
-The CLI publishes 714 commands. 516 of them bind one of the 545 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (`view transform *` commands submit through `view.task.add`, except `rename-columns` and `sort`, which set view display properties through `view.update`). 262 bound commands ran once successfully on release, 1 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer. Use an untried command normally: confirm a write with the user first, check its result with a read afterwards, and never refuse a command only because it is untried.
+The CLI publishes 747 commands. 516 of them bind one of the 545 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (`view transform *` commands submit through `view.task.add`, except `rename-columns` and `sort`, which set view display properties through `view.update`). 262 bound commands ran once successfully on release, 1 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer. Use an untried command normally: confirm a write with the user first, check its result with a read afterwards, and never refuse a command only because it is untried.
 
 Status meanings:
 

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/bundled_skill/mammoth-cli/references/command-index.md

@@ -1,6 +1,6 @@
 # Published CLI command catalog
 
-This generated catalog is a lookup table for every command in the published CLI manifest, currently 740; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
+This generated catalog is a lookup table for every command in the published CLI manifest, currently 747; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
 
 Load only the applicable domain file:
 
@@ -27,7 +27,7 @@ Load only the applicable domain file:
 - [dashboard-style](commands/dashboard-style.md) — 10 published commands
 - [dashboard](commands/dashboard.md) — 108 published commands
 - [data-app](commands/data-app.md) — 12 published commands
-- [dataset](commands/dataset.md) — 22 published commands
+- [dataset](commands/dataset.md) — 27 published commands
 - [doctor](commands/doctor.md) — 1 published commands
 - [external-key](commands/external-key.md) — 4 published commands
 - [file](commands/file.md) — 11 published commands
@@ -52,7 +52,7 @@ Load only the applicable domain file:
 - [user](commands/user.md) — 8 published commands
 - [version](commands/version.md) — 1 published commands
 - [view-transform](commands/view-transform.md) — 34 published commands
-- [view](commands/view.md) — 101 published commands
+- [view](commands/view.md) — 103 published commands
 - [webhook](commands/webhook.md) — 7 published commands
 - [workflow](commands/workflow.md) — 20 published commands
 - [workspace](commands/workspace.md) — 31 published commands

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dataset.md

@@ -52,6 +52,16 @@ Execution is unavailable for the current contract and returns `unsupported_contr
 
 Known restriction: BLOCKED[B07 DATASET_PATCH_UNTYPED]; reserved, not registered.
 
+### `dataset.column-stats`
+
+Run: `mammoth dataset column-stats`. Exact input fields: `mammoth schema get dataset.column-stats`.
+
+Example: `mammoth dataset column-stats`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DatasetColumnStatsResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `dataset.create`
 
 Run: `mammoth dataset create`. Exact input fields: `mammoth schema get dataset.create`.
@@ -82,6 +92,36 @@ Result: `DatasetDataResult`; mutation `read`, confirmation `none`, wait policy `
 
 Status on release: ran once on CLI 1.1.10 — Bounded retained-resource read with published CLI 1.1.10 and explicit timeout=30,poll_interval=1 returned 100 rows and five headers for dataset 28. No Full claim: retained ETL-owned resource and no option/error/lifecycle matrix beyond this read.
 
+### `dataset.definition.add`
+
+Run: `mammoth dataset definition add`. Exact input fields: `mammoth schema get dataset.definition.add`.
+
+Example: `mammoth dataset definition add 123 --input '{"term": "late", "definition": "delivered more than 5 days after shipped_date"}'`. Illustrative only: append `--yes --confirm <EXACT_TARGET>` after observing the target.
+
+Result: `DatasetDefinitionAddResult`; mutation `benign_mutation`, confirmation `confirm_target`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `dataset.definition.list`
+
+Run: `mammoth dataset definition list`. Exact input fields: `mammoth schema get dataset.definition.list`.
+
+Example: `mammoth dataset definition list 123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DatasetDefinitionListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `dataset.definition.remove`
+
+Run: `mammoth dataset definition remove`. Exact input fields: `mammoth schema get dataset.definition.remove`.
+
+Example: `mammoth dataset definition remove 123 a1b2c3d4`. Illustrative only: append `--yes` after observing an owned target.
+
+Result: `DatasetDefinitionRemoveResult`; mutation `benign_mutation`, confirmation `prompt_or_yes`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `dataset.delete`
 
 Run: `mammoth dataset delete`. Exact input fields: `mammoth schema get dataset.delete`.
@@ -192,6 +232,16 @@ Result: `DatasetRestoreResult`; mutation `benign_mutation`, confirmation `none`,
 
 Status on release: ran once on CLI 2.0.14 — write sweep 2026-09-18: exit 0 on release with CLI 2.0.14. job 312 restore_datasource -> status success. dataset list --project 21 confirms dataset 49 (name 'stores.csv 2') is back and visible alongside 48. Single invocation only.
 
+### `dataset.schema-diff`
+
+Run: `mammoth dataset schema-diff`. Exact input fields: `mammoth schema get dataset.schema-diff`.
+
+Example: `mammoth dataset schema-diff 10 11`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DatasetSchemaDiffResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `dataset.search`
 
 Run: `mammoth dataset search`. Exact input fields: `mammoth schema get dataset.search`.

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -252,6 +252,16 @@ Result: `ViewDataCompareResult`; mutation `read`, confirmation `none`, wait poli
 
 Status on release: untried; no live run recorded.
 
+### `view.data.drivers`
+
+Run: `mammoth view data drivers`. Exact input fields: `mammoth schema get view.data.drivers`.
+
+Example: `mammoth view data drivers 123 --input '{"measure": {"column": "revenue", "function": "SUM"}, "date_column": "sale_date", "compare": ["2026-07", "2026-08"], "by": ["store", "category"]}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `ViewDataDriversResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `view.data.explore`
 
 Run: `mammoth view data explore`. Exact input fields: `mammoth schema get view.data.explore`.
@@ -262,6 +272,16 @@ Result: `ViewDataExploreResult`; mutation `read`, confirmation `none`, wait poli
 
 Status on release: untried; no live run recorded.
 
+### `view.data.forecast`
+
+Run: `mammoth view data forecast`. Exact input fields: `mammoth schema get view.data.forecast`.
+
+Example: `mammoth view data forecast 123 --input '{"measure": {"column": "revenue", "function": "SUM"}, "date_column": "sale_date", "unit": "month", "periods": 2}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `ViewDataForecastResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `view.data.get`
 
 Run: `mammoth view data get`. Exact input fields: `mammoth schema get view.data.get`.

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/workflow.md

@@ -66,7 +66,7 @@ Status on release: untried; no live run recorded.
 
 Run: `mammoth workflow canvas`. Exact input fields: `mammoth schema get workflow.canvas`.
 
-Example: `mammoth workflow canvas 12 --input '{"canvas_state": {"proposed_changes": [{"op": "add_view", "dataset_id": 415, "name": "Urgent tickets", "ref": "urgent"}, {"op": "send_to_new_dataset", "dataset_id": 415, "view_ref": "urgent", "name": "Urgent tickets by team"}]}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth workflow canvas 12 --input '{"canvas_state": {"proposed_changes": [{"op": "add_view", "dataset_id": 415, "name": "Urgent tickets", "ref": "urgent"}, {"op": "add_step", "view_ref": "urgent", "transform": "filter", "params": {"condition": {"column": "Priority", "operator": "EQ", "value": "Urgent"}}, "label": "Keep urgent tickets"}, {"op": "send_to_new_dataset", "dataset_id": 415, "view_ref": "urgent", "name": "Urgent tickets by team"}]}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `WorkflowCanvasResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/bundled_skill/mammoth-cli/references/operations.md

@@ -44,6 +44,18 @@ returns the project's datasets whose name, column names or sampled column
 values contain TERM, each with the matched column and value. `dataset find`
 and `browse` search match names only. A `browse` search hit carries `dataset_id` or `view_id`: use those,
 never the tree `id`.
+To check missing values or blanks across a project's datasets, run
+`dataset column-stats` once instead of profiling each view: it returns every
+dataset's columns with their blank count and share, type and distinct count,
+from stats stored at the last load or pipeline run.
+When the user states what a term means for a dataset ("late means delivered
+more than 5 days after shipped_date"), save it with
+`dataset definition add DATASET_ID --input '{"term": "...", "definition": "..."}'`,
+written in the dataset's real column names. A definition is shared by
+everyone's chats on that dataset, so the save needs
+`--yes --confirm DATASET_ID`, and a definition for an existing term replaces
+it. Do not save one for a one-off question. `dataset definition list` and
+`dataset definition remove DATASET_ID DEFINITION_ID` read and drop them.
 
 ```bash
 mammoth capability find "transform"
@@ -130,16 +142,19 @@ NAME --input '{"seed_datasource_id": ROOT_DATASET_ID}'`, which returns its
 record id. `workflow cleanup` deletes the project's orphaned skeleton
 ("ghost") workflows (destructive; needs `--yes`).
 
-To only *suggest* a workflow's shape for the user to review, use `workflow
+To only *suggest* changes to a workflow for the user to review, use `workflow
 canvas WORKFLOW_ID --input '{"canvas_state": {"proposed_changes": [...]}}'`.
-Nothing is built until the user presses Save on the Workflows canvas; tell
-them the changes are waiting there. Changes are `add_view`, `rename_view`,
-`trash_view`, `rename_dataset`, `trash_dataset`, `send_to_new_dataset`,
-`send_to_dataset`, `join` and `export` (fields per op: `schema get
-workflow.canvas`). A later change in the same call can point at an earlier
-one: give the earlier change a `ref`, then use `view_ref`, `dataset_ref` or
-`target_dataset_ref` instead of an id. It cannot add filters, calculations or
-other tasks; if the request needs those, build it with `view` commands.
+Nothing is built until the user presses Save on the Workflows canvas, which
+builds every change in flow order; tell them the changes are waiting there.
+Changes are `add_view`, `rename_view`, `trash_view`, `rename_dataset`,
+`trash_dataset`, `send_to_new_dataset`, `send_to_dataset`, `join`, `export`,
+and, for the steps inside a view, `add_step`, `update_step` and `remove_step`
+(fields per op: `schema get workflow.canvas`). A later change in the same call
+can point at an earlier one: give the earlier change a `ref`, then use
+`view_ref`, `dataset_ref` or `target_dataset_ref` instead of an id. Propose the
+filters, calculations and other tasks a view needs as `add_step` changes in the
+same call (`transform` is a `view transform` kind, `params` its `--input`),
+never as `view` commands run afterwards.
 
 Draft mode is server-side batching for view pipeline edits. Enter, inspect
 status, submit, and verify pipeline state; discard only with the required
@@ -158,6 +173,18 @@ applied.
   put a card on a dashboard, say it to `dashboard chat edit`. Figures
   from `explore` and `view data aggregate` are rounded for display (2
   decimals; 4 below 1); `view data compare` keeps full precision.
+- "Why did revenue drop from July to August", "what drove the change": one
+  `view data drivers VIEW_ID` call, not a series of aggregates. It returns
+  each period's total and row count, the change, whether it came from volume
+  or value per row, and per `by` column the groups that moved most with their
+  signed `share_of_change`; `partial_period` names a period the data does not
+  cover to its end.
+- "Forecast", "what will revenue be in October": `view data forecast
+  VIEW_ID` (a linear trend over the complete months, quarters or weeks, with a
+  95% range; seasonal only with two full cycles). A last period the data does
+  not cover to its end is left out and reported as `excluded_partial`, and it
+  is the first period forecast: for October with data ending mid-September,
+  pass `periods` 2. Never scale a partial period up by its days.
 - "Who changed X": `activity list` (a change list of time, user, action and a
   `path` naming the dataset and view). Filter with `resource_id` in the log's
   typed form, `dataview_<id>` or `datasource_<id>` (a bare number matches

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -103,8 +103,9 @@ mammoth view transform math VIEW_ID --project PROJECT_ID \
   revenue. Say how many there are in your report.
 - A generate or edit result may carry `deliverable_check`: `money_not_shown`
   (with the `math` command in `fix`), `unit_price_summed`,
-  `columns_not_on_dashboard` (view columns added after the dashboard was made)
-  and one `blank_values` entry for each column on the board that has blanks.
+  `columns_not_on_dashboard` (view columns added after the dashboard was made),
+  `count_titled_as_rate` (a card or tile counts rows, but its title reads as a
+  rate) and one `blank_values` entry for each column on the board that has blanks.
   Fix each warning (add the column, then ask again in words), or say in your
   report why you kept it.
 
@@ -168,6 +169,9 @@ the user to use Download PDF in the app; never retry with `{"data": {}}`.
 not publish: `was_published` stays false until you also run
 `dashboard action DASHBOARD_ID --input '{"action":"publish-presentation"}'`.
 `share` returns `data: null`; read the url slug back with `dashboard get`.
+`dashboard action` with `publish-data` on a board that was never published
+publishes the presentation instead and says so. `share` and `action` print the
+deliverable check in their confirmation text.
 Only then do `dashboard published canvas URL`, `published data URL`,
 `job-by-url URL JOB_ID` and the other `/dashboards/url/...` routes answer;
 before that they return 404 `DASHBOARD_NOT_FOUND`. Legacy widget routes

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/transforms.md

@@ -81,6 +81,11 @@ mammoth view transform math VIEW_ID --project PROJECT_ID \
   --input '{"dataset_id":DATASET_ID,"expression":"GDP / Population","new_column":"GDP per capita"}'
 ```
 
+A TEXT column that writes numbers with a decimal comma (`1.234,5`) converts with
+`"decimal_separator":","` on its `conversions` entry (`thousands_separator`
+defaults to the other mark). `view data profile` lists such a column under
+`summary.mixed_number_format` when its values mix notations.
+
 In a math `expression`, write a multi-word display name bare (`Quantity * Unit
 Price`) or quoted (`Quantity * \"Unit Price\"` inside the JSON string).
 

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/commands/capability.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import re
 from typing import Any
 
+from mammoth_cli.commands.schema import command_scope
 from mammoth_cli.manifest.loader import command_by_id, load_operations
 from mammoth_cli.services.command_contract import resolve_command_contract
 
@@ -85,48 +86,7 @@ def _contract_fields(command: dict[str, Any]) -> dict[str, Any]:
     """
     command_id = str(command.get("command_id", ""))
     resolved = resolve_command_contract(command_id) if command_id else None
-    path = str(command.get("command_path", ""))
-    family = path.split()[0] if path else ""
-    if family in {
-        "project",
-        "dataset",
-        "file",
-        "folder",
-        "view",
-        "batch",
-        "annotation",
-        "dashboard",
-        "automation",
-        "schedule",
-        "snippet",
-        "template",
-        "workflow",
-    }:
-        scope = "project"
-    elif family in {
-        "workspace",
-        "user",
-        "support",
-        "billing",
-        "connector",
-        "client-app",
-        "external-key",
-    }:
-        scope = "workspace"
-    elif family in {
-        "auth",
-        "config",
-        "context",
-        "completion",
-        "doctor",
-        "schema",
-        "capability",
-        "skill",
-        "version",
-    }:
-        scope = "local"
-    else:
-        scope = "profile"
+    scope = command_scope(command)
     # Keep capability discovery aligned with the resolved command contract
     # consumed by runtime admission and binding. The manifest fallback is for
     # genuinely local/bespoke records without a resolvable SDK signature.

{mammoth_cli-2.2.75 → mammoth_cli-2.2.77}/mammoth_cli/commands/dashboard.py

@@ -576,16 +576,30 @@ def dashboard_action(invocation: Invocation) -> HandlerResult:
     dashboard_id = _require_int_positional(invocation, "dashboard id")
     document = _bound_document(invocation)
     action = _require_field(document, "action")
-    enforce_confirmation(
-        invocation,
-        policy=POLICY_YES_ALWAYS,
-        action=f"apply an action to dashboard {dashboard_id}",
-    )
     kwargs: dict[str, Any] = {"dashboard_id": dashboard_id, "action": action}
     assert document is not None
     _forward_optional(document, kwargs, ("params_enabled", "params_view_id"))
     with open_service(invocation) as (service, auth):
+        published = _was_published(service, dashboard_id)
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_YES_ALWAYS,
+            action=f"apply an action to dashboard {dashboard_id}"
+            + _board_findings(invocation, service, auth, dashboard_id),
+        )
+        first_publish = action == "publish-data" and not published
+        if first_publish:
+            kwargs["action"] = "publish-presentation"
         data = service.call(_symbol(invocation), **kwargs)
+    if first_publish:
+        data = {
+            "action": "publish-presentation",
+            "note": (
+                "The board was never published, so publish-data was refused by the "
+                "server; the presentation was published instead."
+            ),
+            "response": data,
+        }
     return data, _meta(invocation, auth.workspace_id)
 
 
@@ -594,19 +608,45 @@ def dashboard_share(invocation: Invocation) -> HandlerResult:
     dashboard_id = _require_int_positional(invocation, "dashboard id")
     document = _bound_document(invocation)
     type_of_auth = _require_field(document, "type_of_auth")
-    enforce_confirmation(
-        invocation,
-        policy=POLICY_YES_ALWAYS,
-        action=f"share dashboard {dashboard_id}",
-    )
     kwargs: dict[str, Any] = {"dashboard_id": dashboard_id, "type_of_auth": type_of_auth}
     assert document is not None
     _forward_optional(document, kwargs, ("users",))
     with open_service(invocation) as (service, auth):
+        unpublished = (
+            " (not published yet: sharing alone does not publish it; run dashboard action "
+            'with {"action":"publish-presentation"} to publish)'
+            if not _was_published(service, dashboard_id)
+            else ""
+        )
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_YES_ALWAYS,
+            action=f"share dashboard {dashboard_id}{unpublished}"
+            + _board_findings(invocation, service, auth, dashboard_id),
+        )
         data = service.call(_symbol(invocation), **kwargs)
     return data, _meta(invocation, auth.workspace_id)
 
 
+def _was_published(service: Any, dashboard_id: int) -> bool:
+    """Whether the board was ever published; ``dashboard get`` carries ``was_published``."""
+    board = _dump_model(service.call(_DASHBOARD_GET, dashboard_id=dashboard_id))
+    return bool(board.get("was_published")) if isinstance(board, dict) else False
+
+
+def _board_findings(invocation: Invocation, service: Any, auth: Any, dashboard_id: int) -> str:
+    """The deliverable check's findings as confirmation text; empty when clean or unreadable."""
+    try:
+        warnings = _deliverable_warnings(invocation, service, auth, dashboard_id)
+    except Exception:  # noqa: BLE001 -- advice must never block the confirmation
+        return ""
+    if not warnings:
+        return ""
+    return " -- deliverable check: " + "; ".join(
+        f"{warning['issue']}: {warning['detail']}" for warning in warnings
+    )
+
+
 def _figure_page_kwargs(page: Any) -> dict[str, Any]:
     """Map the endpoint's ``page`` ({"id"} or {"new_title"}) onto the SDK's page arguments."""
     if not isinstance(page, dict) or set(page) not in ({"id"}, {"new_title"}):
@@ -923,6 +963,7 @@ def _deliverable_warnings(
     )
 
 
+_DASHBOARD_GET = "mammoth.api.dashboards.DashboardsAPI.get"
 _CANVAS_SAVE = "mammoth.api.dashboards.DashboardsAPI.canvas_save"
 _FILTER_KEYS = ("field", "control", "label", "default")