mammoth-cli 2.0.12__tar.gz → 2.0.14__tar.gz

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.12
+Version: 2.0.14
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,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.8,>=0.7.4
+Requires-Dist: mammoth-io<0.8,>=0.7.6
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.13
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/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.0.12"
+__version__ = "2.0.14"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/app.py

@@ -24,6 +24,7 @@ from typing import Annotated, Any
 
 import typer
 from typer._click import exceptions as _typer_click_exceptions
+from typer._click.core import Command as _ClickCommand
 from typer.core import TyperGroup
 
 from mammoth_cli import __version__
@@ -297,6 +298,33 @@ def _usage_error_report(error: Any, tokens: Sequence[str]) -> CliError | None:
     )
 
 
+class _LeafGroup(TyperGroup):
+    """Group for a node that is also an invocable command with positionals.
+
+    Click resolves the first bare token after a group as a subcommand name, so
+    ``mammoth project resource-dependencies 3`` failed with ``No such command
+    '3'`` even though the manifest (and every printed example) takes the
+    project id positionally. When the leading token is not a registered
+    subcommand, keep every token as an argument for the group callback instead;
+    genuine subcommands (``... resource-dependencies update 3``) are unaffected.
+    """
+
+    def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
+        super().parse_args(ctx, args)
+        protected = list(getattr(ctx, "_protected_args", ()) or ())
+        if protected and protected[0] not in self.commands:
+            # Leaf invocation. A group parser stops at the first bare token, so
+            # options after the positional were left unparsed; parse again as a
+            # plain command with interspersed options, keeping the bare tokens
+            # as the callback's positional arguments.
+            ctx.allow_interspersed_args = True
+            ctx.args = _ClickCommand.parse_args(self, ctx, list(args))
+            # Click's own attribute for the pending subcommand token (Click
+            # >= 8.2 made it private); not an SDK member.
+            setattr(ctx, "_protected_args", [])  # noqa: B010
+        return list(ctx.args)
+
+
 class _EnvelopeGroup(TyperGroup):
     """Root group that renders Click usage errors as the machine error envelope.
 
@@ -358,10 +386,10 @@ class _EnvelopeGroup(TyperGroup):
         # group-level classifier (schema get and nested commands rely on the
         # stable missing_argument envelope).
         error_message = error.format_message()
-        is_missing_parameter = isinstance(
-            error, _typer_click_exceptions.MissingParameter
-        ) or error.__class__.__name__ == "MissingParameter" or bool(
-            re.match(r"^Missing argument '[^']+'\.", error_message)
+        is_missing_parameter = (
+            isinstance(error, _typer_click_exceptions.MissingParameter)
+            or error.__class__.__name__ == "MissingParameter"
+            or bool(re.match(r"^Missing argument '[^']+'\.", error_message))
         )
         report = None if is_missing_parameter else _usage_error_report(error, tokens)
         if _output_mode_from_argv(argv) in MACHINE_OUTPUTS:
@@ -393,8 +421,7 @@ class _EnvelopeGroup(TyperGroup):
                         (
                             token.split("=", 1)[0]
                             for token in tokens
-                            if token.startswith("--")
-                            and token.split("=", 1)[0] not in known
+                            if token.startswith("--") and token.split("=", 1)[0] not in known
                         ),
                         None,
                     )
@@ -829,6 +856,7 @@ def build_app() -> typer.Typer:
         if command_id is not None:
             # This node is both a group and an invocable command.
             sub = typer.Typer(
+                cls=_LeafGroup,
                 no_args_is_help=False,
                 invoke_without_command=True,
                 context_settings={"allow_extra_args": True, "ignore_unknown_options": True},

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -65,6 +65,9 @@ the result.
 - **Import, resources, transforms, pipelines, dashboards, exports, or cleanup:**
   [recipes](references/recipes/index.md) and [operations](references/operations.md)
 - **A known command family or exact command:** [command catalog](references/command-index.md)
+- **Whether a route is proven, known-blocked, or untried on release:**
+  [capabilities](references/capabilities.md) — read it before promising a
+  deliverable or reporting a failure as a backend fault
 - **Pause or transfer to another agent:** [handoff](references/handoff.md)
 
 ## Handoff checklist

mammoth_cli-2.0.14/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities.md

@@ -0,0 +1,220 @@
+# What is proven on release
+
+Generated from `docs/release-capability-matrix.json`; do not edit by hand.
+455 API operations have a CLI command. 142 were exercised successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID --output json --no-input`, run it, and treat the structured error envelope as the answer.
+
+Status meanings:
+
+- **verified**: one bounded live run on release returned a success envelope (single path; variants and error paths are usually untested).
+- **not supported**: the backend refuses the route on release; the note says why and what to use instead.
+- **observed blocker**: the last run hit an error; the note quotes it. Re-check before relying on the route, and do not retry the same input.
+- **CLI defect fixed, untried since**: the failure was on the CLI side and this release repairs it; nobody has re-run the route yet.
+- Commands not listed under a family are untried.
+
+The typed `view transform *` commands all submit through `view.task.add`; its row below carries the transformations proven end to end (filter, fill-missing, join, pivot with an exported summary). A transformation not named there has the same untried status as any other command.
+
+## Coverage by family
+
+| Family | Commands | Verified | Not supported | Untried |
+|---|---|---|---|---|
+| `dashboard` | 104 | 66 | 2 | 36 |
+| `view` | 62 | 22 | 0 | 40 |
+| `support` | 45 | 0 | 0 | 45 |
+| `billing` | 23 | 0 | 0 | 23 |
+| `connector` | 22 | 2 | 0 | 20 |
+| `workspace` | 19 | 6 | 0 | 13 |
+| `project` | 17 | 5 | 0 | 12 |
+| `workflow` | 16 | 5 | 0 | 11 |
+| `dataset` | 15 | 9 | 0 | 6 |
+| `parameter` | 14 | 2 | 0 | 12 |
+| `data-app` | 12 | 1 | 0 | 11 |
+| `folder` | 8 | 5 | 0 | 3 |
+| `snippet` | 8 | 1 | 0 | 7 |
+| `automation` | 7 | 1 | 0 | 6 |
+| `user` | 7 | 2 | 0 | 5 |
+| `webhook` | 7 | 0 | 0 | 7 |
+| `addon` | 6 | 0 | 0 | 6 |
+| `batch` | 6 | 2 | 0 | 4 |
+| `file` | 6 | 3 | 0 | 3 |
+| `agent` | 5 | 1 | 0 | 4 |
+| `ai` | 5 | 0 | 0 | 5 |
+| `annotation` | 5 | 1 | 0 | 4 |
+| `client-app` | 5 | 0 | 0 | 5 |
+| `notification` | 5 | 1 | 0 | 4 |
+| `schedule` | 5 | 0 | 0 | 5 |
+| `template` | 5 | 0 | 0 | 5 |
+| `browse` | 4 | 2 | 0 | 2 |
+| `external-key` | 4 | 0 | 0 | 4 |
+| `trash` | 3 | 1 | 0 | 2 |
+| `activity` | 2 | 1 | 0 | 1 |
+| `job` | 2 | 2 | 0 | 0 |
+| `report` | 1 | 1 | 0 | 0 |
+
+## `activity`
+
+Verified: `activity.list`
+
+| Command | State | Note |
+|---|---|---|
+| `activity.export` | observed blocker | server_error: see sweep report |
+
+## `agent`
+
+Verified: `agent.session.list`
+
+## `ai`
+
+| Command | State | Note |
+|---|---|---|
+| `ai.sql.generate` | observed blocker | validation_error: HTTP 400 Validation error |
+| `ai.suggestion.list` | observed blocker | validation_error: HTTP 400 Validation error |
+
+## `annotation`
+
+Verified: `annotation.list`
+
+## `automation`
+
+Verified: `automation.list`
+
+## `batch`
+
+Verified: `batch.get`, `batch.list`
+
+## `browse`
+
+Verified: `browse.project`, `browse.workspace`
+
+| Command | State | Note |
+|---|---|---|
+| `browse.folder` | observed blocker | cli_error: rejects folder id 0 although folder.root reports id 0 as the root |
+| `browse.root` | observed blocker | server_error: see sweep report |
+
+## `connector`
+
+Verified: `connector.active`, `connector.list`
+
+| Command | State | Note |
+|---|---|---|
+| `connector.ai.session.list` | observed blocker | cli_error: backend returned HTTP 200 but the CLI raised api_error (envelope mismatch) |
+| `connector.connection.list` | observed blocker | server_error: see sweep report |
+| `connector.get` | observed blocker | validation_error: HTTP 400 'Invalid connector key' for a key returned by connector.list |
+
+## `dashboard`
+
+Verified: `dashboard.analytics`, `dashboard.cancel-generation`, `dashboard.canvas.get`, `dashboard.canvas.restore`, `dashboard.chat.edit`, `dashboard.chat.history`, `dashboard.context.create`, `dashboard.context.delete`, `dashboard.context.extract`, `dashboard.context.list`, `dashboard.context.update`, `dashboard.create-blank`, `dashboard.delete`, `dashboard.descriptor-data`, `dashboard.duplicate`, `dashboard.exemplar.extract`, `dashboard.get`, `dashboard.get-by-url`, `dashboard.list`, `dashboard.page.plan`, `dashboard.pages.add`, `dashboard.qa.ask`, `dashboard.qa.comment.create`, `dashboard.qa.comment.delete`, `dashboard.qa.feedback`, `dashboard.qa.session.create`, `dashboard.qa.session.delete`, `dashboard.qa.session.fork`, `dashboard.qa.session.get`, `dashboard.qa.session.list`, `dashboard.qa.session.rename`, `dashboard.qa.session.set-visibility`, `dashboard.qa.settings.get`, `dashboard.qa.settings.set`, `dashboard.restore`, `dashboard.rls.assignment.list`, `dashboard.rls.assignment.set`, `dashboard.rls.column.list`, `dashboard.rls.value.list`, `dashboard.signature.create`, `dashboard.signature.delete`, `dashboard.signature.list`, `dashboard.signature.update`, `dashboard.style.custom.create`, `dashboard.style.custom.delete`, `dashboard.style.custom.list`, `dashboard.style.custom.update`, `dashboard.style.extract-brand`, `dashboard.style.preset.list`, `dashboard.style.token.list`, `dashboard.suggestion.list`, `dashboard.swap-data`, `dashboard.tags.delete`, `dashboard.tags.list`, `dashboard.tags.merge`, `dashboard.tags.rename`, `dashboard.tags.set`, `dashboard.template.fit`, `dashboard.template.list`, `dashboard.template.preview`, `dashboard.template.resolve-mapping`, `dashboard.templates.pending`, `dashboard.trash`, `dashboard.update`, `dashboard.v3.generate`, `dashboard.video-state`
+
+| Command | State | Note |
+|---|---|---|
+| `dashboard.create` | not supported | Not supported on release: backend returns HTTP 409 4DASH012 DASHBOARD_LEGACY_CREATION_RETIRED (legacy dashboard creation retired). Use dashboard.create-blank or dashboard.v3.generate. Dashboard sweep 2026-09-18, CLI 2.0.12. |
+| `dashboard.pdf.export` | not supported | Not supported from the CLI on release: backend HTTP 400 4GENR001 requires params.data to be the browser-hydrated DashboardData map and states it cannot rebuild it from stored descriptors (dashboard sweep and Haiku e2e, 2026-09-18). The route works only with a client render pass. |
+| `dashboard.pdf-artifact` | observed blocker | blocked_missing_fixture: No real pdf export job_id obtainable (dashboard.pdf.export is itself blocked_missing_fixture) |
+| `dashboard.published.canvas` | observed blocker | blocked_missing_fixture: HTTP 404 4DASH001 DASHBOARD_NOT_FOUND via url endpoint: D=52 was never actually published (was_published=false); the only publish mechanism is 'dashboard s |
+| `dashboard.source.list` | observed blocker | server_error: HTTP 500 on GET /dashboards/sources; matches documented B04 SERVER_VARIANCE precondition |
+| `dashboard.video.export` | observed blocker | validation_error: HTTP 400 4GENR001: 'publish the dashboard before exporting a video' -- clear, actionable message |
+| `dashboard.widget-data` | observed blocker | blocked_missing_fixture: HTTP 409 4DASH004 DASHBOARD_WRONG_ENGINE: widget-data is a legacy-engine-only endpoint |
+| `dashboard.archive` | CLI defect fixed, untried since | 2.0.14 accepts the non-object 200 body and reports the committed state |
+| `dashboard.canvas.save` | CLI defect fixed, untried since | 2.0.14 no longer redacts style_tokens, so the canvas get -> save round-trip is intact |
+| `dashboard.data.draft` | CLI defect fixed, untried since | 2.0.14 / SDK 0.7.6 send the WidgetDataSpec params envelope (widget_id) |
+| `dashboard.data.published` | CLI defect fixed, untried since | 2.0.14 / SDK 0.7.6 send the WidgetDataSpec params envelope (widget_id) |
+| `dashboard.figure-intent` | CLI defect fixed, untried since | SDK 0.7.6 returns an unmatched 2xx body instead of raising ValidationError |
+| `dashboard.og-card` | CLI defect fixed, untried since | SDK 0.7.5 returns a described binary body |
+| `dashboard.query` | CLI defect fixed, untried since | 2.0.14 example carries a descriptor with kind=scalar |
+| `dashboard.style.default.get` | CLI defect fixed, untried since | SDK 0.7.6 returns an unmatched 2xx body instead of raising ValidationError |
+| `dashboard.style.derive` | CLI defect fixed, untried since | 2.0.14 no longer redacts styleTokens |
+| `dashboard.template.get` | CLI defect fixed, untried since | SDK 0.7.6 returns an unmatched 2xx body instead of raising ValidationError |
+
+## `data-app`
+
+Verified: `data-app.list`
+
+## `dataset`
+
+Verified: `dataset.batch-data`, `dataset.create`, `dataset.data`, `dataset.delete`, `dataset.file-settings.get`, `dataset.file-settings.update`, `dataset.get`, `dataset.list`, `dataset.trash`
+
+## `external-key`
+
+| Command | State | Note |
+|---|---|---|
+| `external-key.list` | observed blocker | cli_error: not_authenticated although the same session authenticated elsewhere |
+
+## `file`
+
+Verified: `file.get`, `file.list`, `file.upload`
+
+## `folder`
+
+Verified: `folder.create`, `folder.delete`, `folder.get`, `folder.list`, `folder.update`
+
+## `job`
+
+Verified: `job.get`, `job.get-many`
+
+## `notification`
+
+Verified: `notification.list`
+
+## `parameter`
+
+Verified: `parameter.group.list`, `parameter.list`
+
+## `project`
+
+Verified: `project.checkpoint.list`, `project.data-check.list`, `project.list`, `project.pending-changes`, `project.resource-status`
+
+| Command | State | Note |
+|---|---|---|
+| `project.publish-credentials` | observed blocker | cli_error: requires odbc_type, not discoverable read-only |
+| `project.resource-dependencies` | observed blocker | cli_error: required resource_ids has no CLI flag |
+
+## `report`
+
+Verified: `report.list`
+
+## `schedule`
+
+| Command | State | Note |
+|---|---|---|
+| `schedule.list` | observed blocker | validation_error: HTTP 400 with message 'Not implemented' |
+
+## `snippet`
+
+Verified: `snippet.list`
+
+## `template`
+
+| Command | State | Note |
+|---|---|---|
+| `template.list` | observed blocker | cli_error: backend returned HTTP 200 but the CLI raised api_error (envelope mismatch) |
+
+## `trash`
+
+Verified: `trash.list`
+
+## `user`
+
+Verified: `user.get`, `user.preference.get`
+
+## `view`
+
+Verified: `view.active-user.list`, `view.checkpoint.list`, `view.conditional-format.list`, `view.create`, `view.data-check.list`, `view.data.get`, `view.data.query`, `view.derivative.list`, `view.export.list`, `view.exportable-config.get`, `view.get`, `view.list`, `view.parameter-context`, `view.pipeline.get`, `view.pipeline.items`, `view.preview`, `view.task.add`, `view.task.get`, `view.task.list`, `view.version.get`, `view.version.list`
+
+| Command | State | Note |
+|---|---|---|
+| `view.ai.generation-info` | observed blocker | validation_error: HTTP 400 with message 'Not implemented' |
+
+## `webhook`
+
+| Command | State | Note |
+|---|---|---|
+| `webhook.list` | observed blocker | cli_error: api_error with no HTTP status recorded |
+
+## `workflow`
+
+Verified: `workflow.graph`, `workflow.list`, `workflow.workspace-datasets`, `workflow.workspace-exports`, `workflow.workspace-sources`
+
+## `workspace`
+
+Verified: `workspace.app-usage`, `workspace.get`, `workspace.list`, `workspace.segment.list`, `workspace.storage-breakdown`, `workspace.user.list`
+
+Evidence version: CLI mammoth-cli 1.1.11; mammoth-io 0.7.1. Details: `docs/capability-evidence/` in the repository.

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dashboard.md

@@ -148,7 +148,7 @@ Expected success: `DashboardCreateBlankResult` in the standard JSON envelope; mu
 
 Run: `mammoth dashboard data draft`. Exact input fields: `mammoth schema get dashboard.data.draft --output json --no-input`.
 
-Example: `mammoth dashboard data draft 123 --input '{"sql": "SELECT region, SUM(revenue) FROM data GROUP BY region"}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth dashboard data draft 123 --input '{"widget_id": "550e8400-e29b-41d4-a716-446655440000"}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `DashboardDataDraftResult` in the standard JSON envelope; mutation `read`, confirmation `none`, wait policy `always_wait`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -156,7 +156,7 @@ Expected success: `DashboardDataDraftResult` in the standard JSON envelope; muta
 
 Run: `mammoth dashboard data published`. Exact input fields: `mammoth schema get dashboard.data.published --output json --no-input`.
 
-Example: `mammoth dashboard data published 123 --input '{"sql": "SELECT region, SUM(revenue) FROM data GROUP BY region"}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth dashboard data published 123 --input '{"widget_id": "550e8400-e29b-41d4-a716-446655440000"}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `DashboardDataPublishedResult` in the standard JSON envelope; mutation `read`, confirmation `none`, wait policy `always_wait`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -460,7 +460,7 @@ Expected success: `DashboardQaSettingsSetResult` in the standard JSON envelope;
 
 Run: `mammoth dashboard query`. Exact input fields: `mammoth schema get dashboard.query --output json --no-input`.
 
-Example: `mammoth dashboard query 123 --input '{"body": {"params": {"descriptor": {}}}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth dashboard query 123 --input '{"body": {"params": {"descriptor": {"kind": "scalar", "agg": "count"}}}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `DashboardQueryResult` in the standard JSON envelope; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -788,7 +788,7 @@ Expected success: `DashboardTrashResult` in the standard JSON envelope; mutation
 
 Run: `mammoth dashboard update`. Exact input fields: `mammoth schema get dashboard.update --output json --no-input`.
 
-Example: `mammoth dashboard update 123 --input '{"patch": [{"op": "add", "path": "intent", "value": "sample"}]}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth dashboard update 123 --input '{"patch": [{"op": "replace", "path": "title", "value": "Renamed dashboard"}]}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `DashboardUpdateResult` in the standard JSON envelope; mutation `benign_mutation`, confirmation `none`, wait policy `returns_job`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/project.md

@@ -84,7 +84,7 @@ Expected success: `ProjectPublishCredentialsResult` in the standard JSON envelop
 
 Run: `mammoth project resource-dependencies`. Exact input fields: `mammoth schema get project.resource-dependencies --output json --no-input`.
 
-Example: `mammoth project resource-dependencies 123 --input '{"resource_ids": ["resource-123"]}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth project resource-dependencies 123 --input '{"resource_ids": [456]}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `ProjectResourceDependenciesResult` in the standard JSON envelope; mutation `read`, confirmation `none`, wait policy `not_async`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -32,3 +32,28 @@ mammoth schema find "dashboard" --output json --no-input
 Page/widget schemas vary by release. Read each schema, use returned IDs, and
 verify dashboard source plus draft/published data after every mutation. A
 creation response alone is not proof of a usable published view.
+
+## Canvas, widget data and PDF
+
+Never save an invented canvas. Read it, change it, write it back:
+
+```bash
+mammoth dashboard canvas get DASHBOARD_ID --output json --no-input   # data.canvas incl. style_tokens
+mammoth dashboard canvas save DASHBOARD_ID --input '{"body":{"params":{"canvas":CANVAS_FROM_GET}}}' --output json --no-input
+```
+
+`canvas save` with `{"canvas": {}}` fails (`dataset` and other fields are
+required); the object returned by `canvas get` is the only known-good shape.
+Widget ids for `dashboard data draft` / `dashboard data published` come from
+that canvas: `--input '{"widget_id": "WIDGET_UUID"}'` (optional
+`global_filters` / `drilldown_filters` objects). `dashboard query` needs a
+descriptor with a `kind` (`scalar`, `group`, `rate`, `detail`, `options`,
+`range`); `{"kind":"scalar","agg":"count"}` is the smallest that runs.
+
+`dashboard pdf export` and `dashboard video export` cannot be completed from
+the CLI: the backend requires the browser-hydrated `DashboardData` map
+(pre-rendered widget results) in `params.data` and refuses to rebuild it. Report
+this as a known limitation instead of retrying with `{}`. `dashboard create`
+(legacy engine) is retired on release (HTTP 409 `4DASH012`); use
+`create-blank` or `v3 generate`.
+

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/resources.md

@@ -16,6 +16,10 @@ mammoth view list DATASET_ID --project PROJECT_ID --output json --no-input
 mammoth view get VIEW_ID --project PROJECT_ID --output json --no-input
 ```
 
+`file upload` takes the local path as its positional argument; there is no
+`--source`/`--file` option. `dataset delete` is asynchronous: re-read
+`dataset list` (the id disappears once the job completes) before reporting.
+
 Use display names from the exact view schema. For settings, folders and other
 families, use `schema find`/`schema get` first, then read back the exact parent
 and resource IDs. For example:

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/transforms.md

@@ -19,7 +19,21 @@ parent from `view list DATASET_ID` (you already know it after upload) or
 
 Prefer typed operations such as convert-type, fill-missing, replace, join,
 lookup, filter and math only when the live schema
-lists them. For each operation, a successful result should contain a returned
+lists them. Pick the operation by what it does, not by its name:
+
+- `fill-missing` copies the previous/next row's value into blanks
+  (`direction` = `LAST_VALUE` forward-fill or `FIRST_VALUE`). It cannot write a
+  literal. To fill blanks with a constant (for example `0`), use `set-values`
+  on the existing column with an `IS_EMPTY` condition:
+
+```bash
+mammoth view transform set-values VIEW_ID --project PROJECT_ID \
+  --input '{"dataset_id":DATASET_ID,"existing_column":"revenue","values":[{"value":0}],"condition":{"column":"revenue","operator":"IS_EMPTY"}}' \
+  --output json --no-input
+```
+
+- `filter` keeps matching rows by default (`filter_type: "SHOW"`); to drop
+  rows, say so: `{"condition":{"column":"units","operator":"LT","value":0},"filter_type":"REMOVE"}`. For each operation, a successful result should contain a returned
 task/job reference or updated view envelope; then verify with `view task list`,
 `view task get`, `view pipeline items`, or preview according to its schema.
 

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md

@@ -50,7 +50,9 @@ or secrets in an argument, prompt, transcript, or checkpoint.
 4. Discover instead of guessing. Run `mammoth schema list/find/get --output
    json --no-input` for local CLI routes; `mammoth capability list --output
    json --no-input` is an API-binding inventory and can omit typed/local
-   routes. Then resolve workspace/project/dataset/view
+   routes. Check [capabilities](capabilities.md) for whether a route is
+   proven, not supported, or untried on release before building a plan on
+   it. Then resolve workspace/project/dataset/view
    parents with reads. Use display names returned by the exact view schema.
 5. Translate the business intent into a plan the agent chooses. Submit only
    supported operations with explicit `--project` (and other returned parents),

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/commands/dashboard.py

@@ -365,24 +365,52 @@ def dashboard_analytics(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id)
 
 
+def _widget_data_kwargs(invocation: Invocation) -> dict[str, Any]:
+    """Bind the ``WidgetDataSpec`` fields the draft/published data routes take.
+
+    ``widget_id`` (the widget UUID) is required; ``global_filters`` and
+    ``drilldown_filters`` are optional ``{column: value}`` objects.
+    """
+    document = _bound_document(invocation)
+    widget_id = _require_field(document, "widget_id")
+    if not isinstance(widget_id, str) or not widget_id.strip():
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message="The 'widget_id' input field must be a non-empty widget UUID string.",
+            exit_status=EXIT_USAGE,
+            hint="Read widget ids from 'mammoth dashboard canvas get DASHBOARD_ID'.",
+        )
+    kwargs: dict[str, Any] = {"widget_id": widget_id}
+    for name in ("global_filters", "drilldown_filters"):
+        if name not in document:
+            continue
+        value = document[name]
+        if not isinstance(value, dict):
+            raise CliError(
+                code=CODE_INVALID_ARGUMENT,
+                message=f"The '{name}' input field must be an object of column -> value.",
+                exit_status=EXIT_USAGE,
+            )
+        kwargs[name] = value
+    return kwargs
+
+
 def dashboard_data_draft(invocation: Invocation) -> HandlerResult:
-    """Run a SQL query against a dashboard's draft data. ``sql`` comes from ``--input``."""
+    """Read one widget's rows from a dashboard's draft state. Fields come from ``--input``."""
     dashboard_id = _require_int_positional(invocation, "dashboard id")
-    document = _bound_document(invocation)
-    sql = _require_field(document, "sql")
+    kwargs = _widget_data_kwargs(invocation)
     with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), dashboard_id=dashboard_id, sql=sql)
+        data = service.call(_symbol(invocation), dashboard_id=dashboard_id, **kwargs)
         data = _resolve_job(service, invocation, data)
     return data, _meta(invocation, auth.workspace_id)
 
 
 def dashboard_data_published(invocation: Invocation) -> HandlerResult:
-    """Run a SQL query against a dashboard's published data. ``sql`` from ``--input``."""
+    """Read one widget's rows from a dashboard's published state. Fields from ``--input``."""
     dashboard_id = _require_int_positional(invocation, "dashboard id")
-    document = _bound_document(invocation)
-    sql = _require_field(document, "sql")
+    kwargs = _widget_data_kwargs(invocation)
     with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), dashboard_id=dashboard_id, sql=sql)
+        data = service.call(_symbol(invocation), dashboard_id=dashboard_id, **kwargs)
         data = _resolve_job(service, invocation, data)
     return data, _meta(invocation, auth.workspace_id)
 
@@ -561,6 +589,10 @@ def dashboard_archive(invocation: Invocation) -> HandlerResult:
         data = service.call(
             _symbol(invocation), dashboard_id=dashboard_id, archived=document["archived"]
         )
+    if not isinstance(data, dict):
+        # The route declares no response body; give the committed state a
+        # stable object shape instead of a bare scalar.
+        data = {"dashboard_id": dashboard_id, "archived": document["archived"], "response": data}
     return data, _meta(invocation, auth.workspace_id)
 
 

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/commands/view.py

@@ -1214,13 +1214,25 @@ def view_pipeline_items(invocation: Invocation) -> HandlerResult:
 def view_pipeline_items_all(invocation: Invocation) -> HandlerResult:
     """Read all pipeline items through bounded, exact-parent pagination."""
     dataview_id = _require_int_positional_at(invocation, 0, "dataview id")
-    document = invocation.load_input() or {}
+    document = dict(invocation.load_input() or {})
+    # The schema advertises an optional trailing DATASET_ID positional that
+    # falls back to the input field; honour both, and reject a disagreement.
+    positional_parent = _int_positional_at(invocation, 1, "dataset id")
+    if positional_parent is not None:
+        if document.get("dataset_id") not in (None, positional_parent):
+            raise CliError(
+                code="ambiguous_resource_identity",
+                message="Conflicting dataset ids identify different parent resources.",
+                exit_status=EXIT_USAGE,
+                hint="Pass one exact dataset id matching the target view.",
+            )
+        document["dataset_id"] = positional_parent
     if "dataset_id" not in document:
         raise CliError(
             code=CODE_MISSING_FIELD,
-            message="This command requires the 'dataset_id' input field.",
+            message="This command requires the exact parent dataset id.",
             exit_status=EXIT_USAGE,
-            hint="Pass the exact parent dataset_id via --input.",
+            hint="Pass it as the trailing DATASET_ID positional or the 'dataset_id' input field.",
         )
     dataset_id = document["dataset_id"]
     if isinstance(dataset_id, bool) or not isinstance(dataset_id, int) or dataset_id <= 0:

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/output/normalize.py

@@ -14,6 +14,7 @@ import decimal
 import enum
 import ipaddress
 import math
+import re
 import uuid
 from collections.abc import Mapping
 from pathlib import Path
@@ -50,12 +51,33 @@ class _NormalizedJsonSchema(dict[str, Any]):
     """
 
 
+_CAMEL_BOUNDARY = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+# Plural ``*_tokens`` keys that still name credentials rather than design data.
+_CREDENTIAL_TOKEN_PREFIXES = ("access", "refresh", "auth", "api", "bearer", "session", "oauth")
+
+
 def _is_secret_key(key: str) -> bool:
-    lowered = key.lower()
+    # ``styleTokens`` and ``style_tokens`` must be judged the same way.
+    lowered = _CAMEL_BOUNDARY.sub("_", key).lower()
     # ``token_count`` is ordinary result metadata (for example an LLM usage
     # counter), not a credential.  Do not let the broad token guard erase it.
-    if lowered in {"token_count", "next_token", "continuation_token", "design_tokens"}:
+    if lowered in {
+        "token_count",
+        "next_token",
+        "continuation_token",
+        "page_token",
+        "design_tokens",
+    }:
         return False
+    if "token" in lowered and not any(
+        hint in lowered for hint in _SECRET_KEY_HINTS if hint != "token"
+    ):
+        # Credential tokens are singular (``token``, ``access_token``).  Plural
+        # ``tokens`` / ``style_tokens`` are dashboard design-system data, and
+        # erasing them breaks the canvas get -> save round-trip.
+        if lowered == "tokens" or lowered.endswith("_tokens"):
+            return lowered.startswith(_CREDENTIAL_TOKEN_PREFIXES)
+        return True
     return any(hint in lowered for hint in _SECRET_KEY_HINTS)
 
 
@@ -69,8 +91,7 @@ def _is_secret_value(value: Any) -> bool:
     """
     value_type = type(value)
     return value_type.__name__ in {"SecretStr", "SecretBytes"} or (
-        "secret" in value_type.__name__.lower()
-        and hasattr(value, "get_secret_value")
+        "secret" in value_type.__name__.lower() and hasattr(value, "get_secret_value")
     )
 
 

{mammoth_cli-2.0.12 → mammoth_cli-2.0.14}/mammoth_cli/services/input_fields.py

@@ -39,6 +39,9 @@ _CLOSED_ZERO_INPUT_COMMANDS = frozenset({"config.get"})
 #: value here is a genuine, accepted --input field so the documented example both
 #: validates against the input schema and works when run.
 _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
+    # The backend requires integer resource ids ("resource_ids must be
+    # comma-separated integers"); the SDK annotation is a plain list[str].
+    "project.resource-dependencies": {"resource_ids": [456]},
     "view.export.azure-blob": {
         "storage_account_name": "storage-account",
         "tenant_id": "tenant-id",
@@ -142,6 +145,20 @@ _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
     # Blank dashboard creation requires a typed params envelope. Keep the
     # generated destructive example runnable with the explicit approval flag.
     "dashboard.create-blank": {"params": {"dataview_id": 1}},
+    # The draft/published data routes take a WidgetDataSpec keyed by the
+    # widget UUID (read it from ``dashboard canvas get``), not a SQL string.
+    "dashboard.data.draft": {"widget_id": "550e8400-e29b-41d4-a716-446655440000"},
+    "dashboard.data.published": {"widget_id": "550e8400-e29b-41d4-a716-446655440000"},
+    # ``descriptor`` is a baked/1 QueryDescriptor discriminated by ``kind``
+    # (group | scalar | rate | detail | options | range); an empty object is
+    # rejected. A scalar row count runs against any dashboard.
+    "dashboard.query": {"body": {"params": {"descriptor": {"kind": "scalar", "agg": "count"}}}},
+    # ``path`` is a bare field name (title | intent | theme | pages | filters),
+    # not a JSON pointer, and an ``intent`` value must be at least 10 chars; a
+    # title rename is the smallest patch that runs.
+    "dashboard.update": {
+        "patch": [{"op": "replace", "path": "title", "value": "Renamed dashboard"}]
+    },
 }