mammoth-cli 2.0.91__tar.gz → 2.1.0__tar.gz

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.91
+Version: 2.1.0
 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.41
+Requires-Dist: mammoth-io<0.9,>=0.8.0
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/app.py

@@ -43,8 +43,9 @@ from mammoth_cli.output.policy import (
 )
 from mammoth_cli.runtime import executor, validate
 from mammoth_cli.runtime.dataset_health import with_dataset_health
-from mammoth_cli.runtime.new_data import with_new_data_path
+from mammoth_cli.runtime.intent_only import refuse_hand_crafted_write
 from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.new_data import with_new_data_path
 from mammoth_cli.runtime.state import with_state
 from mammoth_cli.runtime.strict import validate_extra_args
 from mammoth_cli.runtime.verify import with_verify
@@ -822,6 +823,7 @@ def _execute(invocation: Invocation) -> None:
         invocation = replace(invocation, profile=profiles.get_selected())
 
     def producer() -> tuple[Any, dict[str, Any]]:
+        refuse_hand_crafted_write(invocation.command_id)
         validate.validate_invocation(invocation)
         validate_extra_args(invocation.command_id, invocation.extra_args)
         validate.validate_positional_ids(invocation.command_id, invocation.extra_args)
@@ -885,18 +887,25 @@ def _dry_run(handler: Handler, invocation: Invocation) -> tuple[Any, dict[str, A
     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.dryrun_targets import resolve_targets
+    from mammoth_cli.runtime.dryrun_targets import resolve_dependents, resolve_targets
     from mammoth_cli.runtime.session import open_service, resolved_project
 
     try:
         return handler(invocation)
     except DryRunStop as stop:
         with open_service(invocation) as (service, _auth):
-            targets = resolve_targets(service, invocation.command_id, stop.record["would_call"])
-        return {**stop.record, "targets": targets}, {
-            "profile": invocation.profile,
-            "project_id": resolved_project(invocation),
-        }
+            would_call = stop.record["would_call"]
+            targets = resolve_targets(service, invocation.command_id, would_call)
+            dependents = resolve_dependents(
+                service, invocation.command_id, would_call, resolved_project(invocation)
+            )
+        impact = invocation.predicted_impact
+        report = {**stop.record, "targets": targets}
+        if dependents is not None:
+            report["dependents"] = dependents
+        if impact is not None:
+            report["predicted_impact"] = impact
+        return report, {"profile": invocation.profile, "project_id": resolved_project(invocation)}
 
 
 def _command_help(command_id: str, record: dict[str, Any] | None) -> str | None:

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -25,30 +25,31 @@ transform` command. The data model, capabilities and full web-to-CLI map:
 ## Start
 
 ```bash
-mammoth doctor                          # auth, endpoint, connectivity, version; must succeed
-mammoth project ensure 'PROJECT NAME'   # get-or-create; becomes the active project
+mammoth doctor                          # auth, endpoint, connectivity; must succeed
+mammoth project ensure 'PROJECT NAME'   # get-or-create; active project
 ```
 
-`doctor` failing is a precondition failure; never proceed anyway.
-When the connection check fails with a 502, 504 or timeout, `mammoth doctor
---input '{"wait": 300}'` probes again for up to that many seconds; continue
-only once it passes. Production is the `app` endpoint; use `release` only
-when named, and check `meta.profile`/`auth status` `endpoint` match before
-continuing. If no profile has credentials, tell the operator to run
-`mammoth auth login` in their own terminal (add
-`--profile NAME` only if not `default`; [auth](references/auth.md)
-says where the token comes from) and wait; never ask for the token in chat,
-never read one from a file/env var, never run `auth login`
-yourself. If any envelope carries `meta.update_available`, run its `command`
-before the next step.
-
-In a shell: piped stdout is compact JSON and prompts are off; in a session
-that is not piped, `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once.
-`project ensure` saves the active project (`--project`, `MAMMOTH_PROFILE`
-and `MAMMOTH_PROJECT` override it). `mammoth skill show --input '{"file":
-"references/recipes/transforms.md"}'` prints any file of this skill;
-`mammoth skill agents-md install` writes a steering block into a
-repository's AGENTS.md so later sessions start here.
+Never proceed if `doctor` fails.
+On a 502, 504 or timeout, `mammoth doctor --input '{"wait": 300}'`
+re-probes that long; continue once it passes. Production is the `app` endpoint; use `release` only
+when named, and check `meta.profile`/`auth status` `endpoint` match. If no profile has credentials, tell the operator to run
+`mammoth auth login` in their own terminal (`--profile NAME` unless
+`default`; [auth](references/auth.md) says where the token comes from) and
+wait; never ask for the token in chat, read one from a file/env var, or run
+`auth login` yourself. If an envelope carries `meta.update_available`, run its `command` first.
+
+Piped stdout is compact JSON with prompts off; if not piped, `export
+MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once.
+`project ensure` saves the active project (`--project`, `MAMMOTH_PROFILE`,
+`MAMMOTH_PROJECT` override it). `mammoth skill show --input '{"file":
+"references/recipes/transforms.md"}'` prints any file of this skill.
+
+## Running inside the Mammoth app
+
+Use the project you are given; never `project ensure`. No `doctor`, auth,
+profiles, `config set`, `upgrade`, `skill install`, env vars, local files,
+stdin, `--input FILE` or `output_path` (they fail `not_available_embedded`);
+downloads return `download_url`. On an auth error, ask the user to reload.
 
 ## Defaults you do not repeat
 
@@ -75,7 +76,7 @@ mammoth schema find "join two datasets; remove duplicates; build a dashboard"
 | Combine two datasets on a key (merge, VLOOKUP) | `view transform join`; one value per key: `view transform lookup` |
 | Add rows to an existing dataset, or combine sources | Local file: `file upload FILE --input '{"append_to_ds_id": DATASET_ID}'`. Already in Mammoth: `view export dataset VIEW_ID --input '{"dataset_name": "NAME"}'`, then per further source `view export dataset VIEW_ID --input '{"dataset_name": "NAME", "target_ds_id": DATASET_ID, "save_as_mode": "APPEND_TO_DS"}'` — combine first, clean once; then `discard-duplicates` and diff `row_count` before/after ([about Mammoth](references/about-mammoth.md#view-settings-and-what-has-no-command)) |
 | Keep or remove rows | `view transform filter` |
-| Remove duplicate rows | `view transform discard-duplicates` |
+| Remove duplicate rows | read `duplicates`; 0: stop. Else `view transform discard-duplicates` |
 | Totals, counts, averages per group — just to read the number | `view data aggregate` (read-only: `--input '{"group_by": [...], "aggregations": [{"column": ..., "function": "SUM"}]}'` or `{"metric": {...}}`); never add a `pivot` task just to answer a question |
 | Totals, counts, averages per group — as a lasting change to the pipeline | `view transform pivot` |
 | A calculated column | `view transform math` |
@@ -86,7 +87,7 @@ mammoth schema find "join two datasets; remove duplicates; build a dashboard"
 | Rank, running total, previous row | `view transform window` |
 | A dashboard | `dashboard v3 generate`, then `chat edit` ([dashboards](references/recipes/dashboards.md)) |
 | Deliver the rows | `view export csv`, `view export postgres` (and other destinations), `view export dataset` |
-| Run something on a schedule or on new data (refresh, append, alert) | `automation create`: a condition (`at_specific_time`, new file in a folder, ...) and tasks (`run_data_retrieval`, `append_data`, `send_an_alert`, `pull_cloud_files`). `schedule create` only pulls a connector's data. A dataset from an uploaded file or URL is a one-time copy with no source to refresh; say so. Full recipe, including a known `automation get` backend caveat: [recurring work](references/recipes/scheduling.md) |
+| Run something on a schedule or on new data (refresh, append, alert) | `automation create`: a condition (`at_specific_time`, new file in a folder, ...) and tasks (`run_data_retrieval`, `append_data`, `send_an_alert`, `pull_cloud_files`). `schedule create` only pulls a connector's data. A dataset from an uploaded file or URL is a one-time copy with no source to refresh; say so. Recipe and caveats: [recurring work](references/recipes/scheduling.md) |
 
 Call a find result (or `suggestions` entry) from its `accepted_fields` and
 `agent_example`. Before concluding the CLI cannot do something the web app
@@ -108,7 +109,7 @@ dashboard from t_a and t_b"). Work it out from the data before building:
 2. Find the keys. A column in one view whose values appear in a column of
    the other (`customer_id` and `id`, `order_ref` and `order_no`) is a
    foreign key; the view with many rows per key is the main one.
-3. Make the keys match before the join: same type (`convert-type`), same
+3. Read both key columns, then match the keys: same type (`convert-type`), same
    case and padding (`text`), no blanks (`set-values`, `filter`).
 4. Act on every `column_warnings` entry for a column the deliverable uses:
    run its `fix` (`convert-type` to `NUMERIC`/`DATE`; non-numeric values
@@ -176,8 +177,8 @@ your report. If no column links the files, ask before you combine them.
 - Check an answer with no write against the question (a trend: time
   buckets, a partial period named; no `project check`); a reported number
   comes from `calc`/`view data compare`, never mental math.
-- After a write, run `mammoth project check PROJECT_ID` and fix each
-  `to_report` line, or note it in the report.
+- After a write, run `mammoth project check PROJECT_ID DATASET_ID`; fix
+  only the `to_report` lines your request touches.
 - Run the [report checklist](references/report-checklist.md) before stating
   a number or calling a step done. When files disagree,
   [capabilities](references/capabilities.md) wins over a recipe, then the

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/references/about-mammoth.md

@@ -61,7 +61,7 @@ workspace            account and billing; an API token belongs to one workspace
 | Check data quality in the pipeline | Data Check, Checkpoint Alert | `view data-check create`, `view checkpoint create` |
 | Reuse a value or a SQL block | Parameters, Snippets | `parameter ...`, `snippet ...` |
 | Inspect or restore pipeline history | Version history | `view version list`, `view version apply` |
-| Build a dashboard | Publish | `dashboard create-blank`, `dashboard v3 generate`, `dashboard canvas ...` |
+| Build a dashboard | Publish | `dashboard v3 generate`, `dashboard chat edit` |
 | Deliver data | Export, Send to dataset | `view export csv`, `view export postgres` (and other destinations), `view export dataset` |
 | Automate | Automations | `automation ...`, `workflow ...` |
 | Undo a delete | Trash | `trash list`, `trash restore` |
@@ -146,10 +146,12 @@ No command:
   appends again into the target dataset, not just the first run. To stack
   rows into a brand-new dataset instead of an existing one, omit
   `target_ds_id`. A row present in both sources lands twice: note the
-  appended view's `row_count` (`view get`), run `view transform
-  discard-duplicates` on it (`ignore_columns` for any column you added per
-  source, e.g. a region tag, since it would make shared rows differ), read
-  `row_count` again, and report the difference as duplicates removed.
+  appended view's `row_count` (`view get`) and its `duplicates` fact
+  (`view data get`; zero means nothing to remove: report that and stop). If
+  there are duplicates, run `view transform discard-duplicates` on it
+  (`ignore_columns` for any column you added per source, e.g. a region tag,
+  since it would make shared rows differ), read `row_count` again, and
+  report the difference as duplicates removed.
 - **Hide or reorder columns.** Display changes in the web app; they do not
   change the data.
 

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -418,7 +418,7 @@ Status on release: untried; no live run recorded.
 
 Run: `mammoth view export create`. Exact input fields: `mammoth schema get view.export.create`.
 
-Example: `mammoth view export create 123 --input '{"export_spec": {"DATAVIEW_ID": 1, "handler_type": "postgres", "trigger_type": "none", "target_properties": {"file": "./sales.csv", "file_type": "./sales.csv", "include_hidden": true, "is_format_set": true, "use_format": true}, "additional_properties": {}, "run_immediately": true}}'`. Illustrative only: append `--yes` after observing an owned target.
+Example: `mammoth view export create 123 --input '{"export_spec": {"DATAVIEW_ID": 1, "handler_type": "postgres", "trigger_type": "none", "run_immediately": true}}'`. Illustrative only: append `--yes` after observing an owned target.
 
 Result: `ViewExportCreateResult`; mutation `external_effect`, confirmation `yes_always`, wait policy `returns_job`.
 

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/auth-scope.md

@@ -17,3 +17,7 @@ condition, not permission to retry mutations. The credential rule lives in
 [auth](../auth.md); this recipe does not restate it.
 
 Exit 4 is auth/authorization; preserve the structured error and stop safely.
+
+In the Mammoth app none of the above applies: there is no `auth status`,
+`doctor` or profile, and the app passes the login and project. On exit 4 ask
+the user to reload the page.

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/cleanup.md

@@ -10,9 +10,16 @@ requested dataset, dashboard, view, or export artifact as incidental tidy-up.
 mammoth schema find "trash"
 mammoth schema find "restore"
 mammoth schema get dataset.delete
+mammoth dataset delete OWNED_DATASET_ID --project PROJECT_ID --dry-run
 mammoth dataset delete OWNED_DATASET_ID --project PROJECT_ID --yes
 ```
 
+Run the `--dry-run` first for a dataset, view, task or column delete. Its
+`dependents` block lists the views, dashboards and pipelines that read the
+resource (from `project resource-dependencies`); show it at the confirm step.
+`dependents.checked: false` means the lookup failed, not that nothing depends
+on it: run `project resource-dependencies` yourself before you delete.
+
 Keep an immutable typed baseline: before creating anything, record every
 pre-existing id by type (`project list`, `dataset list`, `dashboard list`,
 `view list DATASET_ID` for each dataset you will touch). Before deleting,

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -2,12 +2,17 @@
 
 `dashboard create` (the legacy AI-generation engine) does not exist as a
 command: it has no handler in current apiv2 (always 404s; historically HTTP
-409 `4DASH012 DASHBOARD_LEGACY_CREATION_RETIRED`). Build a board from one
-sentence with `v3 generate`, and change it with `chat edit`. Author or edit the
-canvas yourself (`create-blank`, `canvas get` then `canvas save`, `pages add`)
-for what a sentence cannot say exactly: units, hiding a built-in tile or
-insight, an exact layout. `dashboard filter add` puts a filter control on a
-board (below).
+409 `4DASH012 DASHBOARD_LEGACY_CREATION_RETIRED`).
+
+**Intent only.** Every dashboard is built and changed from what the user asked
+for, in their own words: `dashboard v3 generate` builds a board, `dashboard chat
+edit` changes one. Pass the user's request as the `intent` / `prompt`; do not
+write canvas JSON, KPI cards, charts, filters or layout yourself, and do not
+work around a request the builder handled badly by hand-crafting the result.
+`dashboard create-blank`, `canvas save`, `canvas restore`, `pages add`,
+`template apply|fit|use|create` and `import-workbook` are for a person at the
+standalone CLI; an in-product run refuses them with `intent_only_dashboards`.
+Reads (`dashboard get`, `canvas get`, `descriptor-data`) are always fine.
 `dashboard source list` is an observed blocker on release (see
 capabilities); verify the view binding with `dashboard get DASHBOARD_ID`
 (`data.sources`) instead.
@@ -26,64 +31,20 @@ Before you say anything about a board that already exists (what a chart shows,
 its numbers, the period it covers), run `dashboard get DASHBOARD_ID`: its
 `values` carry every KPI card's and tile's number and the `period` it counts.
 Answer from those, never from an earlier turn.
+`dashboard get ID` and `dashboard canvas get ID` read by id whichever project is
+active, so a board open in another project needs no `--project`; the result's
+`project_id` names the project it lives in (null when the backend does not say).
 
-Discover page/widget/publish routes and verify the binding, draft/published
-data and terminal jobs. Use only returned IDs and schema confirmation policy;
-do not invent dashboard JSON or opaque task specs.
+Verify the board with `dashboard get DASHBOARD_ID` (binding, `values`) after
+every change. A creation response alone is not proof of a usable published
+view. If the dashboard is requested as a deliverable, keep the dashboard ID
+named in the returned `data` and do not clean it up. Otherwise, classify it
+explicitly as temporary/intermediate before authorizing deletion.
 
-Expected create-blank input is currently typed as
-`{"params":{"dataview_id":VIEW_ID,"title":"TITLE"}}`; confirm with
-`schema get dashboard.create-blank` first. If the dashboard is requested as a
-deliverable, preserve the dashboard ID actually named in the returned `data`
-object and do not clean it up. Otherwise, classify it explicitly as
-temporary/intermediate before authorizing deletion. Then run:
-
-```bash
-mammoth dashboard get DASHBOARD_ID
-mammoth schema find "dashboard page"
-mammoth schema find "dashboard"
-```
-
-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. When the route refuses a chart (for
-example a `pie` that the data does not support), `data.chart_check.refused`
-names it. A new page that got no charts is removed, and
-`data.chart_check.removed_pages` lists it. Add a chart of a different kind
-(`hbar`, `line`, `table`) for that page.
+If the board is not what the user asked for (a wrong chart, a missing unit, a
+tile they do not want), say so in the next `chat edit` prompt in the user's
+words ("show revenue in pounds", "remove the Key insights tile"); the builder
+decides how.
 
 ## "Per region", "per month", "for each X": one board and a filter control
 
@@ -115,32 +76,6 @@ chart that groups by month (`date_bucket`).
 Build only the board you were asked for. If the user wants the board for one
 region only, that is the control's `default`, not a second board.
 
-## Hide a built-in tile or insight
-
-A board's built-in parts (Key insights, the KPI strip, the breakdown, trend and
-table tiles) re-derive from the data, so they cannot be deleted; the product's
-"Remove" hides them: it adds the tile's key to `hidden` on the page. Do the
-same with `canvas save`: read the canvas, add the key to the page's `hidden`,
-write it back.
-
-```bash
-mammoth dashboard canvas get DASHBOARD_ID > canvas.json     # data.canvas is the object to edit
-# pages[0].hidden = ["summary"]            Key insights tile
-#                   ["kpis"]               the whole KPI strip
-#                   ["breakdown", "mix", "secondary", "trend", "table"]   the other built-in tiles
-# canvas.hidden (no pages) is the same list on a canvas without pages
-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
-```
-
-`hidden` sits on the page you mean (`pages[i]`, the page the tile is on), not
-on the canvas root, when the canvas has `pages`. Keep the keys already in the
-list. A single KPI card is removed by taking its entry out of
-`pages[i].focus.kpis`. To hide one insight rather than the whole tile, put its
-tag in `insights.hide` (tags: `leader`, `momentum`, `gap`, `laggard`,
-`concentration`, `secondary`, `peak`, `quality`, `spread`). Read the board back
-with `dashboard canvas get` and check the key is in `hidden`.
-
 ## Put the money on the board
 
 If the data has money (a price, an amount, revenue or cost), the dashboard
@@ -158,20 +93,20 @@ mammoth view transform math VIEW_ID --project PROJECT_ID \
   --input '{"dataset_id":DATASET_ID,"expression":"qty * price","new_column":"revenue"}'
 ```
 
-- Add every column the board needs before `create-blank`. A dashboard sees
-  only the columns the view had when the dashboard was made: `pages add`
-  refuses a later column ("isn't a measure in this data"). If you added it
-  after, make a new dashboard and delete the old one if you made it for this
-  task. The upload result's `before_dashboard` names the column to add.
-- Put revenue in a KPI (`focus.kpis`, `agg` `sum`, `unit.prefix` for the
-  currency) and in one or more charts (revenue by product, by segment, by
-  month). Rows with an empty price give an empty revenue. Say how many there
-  are in your report.
-- `create-blank`, `canvas save` and `pages add` return `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, with the `create-blank` command in `fix`), and one `blank_values` entry for each column on the board that has blanks.
-  Fix each warning, or say in your report why you kept it.
+- Add every column the board needs before `v3 generate`. A dashboard sees
+  only the columns the view had when the dashboard was made; a later column
+  is not on it. If you added it after, generate a new dashboard and delete the
+  old one if you made it for this task. The upload result's `before_dashboard`
+  names the column to add.
+- Ask for the money in the intent ("revenue by product, by segment and by
+  month, with a revenue card"). Rows with an empty price give an empty
+  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.
+  Fix each warning (add the column, then ask again in words), or say in your
+  report why you kept it.
 
 **Read the bindings back, then the numbers.** `dashboard canvas get` returns
 `data.meta.figures` — `"p1:kpi:2": {"descriptors": {"value": "<id>"}}` per
@@ -190,15 +125,9 @@ 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:
-
-```bash
-mammoth dashboard canvas get DASHBOARD_ID   # data.canvas incl. style_tokens
-mammoth dashboard canvas save DASHBOARD_ID --input '{"body":{"params":{"canvas":CANVAS_FROM_GET}}}'
-```
-
-`canvas save` with `{"canvas": {}}` fails (`dataset` and other fields are
-required); the object returned by `canvas get` is the only known-good shape.
+`dashboard canvas get DASHBOARD_ID` reads the canvas (`data.canvas` incl.
+`style_tokens`). It is for reading; change a board with `chat edit`, never by
+writing a canvas back.
 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
@@ -257,3 +186,13 @@ returns the plaintext signing secret once, never on a read) and `dashboard
 embed lifetime set WORKSPACE_ID --input '{"token_ttl": 900}'` (60-3600
 seconds, how long a minted embed viewer session lives).
 
+
+## Pin a dashboard, file it "under" a name
+
+Pinning is a per-user preference: `user preference get`, read
+`GLOBAL.DASHBOARDS.pinned_ids`, then write the whole list back with the id
+appended as a string: `user preference update --input
+'{"patch":[{"op":"replace","path":"global.dashboards","value":{"pinned_ids":["123"]}}]}'`
+(unpin = write it without the id). Dashboards live in no folder, so
+`folder move` cannot file one; the library groups by tags: `dashboard tags set
+DASHBOARD_ID --input '{"tags":["Finance"]}' --yes --confirm DASHBOARD_ID`.

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/exports.md

@@ -23,7 +23,8 @@ reconciliation before replay.
 Representative successful local export data is typically an envelope with a
 returned export/artifact identifier or path under `data`; verify that path is
 owned, exists, has the expected schema/row count, and hash it. If the command
-returns `job_id`, read it until terminal success before inspecting the artifact.
+returns `job_id`, run `mammoth job wait JOB_ID` (not a hand-rolled poll of
+`job get`) and read the result once before inspecting the artifact.
 If `schema get view.export.csv` rejects requested fields, preserve the
 structured error and discover another declared export route rather than using
 raw HTTP.

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/need-action.md

@@ -28,11 +28,13 @@ mammoth dataset file-settings update DATASET_ID --project PROJECT_ID \
   --input '{"delimiter": ",", "has_header": true, "initial_skip_count": 0, "quotechar": "\"", "date_format": "US"}'
 ```
 
-The response is a job (`operation: "understand_csv"`). Poll `dataset get`
-(the record is under `data.dataset`, so read `data.dataset.status`) until
-the status leaves `need_action`. It usually reaches `ready` within seconds;
-on prague an ISO `YYYY-MM-DD` column was flagged ambiguous and took about
-three minutes, so poll for up to five minutes before treating it as stuck.
+The response is a job (`operation: "understand_csv"`). Run
+`mammoth job wait JOB_ID` on its `job_id` instead of polling by hand, then
+read `dataset get` once (the record is under `data.dataset`, so read
+`data.dataset.status`) to confirm the status left `need_action`. It usually
+reaches `ready` within seconds; on prague an ISO `YYYY-MM-DD` column was
+flagged ambiguous and took about three minutes, so allow up to five minutes
+before treating it as stuck.
 Then `view list` returns the generated view and typed transforms can
 proceed. Every environment can ask, release included: on 2026-09-24 release
 flagged an ISO `YYYY-MM-DD` column too and reached `ready` within seconds of

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/resources.md

@@ -10,6 +10,10 @@ Discover exact contracts, then upload and read back explicit parents.
 
 ## Where uploads land
 
+In the Mammoth app, use the project you are given and never run `project
+ensure` or `project create` for a scratch project; the rest of this section is
+for the CLI in a terminal.
+
 Unless the task names a project, work in one project of your own and put
 every dataset of the task there. The user's real projects then stay clean, and
 one sweep removes everything. `project ensure` is idempotent get-or-create

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/scheduling.md

@@ -37,7 +37,7 @@ mammoth automation create 'Nightly refresh' --yes --input '{
   ],
   "conditions": [
     {"condition_type": "at_specific_time", "details": {
-      "frequency": "daily", "interval": 1, "start_at": "2026-01-01T02:00:00Z"
+      "frequency": "daily", "interval": 1, "start_at": "2027-01-01T02:00:00Z"
     }}
   ]
 }'
@@ -71,7 +71,7 @@ mammoth automation create 'Monthly brand spend to client' --yes --input '{
   ],
   "conditions": [
     {"condition_type": "at_specific_time", "details": {
-      "frequency": "monthly", "interval": 1, "start_at": "2026-01-01T02:00:00Z"
+      "frequency": "monthly", "interval": 1, "start_at": "2027-01-01T02:00:00Z"
     }}
   ]
 }'
@@ -102,6 +102,21 @@ automation.create` under `tasks[].details`:
 or via its other condition types (new file in a folder, etc.), not on a
 recurrence.
 
+## Create once: list first, update instead of create
+
+`automation create` is not idempotent: running it twice makes two
+automations that both fire (two client emails a month). Before every create:
+
+```bash
+mammoth automation list        # is there already one with this name or these recipients?
+```
+
+If one exists, change it with `automation update AUTOMATION_ID` (see below)
+instead of creating another. Before a schedule that emails a client, send the
+same email to the user first (or `--dry-run` the create and show the
+recipients, subject and attached views) and get a yes. Give `start_at` a time
+in the future; a past `start_at` may fire straight away or never.
+
 ## Read it back
 
 ```bash
@@ -123,7 +138,8 @@ matching the empty response body (a normal validation error returns a JSON
 envelope; this does not). Do not report "the automation vanished"; if `get`
 or `list` fail this way right after a create, treat the create's own 200/202
 response and `automation_id` as the source of truth, and say so in the
-report. This is not something the CLI can work around — do not retry
+report as "created, unconfirmed" (the create returned 200 but the read-back
+failed): never re-run the create to "fix" it, which makes a duplicate. This is not something the CLI can work around — do not retry
 `automation get` more than once for this.
 
 ## Update: disable / enable, change tasks, run now
@@ -155,7 +171,7 @@ mammoth automation trash AUTOMATION_ID           # reversible; automation.restor
 ```bash
 mammoth schema get schedule.create
 mammoth schedule create --yes --input '{"spec": {
-  "rrule": {"frequency": "daily", "start": "2026-01-01T02:00:00Z"},
+  "rrule": {"frequency": "daily", "start": "2027-01-01T02:00:00Z"},
   "work_items": [{"name": "pull_cloud_data", "execution_params": {
     "schedule_type": "moment", "first_pull_at": "now", "on_refresh_action": "replace"
   }, "args": [DATASET_ID]}]

{mammoth_cli-2.0.91 → mammoth_cli-2.1.0}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/transforms.md

@@ -38,8 +38,9 @@ Compare the two reads: the row count is unchanged, the rows that were blank
 now read `0`, and every non-blank value is identical to the before-sample.
 If every row now reads `0`, or a non-blank value changed, the condition was
 dropped: stop, do not build joins or summaries on this view, and report it.
-Use `view data get` (paged, 400 rows per page) for this, not `view preview`
-(50 rows), and sample from more than one page on a large view.
+Use `view data get` (paged, 50 rows per page by default; pass `limit` and
+`offset` for more) for this, not `view preview`, and sample from more than
+one page on a large view.
 
 - `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
@@ -84,9 +85,12 @@ In a math `expression`, write a multi-word display name bare (`Quantity * Unit
 Price`) or quoted (`Quantity * \"Unit Price\"` inside the JSON string).
 
 The released catalog exposes typed dedupe through `schema find duplicate` as
-`view.transform.discard-duplicates`. Inspect its optional `ignore_columns`
-field before submitting. For a join, verify both schemas and
-expected multiplicity:
+`view.transform.discard-duplicates`. Observe before writing: `view data get`
+states `duplicates` (`exact_duplicate_rows` over `rows_checked` of `row_count`;
+on a later page it names the table-wide check). When it is 0, report "none,
+no change needed" and add no step. Only then inspect its optional
+`ignore_columns` field and submit; `--dry-run` reports `predicted_impact` or
+fails `no_op`. For a join, verify both schemas and expected multiplicity:
 
 ```bash
 mammoth schema get view.transform.discard-duplicates
@@ -111,9 +115,12 @@ as defaults, and let the user's request override them:
 - Joins are nearly always `LEFT` on one key column. Use `INNER`, `RIGHT`,
   `OUTER` or a key of two or more columns only when the user asks for it or
   the data needs it, and say why in your report.
-- Check the key before a join or lookup. Most keys go in without a prep
-  step, so a type, case or padding difference shows up as unmatched rows. Read
-  both key columns first (`view data get`) and act on `join_check`.
+- Always read both key columns before a join or lookup (`view data get`, and
+  `view data profile` for blanks and spelling), then run the join with
+  `--dry-run`: its `join_preview` gives `match_rate` and `unmatched_keys`
+  without writing. A low rate means a type, case or padding difference: fix
+  the keys first (`convert-type`, `text`). After the real join, act on
+  `join_check`.
 - Date steps (`increment-date`, `extract-date`, and `text` on date columns)
   fail more often than other steps. Before a date step, confirm that the
   column type is `DATE` (`view get`); if it is `TEXT`, run `convert-type`
@@ -198,6 +205,11 @@ values you are summing.
   `view list` returns `data.dataviews[]`, `view data get` returns rows keyed by
   display name. Read the envelope you got, not the one you expected.
 
+Read-only way to answer a by-weekday or by-month question: `view data aggregate`
+with a `part` group, for example `--input '{"group_by": [{"column": "Order Date",
+"part": "weekday"}], "aggregations": [{"column": "Sales", "function": "SUM",
+"as_name": "Total"}], "order_by": ["Total desc"]}'`. Do not build a temporary view.
+
 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.