mammoth-cli 2.0.87__tar.gz → 2.0.88__tar.gz

{mammoth_cli-2.0.87 → mammoth_cli-2.0.88}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.87
+Version: 2.0.88
 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.87 → mammoth_cli-2.0.88}/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.87"
+__version__ = "2.0.88"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.87 → mammoth_cli-2.0.88}/mammoth_cli/bundled_skill/mammoth-cli/references/command-index.md

@@ -1,6 +1,6 @@
 # Published CLI command catalog
 
-This generated catalog is a lookup table for every command in the published CLI manifest, currently 576; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
+This generated catalog is a lookup table for every command in the published CLI manifest, currently 579; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
 
 Load only the applicable domain file:
 
@@ -22,7 +22,8 @@ Load only the applicable domain file:
 - [connector](commands/connector.md) — 22 published commands
 - [context](commands/context.md) — 3 published commands
 - [dashboard-qa](commands/dashboard-qa.md) — 13 published commands
-- [dashboard](commands/dashboard.md) — 100 published commands
+- [dashboard-style](commands/dashboard-style.md) — 10 published commands
+- [dashboard](commands/dashboard.md) — 93 published commands
 - [data-app](commands/data-app.md) — 12 published commands
 - [dataset](commands/dataset.md) — 20 published commands
 - [doctor](commands/doctor.md) — 1 published commands

mammoth_cli-2.0.88/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dashboard-style.md

@@ -0,0 +1,103 @@
+# `dashboard-style` commands
+
+Every command returns the standard JSON envelope. On nonzero exit, read the error envelope and its `recovery_commands`; do not guess request fields. "Status on release" is joined from `docs/release-capability-matrix.json`: *ran once* means one bounded live run succeeded on the named CLI release, *untried* means nobody has run it, *not supported* means the backend refuses it. When this file disagrees with [capabilities](../capabilities.md) or a recipe, they win. Envelope shapes: [machine output](../machine-output.md).
+
+### `dashboard.style.custom.create`
+
+Run: `mammoth dashboard style custom create`. Exact input fields: `mammoth schema get dashboard.style.custom.create`.
+
+Example: `mammoth dashboard style custom create --input '{"body": {"params": {"signals": {}}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardStyleCustomCreateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+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: style. created custom style id=1 with full unredacted colors/font/viz (no tokens field passed) Single invocation only; no error-path or variant coverage.
+
+### `dashboard.style.custom.delete`
+
+Run: `mammoth dashboard style custom delete`. Exact input fields: `mammoth schema get dashboard.style.custom.delete`.
+
+Example: `mammoth dashboard style custom delete resource-123`. Illustrative only: append `--yes` after observing an owned target.
+
+Result: `DashboardStyleCustomDeleteResult`; mutation `destructive`, confirmation `prompt_or_yes`, wait policy `not_async`.
+
+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: ok. deleted custom style 1 Single invocation only; no error-path or variant coverage.
+
+### `dashboard.style.custom.list`
+
+Run: `mammoth dashboard style custom list`. Exact input fields: `mammoth schema get dashboard.style.custom.list`.
+
+Example: `mammoth dashboard style custom list`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardStyleCustomListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: ran once on CLI 2.0.12 — Bounded release read succeeded with pinned CLI 1.1.9 in workspace 4; empty custom-style list observed. No Full claim: no non-empty fixture. Also: Dashboard sweep 2026-09-18: exit 0 on release with CLI 2.0.12; result keys: styles. empty custom styles list Sing…
+
+### `dashboard.style.custom.update`
+
+Run: `mammoth dashboard style custom update`. Exact input fields: `mammoth schema get dashboard.style.custom.update`.
+
+Example: `mammoth dashboard style custom update resource-123 --input '{"body": {"params": {"signals": {}}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardStyleCustomUpdateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+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: style. renamed custom style 1 Single invocation only; no error-path or variant coverage.
+
+### `dashboard.style.default.get`
+
+Run: `mammoth dashboard style default get`. Exact input fields: `mammoth schema get dashboard.style.default.get`.
+
+Example: `mammoth dashboard style default get`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardStyleDefaultGetResult`; mutation `read`, 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: returned a real matched body {"styleId":"stone"} instead of raising ValidationError on an unmatched 2xx. Single invocation only.
+
+### `dashboard.style.default.set`
+
+Run: `mammoth dashboard style default set`. Exact input fields: `mammoth schema get dashboard.style.default.set`.
+
+Example: `mammoth dashboard style default set --input '{"body": {"params": {"styleId": "sample"}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardStyleDefaultSetResult`; 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. Set styleId to the exact value read from style default get ("stone"), i.e. a verified no-op restore. Result {"styleId":"stone"}; re-ran style default get afterward and confirmed it still…
+
+### `dashboard.style.derive`
+
+Run: `mammoth dashboard style derive`. Exact input fields: `mammoth schema get dashboard.style.derive`.
+
+Example: `mammoth dashboard style derive --input '{"body": {"params": {"signals": {}}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardStyleDeriveResult`; 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: returned a full real styleTokens object (colors, font, viz palette, radius, shadow, etc.) with no '***REDACTED***' placeholders anywhere in the body. Single…
+
+### `dashboard.style.extract-brand`
+
+Run: `mammoth dashboard style extract-brand`. Exact input fields: `mammoth schema get dashboard.style.extract-brand`.
+
+Example: `mammoth dashboard style extract-brand --input '{"body": {"params": {"url": "https://example.com/data.csv"}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardStyleExtractBrandResult`; 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: screenshot, signals. captured screenshot + extracted brand signals (accents/font/ground/primary), no redaction here Single invocation only; no error-path or variant coverage.
+
+### `dashboard.style.preset.list`
+
+Run: `mammoth dashboard style preset list`. Exact input fields: `mammoth schema get dashboard.style.preset.list`.
+
+Example: `mammoth dashboard style preset list`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardStylePresetListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: ran once on CLI 2.0.12 — Bounded release read succeeded with pinned CLI 1.1.9 in workspace 4; 10 stock presets returned. No Full claim: custom preset fixture not observed. Also: Dashboard sweep 2026-09-18: exit 0 on release with CLI 2.0.12; result keys: presets. returns built-in styl…
+
+### `dashboard.style.token.list`
+
+Run: `mammoth dashboard style token list`. Exact input fields: `mammoth schema get dashboard.style.token.list`.
+
+Example: `mammoth dashboard style token list resource-123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardStyleTokenListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: ran once on CLI 1.1.11 — Published PyPI CLI 1.1.11 / SDK 0.7.1 read of observed preset stone returned a redacted token payload. Bounded to one preset and redacted semantics; not Full. Dashboard sweep 2026-09-18 on release observed cli_error: HTTP 200 but result is tokens='***REDACTED…

{mammoth_cli-2.0.87 → mammoth_cli-2.0.88}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dashboard.md

@@ -342,6 +342,36 @@ Result: `DashboardFigureIntentResult`; mutation `benign_mutation`, confirmation
 
 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: returned a full matched structured body ({"added":{...},"kind":"bar","spec":{...},"intentApplied":true,...}) instead of raising ValidationError on an unmatch…
 
+### `dashboard.filter.add`
+
+Run: `mammoth dashboard filter add`. Exact input fields: `mammoth schema get dashboard.filter.add`.
+
+Example: `mammoth dashboard filter add 123 --input '{"field": "sample"}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardFilterResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `dashboard.filter.list`
+
+Run: `mammoth dashboard filter list`. Exact input fields: `mammoth schema get dashboard.filter.list`.
+
+Example: `mammoth dashboard filter list 123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardFilterResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
+### `dashboard.filter.remove`
+
+Run: `mammoth dashboard filter remove`. Exact input fields: `mammoth schema get dashboard.filter.remove`.
+
+Example: `mammoth dashboard filter remove 123 --input '{"field": "sample"}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `DashboardFilterResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `dashboard.get`
 
 Run: `mammoth dashboard get`. Exact input fields: `mammoth schema get dashboard.get`.
@@ -650,106 +680,6 @@ Result: `DashboardSourceListResult`; mutation `read`, confirmation `none`, wait
 
 Status on release: observed blocker — blocker; still broken, not one of the 11 CLI-fixed commands. Re-check before relying on it.
 
-### `dashboard.style.custom.create`
-
-Run: `mammoth dashboard style custom create`. Exact input fields: `mammoth schema get dashboard.style.custom.create`.
-
-Example: `mammoth dashboard style custom create --input '{"body": {"params": {"signals": {}}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
-
-Result: `DashboardStyleCustomCreateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
-
-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: style. created custom style id=1 with full unredacted colors/font/viz (no tokens field passed) Single invocation only; no error-path or variant coverage.
-
-### `dashboard.style.custom.delete`
-
-Run: `mammoth dashboard style custom delete`. Exact input fields: `mammoth schema get dashboard.style.custom.delete`.
-
-Example: `mammoth dashboard style custom delete resource-123`. Illustrative only: append `--yes` after observing an owned target.
-
-Result: `DashboardStyleCustomDeleteResult`; mutation `destructive`, confirmation `prompt_or_yes`, wait policy `not_async`.
-
-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: ok. deleted custom style 1 Single invocation only; no error-path or variant coverage.
-
-### `dashboard.style.custom.list`
-
-Run: `mammoth dashboard style custom list`. Exact input fields: `mammoth schema get dashboard.style.custom.list`.
-
-Example: `mammoth dashboard style custom list`. Placeholders are illustrative; resolve IDs and input from observed reads.
-
-Result: `DashboardStyleCustomListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
-
-Status on release: ran once on CLI 2.0.12 — Bounded release read succeeded with pinned CLI 1.1.9 in workspace 4; empty custom-style list observed. No Full claim: no non-empty fixture. Also: Dashboard sweep 2026-09-18: exit 0 on release with CLI 2.0.12; result keys: styles. empty custom styles list Sing…
-
-### `dashboard.style.custom.update`
-
-Run: `mammoth dashboard style custom update`. Exact input fields: `mammoth schema get dashboard.style.custom.update`.
-
-Example: `mammoth dashboard style custom update resource-123 --input '{"body": {"params": {"signals": {}}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
-
-Result: `DashboardStyleCustomUpdateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
-
-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: style. renamed custom style 1 Single invocation only; no error-path or variant coverage.
-
-### `dashboard.style.default.get`
-
-Run: `mammoth dashboard style default get`. Exact input fields: `mammoth schema get dashboard.style.default.get`.
-
-Example: `mammoth dashboard style default get`. Placeholders are illustrative; resolve IDs and input from observed reads.
-
-Result: `DashboardStyleDefaultGetResult`; mutation `read`, 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: returned a real matched body {"styleId":"stone"} instead of raising ValidationError on an unmatched 2xx. Single invocation only.
-
-### `dashboard.style.default.set`
-
-Run: `mammoth dashboard style default set`. Exact input fields: `mammoth schema get dashboard.style.default.set`.
-
-Example: `mammoth dashboard style default set --input '{"body": {"params": {"styleId": "sample"}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
-
-Result: `DashboardStyleDefaultSetResult`; 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. Set styleId to the exact value read from style default get ("stone"), i.e. a verified no-op restore. Result {"styleId":"stone"}; re-ran style default get afterward and confirmed it still…
-
-### `dashboard.style.derive`
-
-Run: `mammoth dashboard style derive`. Exact input fields: `mammoth schema get dashboard.style.derive`.
-
-Example: `mammoth dashboard style derive --input '{"body": {"params": {"signals": {}}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
-
-Result: `DashboardStyleDeriveResult`; 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: returned a full real styleTokens object (colors, font, viz palette, radius, shadow, etc.) with no '***REDACTED***' placeholders anywhere in the body. Single…
-
-### `dashboard.style.extract-brand`
-
-Run: `mammoth dashboard style extract-brand`. Exact input fields: `mammoth schema get dashboard.style.extract-brand`.
-
-Example: `mammoth dashboard style extract-brand --input '{"body": {"params": {"url": "https://example.com/data.csv"}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
-
-Result: `DashboardStyleExtractBrandResult`; 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: screenshot, signals. captured screenshot + extracted brand signals (accents/font/ground/primary), no redaction here Single invocation only; no error-path or variant coverage.
-
-### `dashboard.style.preset.list`
-
-Run: `mammoth dashboard style preset list`. Exact input fields: `mammoth schema get dashboard.style.preset.list`.
-
-Example: `mammoth dashboard style preset list`. Placeholders are illustrative; resolve IDs and input from observed reads.
-
-Result: `DashboardStylePresetListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
-
-Status on release: ran once on CLI 2.0.12 — Bounded release read succeeded with pinned CLI 1.1.9 in workspace 4; 10 stock presets returned. No Full claim: custom preset fixture not observed. Also: Dashboard sweep 2026-09-18: exit 0 on release with CLI 2.0.12; result keys: presets. returns built-in styl…
-
-### `dashboard.style.token.list`
-
-Run: `mammoth dashboard style token list`. Exact input fields: `mammoth schema get dashboard.style.token.list`.
-
-Example: `mammoth dashboard style token list resource-123`. Placeholders are illustrative; resolve IDs and input from observed reads.
-
-Result: `DashboardStyleTokenListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
-
-Status on release: ran once on CLI 1.1.11 — Published PyPI CLI 1.1.11 / SDK 0.7.1 read of observed preset stone returned a redacted token payload. Bounded to one preset and redacted semantics; not Full. Dashboard sweep 2026-09-18 on release observed cli_error: HTTP 200 but result is tokens='***REDACTED…
-
 ### `dashboard.suggestion.list`
 
 Run: `mammoth dashboard suggestion list`. Exact input fields: `mammoth schema get dashboard.suggestion.list`.

{mammoth_cli-2.0.87 → mammoth_cli-2.0.88}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -3,8 +3,11 @@
 `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 a canvas by
-hand (`create-blank`, `canvas save`, `pages add`) only when asked to.
+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).
 `dashboard source list` is an observed blocker on release (see
 capabilities); verify the view binding with `dashboard get DASHBOARD_ID`
 (`data.sources`) instead.
@@ -19,6 +22,11 @@ mammoth dashboard get DASHBOARD_ID
 `chat edit` returns `changed` and a one-line `message`. Quote one number from
 the board before you report it done.
 
+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.
+
 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.
@@ -77,6 +85,62 @@ 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.
 
+## "Per region", "per month", "for each X": one board and a filter control
+
+A request for a board "per <dimension>" (per region, per month, per rep, by
+status) is ONE board with a **filter control** on that column: the viewer picks
+the value. Do not build a copy of the board for each value. Build the board
+once, then add the control:
+
+```bash
+mammoth dashboard filter add DASHBOARD_ID --input '{"field": "Region"}'
+mammoth dashboard filter list DASHBOARD_ID
+mammoth dashboard filter remove DASHBOARD_ID --input '{"field": "Region"}'
+```
+
+`field` is a column of the board's data. `control` is optional: leave it out
+and the column's type picks one (a category gets a selection list, a number or
+a date gets a range). Set it to choose: `dropdown`, `chips`, `multi` or
+`search` for a category, `range` for a number or a date, `motion` for a date
+that plays over time. `label` is the text the viewer sees, and `default` (a
+list of values) is what is selected when the board opens:
+`--input '{"field": "Region", "control": "dropdown", "label": "Region", "default": ["North"]}'`.
+A second `add` on the same column replaces the first. The command refuses a
+column the board does not have (and names the columns it has) and a control
+the column's type cannot take. Its result carries the declared `filters` and a
+`bake_job_id`; `dashboard filter list` reads them back. Say "per month" the same
+way: a filter on the date column with `range`, or `dashboard chat edit` for a
+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

{mammoth_cli-2.0.87 → mammoth_cli-2.0.88}/mammoth_cli/commands/dashboard.py

@@ -10,6 +10,7 @@ SDK method named by the command's reviewed manifest ``sdk_symbol``.
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any, Literal, cast
 
@@ -41,6 +42,12 @@ from mammoth_cli.runtime.session import open_service, require_project, resolved_
 from mammoth_cli.services.argspec import arg_spec
 from mammoth_cli.services.board_values import board_values, dashboard_link
 from mammoth_cli.services.command_contract import bind_command_inputs
+from mammoth_cli.services.dashboard_filters import (
+    check_filter,
+    declared,
+    with_filter,
+    without_filter,
+)
 from mammoth_cli.services.dashboard_pages import check_added_pages
 from mammoth_cli.services.dashboard_review import (
     CANVAS_GET,
@@ -369,10 +376,16 @@ def dashboard_tags_merge(invocation: Invocation) -> HandlerResult:
 
 
 def dashboard_get(invocation: Invocation) -> HandlerResult:
-    """Get one dashboard by id."""
+    """Get one dashboard by id, with each KPI card's and tile's number and period.
+
+    A question about an existing board is answered from what it shows, so the
+    read carries the numbers, not only the definitions (UQA-RT10-02).
+    """
     dashboard_id = _require_int_positional(invocation, "dashboard id")
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), dashboard_id=dashboard_id)
+        if not invocation.readback:
+            data = _with_board_values(service, auth, {"dashboard_id": dashboard_id}, data)
     return data, _meta(invocation, auth.workspace_id)
 
 
@@ -771,6 +784,62 @@ def _with_deliverable_check(
     return data
 
 
+_CANVAS_SAVE = "mammoth.api.dashboards.DashboardsAPI.canvas_save"
+_FILTER_KEYS = ("field", "control", "label", "default")
+
+
+def _edit_filters(
+    invocation: Invocation, edit: Callable[[dict[str, Any]], dict[str, Any]]
+) -> HandlerResult:
+    """Read the draft canvas, apply ``edit`` to the read, save it, and return the filters."""
+    dashboard_id = _require_int_positional(invocation, "dashboard id")
+    with open_service(invocation) as (service, auth):
+        current = _dump_model(service.call(CANVAS_GET, dashboard_id=dashboard_id))
+        canvas = edit(current)
+        saved = _dump_model(
+            service.call(
+                _CANVAS_SAVE,
+                dashboard_id=dashboard_id,
+                body={"params": {"canvas": canvas, "base_sequence": current["meta"]["sequence"]}},
+            )
+        )
+    result = {
+        "dashboard_id": dashboard_id,
+        "filters": declared(canvas),
+        "sequence": saved.get("sequence"),
+        "bake_job_id": saved.get("bake_job_id"),
+    }
+    return result, _meta(invocation, auth.workspace_id)
+
+
+def dashboard_filter_add(invocation: Invocation) -> HandlerResult:
+    """Add (or replace) the filter control on one column of a board."""
+    document = _bound_document(invocation)
+    _require_field(document, "field")
+    entry = {key: document[key] for key in _FILTER_KEYS if document.get(key) is not None}
+
+    def edit(current: dict[str, Any]) -> dict[str, Any]:
+        check_filter(current, entry)
+        return with_filter(current["canvas"], entry)
+
+    return _edit_filters(invocation, edit)
+
+
+def dashboard_filter_remove(invocation: Invocation) -> HandlerResult:
+    """Remove the filter control on one column of a board."""
+    field = str(_require_field(_bound_document(invocation), "field"))
+    return _edit_filters(invocation, lambda current: without_filter(current["canvas"], field))
+
+
+def dashboard_filter_list(invocation: Invocation) -> HandlerResult:
+    """List the filter controls a board declares."""
+    dashboard_id = _require_int_positional(invocation, "dashboard id")
+    with open_service(invocation) as (service, auth):
+        current = _dump_model(service.call(CANVAS_GET, dashboard_id=dashboard_id))
+    result = {"dashboard_id": dashboard_id, "filters": declared(current["canvas"])}
+    return result, _meta(invocation, auth.workspace_id)
+
+
 def dashboard_assess_twb(invocation: Invocation) -> HandlerResult:
     """Assess a local Tableau workbook through the SDK multipart seam."""
     file_path = _require_str_positional(invocation, "file")

{mammoth_cli-2.0.87 → mammoth_cli-2.0.88}/mammoth_cli/commands/registry.py

@@ -404,6 +404,9 @@ HANDLERS: dict[str, Handler] = {
     "dashboard.data.published": dashboard_cmd.dashboard_data_published,
     "dashboard.delete": dashboard_cmd.dashboard_delete,
     "dashboard.get": dashboard_cmd.dashboard_get,
+    "dashboard.filter.add": dashboard_cmd.dashboard_filter_add,
+    "dashboard.filter.list": dashboard_cmd.dashboard_filter_list,
+    "dashboard.filter.remove": dashboard_cmd.dashboard_filter_remove,
     "dashboard.get-by-url": dashboard_cmd.dashboard_get_by_url,
     "dashboard.job-by-url": dashboard_cmd.dashboard_job_by_url,
     "dashboard.list": dashboard_cmd.dashboard_list,

{mammoth_cli-2.0.87 → mammoth_cli-2.0.88}/mammoth_cli/commands/view_profile.py

@@ -361,32 +361,47 @@ def _paged_columns(details: dict[str, dict[str, Any]], limit: int) -> dict[str,
 def _variant_report(
     scope: _Scope, names: list[str], tables: dict[str, dict[Any, int] | None]
 ) -> list[dict[str, Any]]:
-    """Per TEXT column, spellings of one value (Ltd/Limited, case, punctuation) and the fix."""
+    """Per TEXT column, spellings of one value (Ltd/Limited, case, punctuation) and the fix.
+
+    ``likely_groups`` are names that differ only by a legal form or a connector
+    (``TECNOLAB`` / ``TECNOLAB S.A.``): proposed, never merged without a yes.
+    """
     report: list[dict[str, Any]] = []
     for name in names:
         table = tables.get(name)
         if table is None or scope.types.get(name) != "TEXT":
             continue
-        groups = dp.variant_groups({k: v for k, v in table.items() if isinstance(k, str)})
-        if not groups:
+        texts = {k: v for k, v in table.items() if isinstance(k, str)}
+        groups, likely = dp.variant_groups(texts), dp.likely_groups(texts)
+        if not groups and not likely:
             continue
-        shown = groups[:_MAX_VARIANT_GROUPS]
-        body = {**dp.bulk_replace_input(name, shown), "dataset_id": scope.dataset_id}
-        report.append(
-            {
-                "column": name,
-                "groups_total": len(groups),
-                "groups": shown,
-                "bulk_replace": body,
-                "command": (
-                    f"mammoth view transform bulk-replace {scope.view_id} "
-                    f"--input {shlex.quote(json.dumps(body))}"
-                ),
-            }
-        )
+        entry: dict[str, Any] = {"column": name, **_merge_fix(scope, name, groups)}
+        if likely:
+            entry["likely_groups"] = {"note": _LIKELY_NOTE, **_merge_fix(scope, name, likely)}
+        report.append(entry)
     return report
 
 
+_LIKELY_NOTE = (
+    "Same name apart from a legal form or a connector word; confirm with the user "
+    "before merging (SRL and SA can be two companies)."
+)
+
+
+def _merge_fix(scope: _Scope, column: str, groups: list[dict[str, Any]]) -> dict[str, Any]:
+    """The groups shown and the bulk-replace that merges them."""
+    shown = groups[:_MAX_VARIANT_GROUPS]
+    fix: dict[str, Any] = {"groups_total": len(groups), "groups": shown}
+    if not shown:
+        return fix
+    body = {**dp.bulk_replace_input(column, shown), "dataset_id": scope.dataset_id}
+    command = (
+        f"mammoth view transform bulk-replace {scope.view_id} "
+        f"--input {shlex.quote(json.dumps(body))}"
+    )
+    return {**fix, "bulk_replace": body, "command": command}
+
+
 # -- target vs column ----------------------------------------------------------------------
 
 

{mammoth_cli-2.0.87 → mammoth_cli-2.0.88}/mammoth_cli/runtime/invocation.py

@@ -76,6 +76,9 @@ class Invocation:
     # handler so its verify and readback reads address the view directly
     # instead of walking every dataset to find it.
     known_dataset_id: int | None = field(default=None, repr=False, compare=False)
+    # Set on the read a write's ``state`` block issues: that read confirms the
+    # write, so a command's extra evaluation (a board's numbers) is skipped.
+    readback: bool = field(default=False, repr=False, compare=False)
     _prepared_input: object = field(
         default=_UNINITIALIZED_INPUT, init=False, repr=False, compare=False
     )

{mammoth_cli-2.0.87 → mammoth_cli-2.0.88}/mammoth_cli/runtime/state.py

@@ -196,6 +196,7 @@ def _read_invocation(command_id: str, resolved_ids: dict[str, Any], base: Invoca
         no_input=True,
         positionals=positionals,
         extra_args=extra_args,
+        readback=True,
     )
     object.__setattr__(invocation, "_prepared_input", document or None)
     return invocation

{mammoth_cli-2.0.87 → mammoth_cli-2.0.88}/mammoth_cli/services/command_contract.py

@@ -351,6 +351,22 @@ _VIEW_DATA_PROFILE_FIELDS = (
     FieldSpec("limit", required=False, annotation=int, default=50),
 )
 
+# dashboard.filter.add/remove are CLI composites over canvas get + canvas save
+# (DashboardsAPI.canvas_save is named in the manifest as the SDK anchor); the
+# canvas body is built by the handler, so the document carries only the filter.
+_DASHBOARD_FILTER_ADD_FIELDS = (
+    FieldSpec("field", required=True, annotation=str),
+    FieldSpec(
+        "control",
+        required=False,
+        annotation=Literal["multi", "dropdown", "chips", "search", "range", "motion"] | None,
+        default=None,
+    ),
+    FieldSpec("label", required=False, annotation=str | None, default=None),
+    FieldSpec("default", required=False, annotation=list[str] | None, default=None),
+)
+_DASHBOARD_FILTER_REMOVE_FIELDS = (FieldSpec("field", required=True, annotation=str),)
+
 # The remaining S1 commands are intentionally closed zero-input commands.  A
 # command may still receive ordinary positional/context values; those are
 # represented by ``positionals`` and never become structured-input keys.
@@ -725,6 +741,12 @@ def resolve_command_contract(command_id: str) -> ResolvedCommandContract | None:
         special_fields = _VIEW_DATA_COMPARE_FIELDS
     elif command_id == "view.data.profile":
         special_fields = _VIEW_DATA_PROFILE_FIELDS
+    elif command_id == "dashboard.filter.add":
+        special_fields = _DASHBOARD_FILTER_ADD_FIELDS
+    elif command_id == "dashboard.filter.remove":
+        special_fields = _DASHBOARD_FILTER_REMOVE_FIELDS
+    elif command_id == "dashboard.filter.list":
+        special_fields = ()
     local_fields = _LOCAL_CONTRACT_FIELDS.get(command_id, ()) if is_local else None
     fields = tuple(
         field