mammoth-cli 2.0.28__tar.gz → 2.0.30__tar.gz

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.28
+Version: 2.0.30
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk

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

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/app.py

@@ -29,7 +29,7 @@ from typer.core import TyperGroup
 
 from mammoth_cli import __version__
 from mammoth_cli.commands import BESPOKE
-from mammoth_cli.commands.registry import HANDLERS
+from mammoth_cli.commands.registry import HANDLERS, Handler
 from mammoth_cli.context import profiles
 from mammoth_cli.errors.envelope import EXIT_USAGE, CliError, not_implemented_error
 from mammoth_cli.manifest.loader import command_by_id, load_commands
@@ -629,6 +629,18 @@ def _shared_option_params() -> list[inspect.Parameter]:
                 ),
             ],
         ),
+        opt(
+            "dry_run",
+            False,
+            Annotated[
+                bool,
+                typer.Option(
+                    "--dry-run",
+                    help="Resolve and validate, then report the request instead of sending it.",
+                    rich_help_panel="Safety",
+                ),
+            ],
+        ),
         opt(
             "input_file",
             None,
@@ -777,6 +789,8 @@ def _execute(invocation: Invocation) -> None:
             record = command_by_id(invocation.command_id)
             sdk_symbol = record.get("sdk_symbol", "") if record else ""
             raise not_implemented_error(invocation.command_id, sdk_symbol)
+        if invocation.dry_run:
+            return _dry_run(handler, invocation)
         return handler(invocation)
 
     executor.run(
@@ -789,6 +803,25 @@ def _execute(invocation: Invocation) -> None:
     )
 
 
+def _dry_run(handler: Handler, invocation: Invocation) -> tuple[Any, dict[str, Any]]:
+    """Run ``handler`` until its request would leave; report that request.
+
+    Local commands never open a service, so a dry run of one is the real run.
+    An API-backed handler that returns normally under ``--dry-run`` made no
+    gated SDK call at all (a pure read path); its result is returned as is.
+    """
+    from mammoth_cli.runtime.dryrun import DryRunStop
+    from mammoth_cli.runtime.session import resolved_project
+
+    try:
+        return handler(invocation)
+    except DryRunStop as stop:
+        return stop.record, {
+            "profile": invocation.profile,
+            "project_id": resolved_project(invocation),
+        }
+
+
 def _command_help(command_id: str, record: dict[str, Any] | None) -> str | None:
     """Build a command's user-facing ``--help`` summary.
 

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.28
+version: 2.0.30
 description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines, dashboards, exports, and handoffs."
 ---
 
@@ -60,6 +60,8 @@ before the next step.
   '{"full": true}'` returns the dependency and display trees too.
 - Column inputs and expressions use the exact **display names** the view
   returns, never backend aliases.
+- `--dry-run` on any API-backed command resolves everything and reports the
+  request instead of sending it; use it before a write you are not sure of.
 - Destructive commands need `--yes --confirm ID`. Preserve requested
   deliverables; cleanup is exact-ID authorized and
   never means delete-all-owned-resources: delete only ids this run created,

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities-misc.md

@@ -140,4 +140,4 @@ Ran once: `workflow.create`, `workflow.delete`, `workflow.get`, `workflow.graph`
 
 Ran once: `workspace.app-usage`, `workspace.get`, `workspace.list`, `workspace.segment.list`, `workspace.segment.update`, `workspace.storage-breakdown`, `workspace.user.list`
 
-Evidence collected on CLI releases 1.1.5 through 2.0.27; each row's release is recorded in `docs/release-capability-matrix.json` (`evidence_version`). A row that ran on an older release has not been re-run since unless its note says so. Details: `docs/capability-evidence/` in the repository.
+Evidence collected on CLI releases 1.1.5 through 2.0.28; each row's release is recorded in `docs/release-capability-matrix.json` (`evidence_version`). A row that ran on an older release has not been re-run since unless its note says so. Details: `docs/capability-evidence/` in the repository.

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities.md

@@ -118,4 +118,4 @@ Ran once: `view.active-user.list`, `view.active-user.mark`, `view.ai.generate-da
 | `view.data-check.update` | observed blocker | backend_error: PATCH with the schema's documented {op: command, path: enable/disable, value: null} shape returns HTTP 500 empty body (CLI outcome_unknown, exit 7) while the mutatio |
 | `view.export.publish-db-update` | CLI defect fixed, untried since | 2.0.16 (example value is the documented {"odbc_type": "postgres"} object (a bare string is rejected)) |
 
-Evidence collected on CLI releases 1.1.5 through 2.0.27; each row's release is recorded in `docs/release-capability-matrix.json` (`evidence_version`). A row that ran on an older release has not been re-run since unless its note says so. Details: `docs/capability-evidence/` in the repository.
+Evidence collected on CLI releases 1.1.5 through 2.0.28; each row's release is recorded in `docs/release-capability-matrix.json` (`evidence_version`). A row that ran on an older release has not been re-run since unless its note says so. Details: `docs/capability-evidence/` in the repository.

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dashboard.md

@@ -70,7 +70,7 @@ Example: `mammoth dashboard canvas get 123`. Placeholders are illustrative; reso
 
 Result: `DashboardCanvasGetResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
 
-Status on release: ran once on CLI 2.0.12 — Published PyPI CLI 1.1.11 / SDK 0.7.1 draft canvas read succeeded for retained dashboard 48. One dashboard only; not Full. Also: Dashboard sweep 2026-09-18: exit 0 on release with CLI 2.0.12; result keys: canvas, dashboard_id, meta, plan, specs. returned canv…
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. Read back the authored canvas, plan.hints.kpis and meta.figures (figure key -> descriptor id) after each bake; used as the binding check the ILG brief requires. Single invocation only.
 
 ### `dashboard.canvas.restore`
 
@@ -90,7 +90,7 @@ Example: `mammoth dashboard canvas save 123 --input '{"body": {"params": {"canva
 
 Result: `DashboardCanvasSaveResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 
-Status on release: ran once on CLI 2.0.14 — dashboard re-verification 2026-09-18: exit 0 on release with CLI 2.0.14. CLI defect fixed, confirmed: dashboard canvas get -> save round-trip completed cleanly, sequence advanced 1->2, response {"bake_job_id":296,"changed_tiles":0,"recomposed":false,"seeded_p…
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. Authored a canvas from a blank one: page-level focus.kpis (sum with unit.prefix GBP, and a countDistinct card), added bar (measure+measure2), hbar, line on a derived ratio measure (canvas.derived),…
 
 ### `dashboard.chat.edit`
 
@@ -178,7 +178,7 @@ Example: `mammoth dashboard create-blank --input '{"params": {"dataview_id": 1}}
 
 Result: `DashboardCreateBlankResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 
-Status on release: ran once on CLI 2.0.21 — ergonomics sweep 2026-09-19: exit 0 on release with CLI 2.0.21. Created dashboard 62 (sequence 1). Single invocation only.
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. Two blank v3 dashboards bound to owned views (ids 63, 64). Single invocation only.
 
 ### `dashboard.data.draft`
 
@@ -214,11 +214,11 @@ Status on release: ran once on CLI 2.0.21 — ergonomics sweep 2026-09-19: exit
 
 Run: `mammoth dashboard descriptor-data`. Exact input fields: `mammoth schema get dashboard.descriptor-data`.
 
-Example: `mammoth dashboard descriptor-data 123 --input '{"body": {"params": {"descriptor_ids": ["resource-123"]}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth dashboard descriptor-data 123 --input '{"body": {"params": {"descriptor_ids": ["ef28f9bcc263c0f7"], "filter_state": {"Month": ["2025-01-01", "2025-03-31"]}}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `DashboardDescriptorDataResult`; mutation `benign_mutation`, confirmation `none`, wait policy `always_wait`.
 
-Status on release: ran once on CLI 2.0.12 — Dashboard sweep 2026-09-18: exit 0 on release with CLI 2.0.12; result keys: completed, expected, results. endpoint works on v3 engine; returned structured per-id error (404 unknown descriptor id) for a fabricated descriptor id since no real descriptor id was…
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. Evaluated baked descriptors by id with filter_state {Month: [start, end]}: countDistinct card = 111 unfiltered and 64 under a Q1 range (the fixture key; a summed per-cell count would read 83), sums…
 
 ### `dashboard.duplicate`
 
@@ -258,7 +258,7 @@ Example: `mammoth dashboard get 123`. Placeholders are illustrative; resolve IDs
 
 Result: `DashboardGetResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
 
-Status on release: ran once on CLI 2.0.12 — Published PyPI CLI 1.1.11 read-only dashboard get on retained dashboard48 returned a bounded structural object; one retained scope does not establish Full support. Also: Dashboard sweep 2026-09-18: exit 0 on release with CLI 2.0.12; result keys: auto_publish,…
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. auto_sync for the bound view showed last_synced_at after the upstream data change. Single invocation only.
 
 ### `dashboard.get-by-url`
 
@@ -324,11 +324,11 @@ Status on release: ran once on CLI 2.0.12 — Dashboard sweep 2026-09-18: exit 0
 
 Run: `mammoth dashboard pages add`. Exact input fields: `mammoth schema get dashboard.pages.add`.
 
-Example: `mammoth dashboard pages add 123 --input '{"body": {"params": {"pages": [{}]}}}'`. Illustrative only: append `--yes --confirm <EXACT_TARGET>` after observing the target.
+Example: `mammoth dashboard pages add 123 --input '{"body": {"params": {"pages": [{"title": "By region", "focus": {"measure": "Revenue", "dim": "Region", "kpis": [{"field": "Revenue", "agg": "sum", "label": "Revenue"}]}, "charts": [{"kind": "hbar", "title": "Revenue by region", "dim": "Region", "measure": "Revenue", "agg": "sum"}]}]}}}'`. Illustrative only: append `--yes --confirm <EXACT_TARGET>` after observing the target.
 
 Result: `DashboardPagesAddResult`; mutation `high_impact`, confirmation `confirm_target`, wait policy `returns_job`.
 
-Status on release: ran once on CLI 2.0.12 — Dashboard sweep 2026-09-18: exit 0 on release with CLI 2.0.12; result keys: added_page_ids, bake_job_id, message, sequence. added page p2 to D=52 after supplying --yes --confirm 52 (first attempt without confirmation correctly returned confirmation_required,…
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. Needs --yes --confirm DASHBOARD_ID. body.params.pages[] takes PageAdd objects (title, focus{kpis}, charts[]); the route runs through the LLM guard and dropped unit.prefix on a money card ('nothing…
 
 ### `dashboard.pdf-artifact`
 

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dataset.md

@@ -130,7 +130,7 @@ Example: `mammoth dataset list`. Placeholders are illustrative; resolve IDs and
 
 Result: `DatasetListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
 
-Status on release: ran once on CLI 2.0.18 — fixture-lifecycle sweep 2026-09-19: exit 0 on release with CLI 2.0.18. Empty result on this fixture. Confirmed all 3 owned datasets (85,86,87) gone before deleting the project. Single invocation only.
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. Listed the datasets the sends created in the target project. Single invocation only.
 
 ### `dataset.rename`
 

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/file.md

@@ -82,7 +82,7 @@ Example: `mammoth file upload ./sales.csv`. Placeholders are illustrative; resol
 
 Result: `FileUploadResult`; mutation `benign_mutation`, confirmation `none`, wait policy `start_or_wait`.
 
-Status on release: ran once on CLI 2.0.21 — ergonomics sweep 2026-09-19: exit 0 on release with CLI 2.0.21. Uploaded smoke.csv -> dataset 94 ready; dataview 116 (3 rows). Second call with --input {"append_to_ds_id": 94} returned dataset 95 ready and view 116 row_count went 3 -> 6: append path works (th…
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. Three CSV uploads into a new source project; dates typed DATE without file-settings changes. Single invocation only.
 
 ### `file.upload-folder`
 

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -220,7 +220,7 @@ Example: `mammoth view data get 123 123`. Placeholders are illustrative; resolve
 
 Result: `ViewDataGetResult`; mutation `read`, confirmation `none`, wait policy `always_wait`.
 
-Status on release: ran once on CLI 2.0.21 — ergonomics sweep 2026-09-19: exit 0 on release with CLI 2.0.21. Default trim: rows_returned 3, rows_total_in_page 3, truncated false; with limit 2: rows_returned 2, truncated true. Single invocation only.
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. Paged reads (limit up to 500) used for every value check; envelope data.data rows keyed by display name. Single invocation only.
 
 ### `view.data.query`
 
@@ -466,7 +466,7 @@ Example: `mammoth view export list 123 123`. Placeholders are illustrative; reso
 
 Result: `ViewExportListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
 
-Status on release: ran once on CLI an earlier release — Published PyPI CLI 1.1.11 read-only export-list call on retained view46/dataset29 returned a bounded empty page with unexpected offset50; no export was executed and Full support is not claimed.
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. Listed both internal_dataset exports with target_properties (DS_NAME, COLUMN_MAPPING, project fields). Single invocation only.
 
 ### `view.export.managed-s3`
 
@@ -702,7 +702,7 @@ Example: `mammoth view pipeline items 123`. Placeholders are illustrative; resol
 
 Result: `ViewPipelineItemsResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
 
-Status on release: ran once on CLI 1.1.11 — Published PyPI CLI 1.1.11 pipeline-items read on retained view46/dataset29 returned one bounded item; prior owned-view evidence is retained and no Full claim is made.
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. fields=__full listed both export steps with sequence/status/execution times; the pre-existing step's timestamps did not move when a second send was appended. Single invocation only.
 
 ### `view.pipeline.items-all`
 
@@ -772,7 +772,7 @@ Example: `mammoth view task delete 123 123`. Illustrative only: append `--yes` a
 
 Result: `ViewTaskDeleteResult`; mutation `destructive`, confirmation `prompt_or_yes`, wait policy `always_wait`.
 
-Status on release: ran once on CLI 2.0.14 — write sweep 2026-09-18: exit 0 on release with CLI 2.0.14. Task 24 (created via view transform convert-type) deleted -> {future_id:347,status:processing,type_of_modification:discard_rule}. Verified via view task list 73: tasks:[] afterward. Single invocation…
+Status on release: ran once on CLI 2.0.28 — ILG simulation 2026-09-19: exit 0 on release with CLI 2.0.28. Removed a SQL task that had run on the wrong intermediate shape; view returned to the previous columns and row count. Single invocation only.
 
 ### `view.task.get`
 
@@ -832,7 +832,7 @@ Example: `mammoth view transform add-sql 123 --input '{"query": "SELECT region,
 
 Result: `ViewTransformAddSqlResult`; mutation `reversible_pipeline`, confirmation `none`, wait policy `always_wait`.
 
-Status on release: untried; it submits through `view.task.add`, but this transform was not among those run.
+Status on release: ran once on CLI 2.0.18 through `view.task.add` and was read back with `view data get`; other inputs for this transform are untried.
 
 ### `view.transform.ai`
 
@@ -932,7 +932,7 @@ Example: `mammoth view transform extract-date 123 --input '{"column": "Status",
 
 Result: `ViewTransformExtractDateResult`; mutation `reversible_pipeline`, confirmation `none`, wait policy `always_wait`.
 
-Status on release: untried; it submits through `view.task.add`, but this transform was not among those run.
+Status on release: ran once on CLI 2.0.18 through `view.task.add` and was read back with `view data get`; other inputs for this transform are untried.
 
 ### `view.transform.fill-missing`
 
@@ -1112,7 +1112,7 @@ Example: `mammoth view transform window 123 --input '{"function": "ROW_NUMBER",
 
 Result: `ViewTransformWindowResult`; mutation `reversible_pipeline`, confirmation `none`, wait policy `always_wait`.
 
-Status on release: untried; it submits through `view.task.add`, but this transform was not among those run.
+Status on release: ran once on CLI 2.0.18 through `view.task.add` and was read back with `view data get`; other inputs for this transform are untried.
 
 ### `view.trash`
 

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/input.md

@@ -10,9 +10,11 @@ mammoth view transform filter 1039 --project 180 \
   --input '{"condition": {"and": [{"column": "Order Status", "operator": "EQ", "value": "Open"}, {"column": "Customer Age", "operator": "GT", "value": 30}]}}'
 ```
 
-- `--input FILE` reads a JSON or YAML file; the format is inferred from the
-  extension.
+- `--input FILE` (or `--input @FILE`) reads a JSON or YAML file; the format
+  is inferred from the extension.
 - `--input -` reads stdin; then `--input-format json|yaml` is required.
+- `--dry-run` admits and resolves the document, then reports the SDK call
+  instead of making it ([safety](safety.md)).
 - The top level must be a mapping. A bad path, format, or shape fails with exit
   code 2 and a stable error code.
 - Column references use display names returned by the exact view schema. Do not

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/operations.md

@@ -90,6 +90,14 @@ task/list or pipeline/items result back after a successful write. Without that
 independent specification, report the route as unsupported/ambiguous and stop
 safely.
 
+Typed transforms and `view task add` append at the end of the pipeline and
+never reorder or delete an existing step. On a pipeline other people or
+agents also edit, make that checkable: read `view task list VIEW_ID`, plan,
+then write with `"expected_task_count": N` in the input; the CLI re-reads
+the list just before the write and refuses with `pipeline_changed` when the
+count moved ([safety](safety.md)). `--dry-run` on the same command shows the
+resolved call first.
+
 For a new workflow (a container for automation), discover and then read it
 back; workflow creation is not the same as adding a view pipeline task:
 

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -34,6 +34,54 @@ Page/widget schemas vary by release. Read each schema, use returned IDs, and
 verify the binding plus draft/published data after every mutation. A
 creation response alone is not proof of a usable published view.
 
+## Authoring a board from a blank canvas
+
+`create-blank` gives one empty page. Author it by reading the canvas,
+editing the **active page** (`pages[0]`; a root-level `focus` is stored but
+never baked when pages exist) and writing the whole object back:
+
+```bash
+mammoth dashboard create-blank --yes --input '{"params": {"dataview_id": VIEW_ID, "title": "Overview"}}'
+mammoth dashboard canvas get DASHBOARD_ID > canvas.json      # data.canvas is the object to edit
+# pages[0].focus  = {"measure": "Sales Actual", "dim": "Location",
+#                    "kpis": [{"field": "Sales Actual", "agg": "sum", "label": "Sales", "unit": {"prefix": "£"}, "decimals": 0},
+#                             {"field": "Employee Ref", "agg": "countDistinct", "label": "Distinct staff"}]}
+# pages[0].added  = [{"kind": "bar", "title": "Actual vs Budget by Month", "measure": "Sales Actual", "measure2": "Sales Budget",
+#                     "agg": "sum", "date_bucket": {"field": "Month", "unit": "month"}},
+#                    {"kind": "hbar", "title": "Sales by Location", "dim": "Location", "measure": "Sales Actual", "agg": "sum", "sort": "desc"},
+#                    {"kind": "line", "title": "Occupancy rate", "measure": "occupancy_rate", "date_bucket": {"field": "Month", "unit": "month"}},
+#                    {"kind": "table", "title": "Detail", "columns": ["Location", "Month", "Places"], "sort_by": "Month", "limit": 100}]
+# derived         = [{"id": "occupancy_rate", "label": "Occupancy rate", "numerator": "Occupied", "denominator": "Places"}]
+# filters         = [{"field": "Month", "control": "range", "label": "Month"}, {"field": "Location", "control": "multi"}]
+mammoth dashboard canvas save DASHBOARD_ID --input '{"body": {"params": {"canvas": <edited data.canvas>}}}'
+mammoth job wait BAKE_JOB_ID                                  # data.bake_job_id from the save
+```
+
+Rules the backend enforces (each returns the pydantic path on failure):
+`added[].measure` is a column name — a ratio lives in `canvas.derived[]` and
+is referenced by id; `focus.kpis[].agg` accepts `countDistinct` (the only
+correct aggregation for a "distinct people" card under a date filter);
+`unit.prefix` goes on money cards only. `dashboard pages add --yes --confirm
+ID --input '{"body": {"params": {"pages": [{"title": ..., "focus": {...},
+"charts": [...]}]}}}'` adds a page, but that route runs through the LLM
+guard and may drop a unit it cannot evidence (it says so in `data.message`);
+`canvas save` keeps what you wrote.
+
+**Read the bindings back, then the numbers.** `dashboard canvas get` returns
+`data.meta.figures` — `"p1:kpi:2": {"descriptors": {"value": "<id>"}}` per
+card and tile — and `data.plan.hints.kpis` with the agg per card. Evaluate
+ids with a filter:
+
+```bash
+mammoth dashboard descriptor-data DASHBOARD_ID --input '{"body": {"params": {
+  "descriptor_ids": ["<id>", "<id>"],
+  "filter_state": {"Month": ["2025-01-01", "2025-03-31"]}}}}'
+# -> data.results.<id>.value (scalar) or .data (rows); filter fields must be declared canvas filters
+```
+
+A card that reads the same with and without the filter, or a distinct count
+that equals a row count, is a wrong binding, not a data fact.
+
 ## Canvas, widget data and PDF
 
 Never save an invented canvas. Read it, change it, write it back:

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/transforms.md

@@ -142,6 +142,18 @@ Prefer `pivot` over `add-sql` for a grouped summary when `capabilities.md`
 lists it as run on release; `add-sql` replaces every column of the view, so
 never run it on a deliverable view.
 
+`add-sql` facts from release: the only table is `"view:VIEW_ID"` (the view
+itself; a second view in FROM/JOIN is `5GENR010 only one table allowed` —
+join with `view transform join` afterwards); `CASE`, `DATE_TRUNC('month',
+col)`, `GROUP BY`, `COUNT(DISTINCT col)` and `UNION ALL` over the same view
+work; result columns must be NUMERIC, TEXT or TIMESTAMPTZ (`CAST(x AS DATE)`
+is rejected; `CAST(x || '-01' AS TIMESTAMPTZ)` turns a `YYYY-MM` text month
+into a date column). A location canonicaliser plus month bucketing plus
+per-cell aggregation is one `add-sql` per fact; a mixed-grain table (summary
+rows plus one row per entity with NULL measures, for a `countDistinct` card)
+is one `UNION ALL`. The worked run is
+`docs/capability-evidence/ilg-sim-20260919/SUMMARY.md`.
+
 Reject malformed fields with the structured error envelope and stop rather than
 guessing names. Verify exact display names, join multiplicity, math values and
 remote task/pipeline readback. Draft submit is not proof all tasks persisted:

mammoth_cli-2.0.30/mammoth_cli/bundled_skill/mammoth-cli/references/safety.md

@@ -0,0 +1,66 @@
+# Safe mutation
+
+Each command carries a reviewed confirmation policy:
+
+| policy | how to satisfy it noninteractively |
+|---|---|
+| none | nothing required |
+| prompt_or_yes | pass `--yes` |
+| yes_always | pass `--yes` (always, even at a terminal) |
+| confirm_target | pass `--yes` and `--confirm TARGET` (exact match) |
+
+Under `--no-input` (and in `json`/`ndjson` modes) there is no prompt: a missing
+`--yes`/`--confirm` fails with exit code 2 and error code
+`confirmation_required` or `confirmation_target_mismatch`.
+
+```bash
+# normal delete
+mammoth folder delete 7 --project 180 --yes
+
+# high-impact: target must equal the resource
+mammoth project user remove --project 180 \
+  --yes --confirm 180 --input '{"user_ids": ["u_123"]}'
+
+# project delete cascades to every dataset, view, export and dashboard in it
+mammoth project delete 180 --yes --confirm 180
+```
+
+Discover a command's policy with `mammoth schema get <command.id>`.
+
+## Rehearse before you write
+
+`--dry-run` on any API-backed command does everything but send the request:
+input admission, parent resolution, display-name and condition checks, then
+it stops at the SDK call and reports it as `data.would_call` (`sdk_symbol`,
+resolved `arguments`, `view_id`/`dataset_id`) with `data.dry_run: true`. No
+confirmation flag is needed for a dry run; the real run still needs its
+`--yes`/`--confirm`. Use it before a mutation on a shared or production
+resource, and whenever you are unsure which view or column an input resolves
+to.
+
+```bash
+mammoth view transform filter 144 --dry-run \
+  --input '{"filter_type": "REMOVE", "condition": {"column": "Location", "operator": "EQ", "value": "Total"}}'
+# data.would_call.sdk_symbol = ...FilterOpsMixin.filter_rows, view_id 144, dataset_id 122
+```
+
+## Add-only edits to a pipeline someone else may touch
+
+Every `view transform *` and `view task add` accepts `expected_task_count`:
+the number of tasks your last `view task list VIEW_ID` returned. The CLI
+re-reads the task list right before the write and refuses with
+`pipeline_changed` (exit 2, `details.actual_task_count`, `task_ids`) when the
+count differs, so a plan made against a stale read cannot land on a pipeline
+that changed under you. Read → decide → write with the count, one edit at a
+time; on `pipeline_changed`, re-read and re-decide rather than retrying with
+the new number blindly.
+
+```bash
+mammoth view task list 144            # data.tasks has 3 entries
+mammoth view transform filter 144 --input '{"expected_task_count": 3, "filter_type": "REMOVE", "condition": {...}}'
+```
+Use exact observed resource scope and display names before mutation. A known job
+handle should be inspected or waited, not submitted again. `outcome_unknown`
+means a mutation may have committed without a terminal response: reconcile the
+target before any replay. A retryable read can honor `Retry-After`; exit 7 is
+not blanket permission to retry a mutation.

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/commands/view.py

@@ -1445,11 +1445,15 @@ def view_task_add(invocation: Invocation) -> HandlerResult:
     kwargs: dict[str, Any] = {"dataview_id": dataview_id, "task_spec": task_spec}
     assert document is not None
     _forward_optional(document, kwargs, ("dataset_id",))
+    # Imported here: view_ops imports this module for the brief record helpers.
+    from mammoth_cli.commands.view_ops import (
+        reject_pipeline_reference_errors,
+        require_expected_task_count,
+    )
+
     with open_service(invocation) as (service, auth):
+        require_expected_task_count(service, dataview_id, kwargs.get("dataset_id"), document)
         data = service.call(_symbol(invocation), **kwargs)
-        # Imported here: view_ops imports this module for the brief record helpers.
-        from mammoth_cli.commands.view_ops import reject_pipeline_reference_errors
-
         reject_pipeline_reference_errors(service, dataview_id, kwargs.get("dataset_id"), data)
     return data, _meta(invocation, auth.workspace_id, None)
 

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/commands/view_ops.py

@@ -43,6 +43,7 @@ from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.session import open_service, resolved_project
 from mammoth_cli.services.command_contract import bind_command_inputs
 from mammoth_cli.services.conditions import CONDITION_KWARG
+from mammoth_cli.services.input_fields import TASK_COUNT_FIELD
 
 HandlerResult = tuple[Any, dict[str, Any]]
 
@@ -251,6 +252,7 @@ def _dispatch_view(
     with open_service(invocation) as (service, auth):
         if dataset_id is None:
             dataset_id = parents.lookup(_profile_name(invocation), auth.workspace_id, view_id)
+        require_expected_task_count(service, view_id, dataset_id, document)
         try:
             if dataset_id is None:
                 _require_discovery_allowed(invocation, view_id)
@@ -266,6 +268,60 @@ def _dispatch_view(
     return data, _meta(invocation, auth.workspace_id)
 
 
+CODE_PIPELINE_CHANGED = "pipeline_changed"
+_TASK_LIST_SYMBOL = "mammoth.api.pipeline.PipelineAPI.list_tasks"
+
+
+def require_expected_task_count(
+    service: Any, view_id: int, dataset_id: Any, document: dict[str, Any] | None
+) -> None:
+    """Refuse a pipeline write when the view's task count is not the one read.
+
+    ``expected_task_count`` is the count from the caller's last ``view task
+    list``. A different live count means the pipeline changed since that read
+    (another agent, a person in the web app), and an append planned against
+    the old shape must not land. Without the field nothing is checked.
+    """
+    if not document or TASK_COUNT_FIELD not in document:
+        return
+    expected = int(document[TASK_COUNT_FIELD])
+    kwargs: dict[str, Any] = {"dataview_id": view_id}
+    if dataset_id is not None:
+        kwargs["dataset_id"] = int(dataset_id)
+    listing = service.call(_TASK_LIST_SYMBOL, **kwargs)
+    tasks = listing.get("tasks") if isinstance(listing, dict) else None
+    if not isinstance(tasks, list):
+        raise CliError(
+            code=CODE_PIPELINE_CHANGED,
+            message=f"Could not read the task list of view {view_id} to check the precondition.",
+            exit_status=EXIT_USAGE,
+            details={"view_id": view_id, "expected_task_count": expected, "response": listing},
+        )
+    actual = len(tasks)
+    if actual == expected:
+        return
+    raise CliError(
+        code=CODE_PIPELINE_CHANGED,
+        message=(
+            f"View {view_id} has {actual} pipeline task(s), not the {expected} expected; "
+            "the pipeline changed since it was read, so nothing was written."
+        ),
+        exit_status=EXIT_USAGE,
+        hint=(
+            "Re-read the pipeline, decide whether the plan still holds, and retry "
+            f"with expected_task_count {actual}."
+        ),
+        details={
+            "view_id": view_id,
+            "dataset_id": int(dataset_id) if dataset_id is not None else None,
+            "expected_task_count": expected,
+            "actual_task_count": actual,
+            "task_ids": [t.get("id") for t in tasks if isinstance(t, dict)],
+        },
+        recovery_commands=[f"mammoth view task list {view_id}"],
+    )
+
+
 def _compact_reference_error(entry: Any) -> dict[str, Any]:
     if not isinstance(entry, dict):
         return {"reason": str(entry)}
@@ -362,7 +418,11 @@ def _without_resource_context(document: dict[str, Any]) -> dict[str, Any]:
     # mapping.  These identifiers select the View receiver and are not method
     # kwargs; strip both parent and receiver identities before the transform
     # adapter forwards the document.
-    return {key: value for key, value in document.items() if key not in {"dataset_id", "view_id"}}
+    return {
+        key: value
+        for key, value in document.items()
+        if key not in {"dataset_id", "view_id", TASK_COUNT_FIELD}
+    }
 
 
 def _bind_transform_inputs(invocation: Invocation, document: dict[str, Any]) -> dict[str, Any]:

{mammoth_cli-2.0.28 → mammoth_cli-2.0.30}/mammoth_cli/runtime/confirm.py

@@ -84,6 +84,10 @@ def enforce_confirmation(
     """
     if policy == POLICY_NONE:
         return
+    if invocation.dry_run:
+        # Nothing is sent under --dry-run, so there is nothing to confirm; the
+        # report names the confirmation the real run will need.
+        return
 
     tty = sys.stdin.isatty() if is_tty is None else is_tty
     machine = invocation.output in MACHINE_OUTPUTS