mammoth-cli 2.0.15__tar.gz → 2.0.17__tar.gz

{mammoth_cli-2.0.15 → mammoth_cli-2.0.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.15
+Version: 2.0.17
 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.7
+Requires-Dist: mammoth-io<0.8,>=0.7.9
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.13
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.0.15 → mammoth_cli-2.0.17}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -38,11 +38,18 @@ the result.
 
 ## Working rules
 
+- Every command takes its resource ids as positionals, its request fields as
+  one `--input` JSON document, plus the shared global options (`--project`,
+  `--profile`, `--output`, `--no-input`, `--yes`, `--confirm`, timeouts).
+  There are no per-field flags: `project create NAME`, not `project create
+  --name NAME`. `schema get COMMAND_ID` lists the positionals and input fields.
 - Resolve workspace/project/dataset/view parents from reads; pass observed IDs
   and `--project`. A dataset does not select a default view. Every `view`
   command that changes, exports, or deletes data requires the exact parent
-  `DATASET_ID` (trailing positional or `dataset_id` input field); only reads
-  may omit it and discover the parent. Get it from `mammoth view get VIEW_ID`.
+  `DATASET_ID`: `view transform *` and `view draft *` take it as the
+  `dataset_id` input field, every other `view` command as the trailing
+  positional after `VIEW_ID`; only reads may omit it and discover the parent.
+  Get it from `mammoth view get VIEW_ID`.
 - Uploads and dataset creation return a **dataset** id. Transforms, joins,
   exports, and previews need a **view** id: run `view list DATASET_ID
   --project PROJECT_ID` to get it. See
@@ -51,6 +58,13 @@ the result.
   never backend aliases.
 - Inspect the result after a mutation. A timeout, exit 7, or interruption does
   not prove it failed. Reconcile an `outcome_unknown` before replaying it.
+- A success envelope is not proof the mutation did what you meant. After a
+  row-scoped change (set-values, filter, replace, join, fill) read rows back
+  with `view data get VIEW_ID DATASET_ID` and check both rows the condition
+  should have touched and rows it should not have. A uniform result (every
+  amount 0, every region "Unknown", most join rows unmatched) is a signal
+  that the previous step went wrong, not a fact about the source data: stop
+  and re-inspect that step before building anything on it.
 - Keep secrets out of argv, task notes, checkpoints, logs, and responses.
 - Preserve requested deliverables. Cleanup is exact-ID authorized and never means delete-all-owned-resources.
 
@@ -64,7 +78,10 @@ the result.
   or [recovery](references/recovery.md)
 - **Import, resources, transforms, pipelines, dashboards, exports, or cleanup:**
   [recipes](references/recipes/index.md) and [operations](references/operations.md)
-- **A known command family or exact command:** [command catalog](references/command-index.md)
+- **A known command family or exact command:** [command catalog](references/command-index.md),
+  then check the same command in [capabilities](references/capabilities.md)
+  before composing input from its example (the catalog lists retired and
+  blocked routes with the same wording as working ones)
 - **Whether a route is proven, known-blocked, or untried on release:**
   [capabilities](references/capabilities.md) — read it before promising a
   deliverable or reporting a failure as a backend fault

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

@@ -0,0 +1,268 @@
+# What is proven on release
+
+Generated from `docs/release-capability-matrix.json`; do not edit by hand.
+455 API operations have a CLI command. 227 were exercised successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID --output json --no-input`, run it, and treat the structured error envelope as the answer.
+
+Status meanings:
+
+- **verified**: one bounded live run on release returned a success envelope (single path; variants and error paths are usually untested).
+- **not supported**: the backend refuses the route on release; the note says why and what to use instead.
+- **observed blocker**: the last run hit an error; the note quotes it. Re-check before relying on the route, and do not retry the same input.
+- **CLI defect fixed, untried since**: the failure was on the CLI side and this release repairs it; nobody has re-run the route yet.
+- Commands not listed under a family are untried.
+
+The typed `view transform *` commands all submit through `view.task.add`; its row below carries the transformations proven end to end (filter, fill-missing, join, pivot with an exported summary). A transformation not named there has the same untried status as any other command.
+
+## Coverage by family
+
+| Family | Commands | Verified | Not supported | Untried |
+|---|---|---|---|---|
+| `dashboard` | 104 | 81 | 2 | 21 |
+| `view` | 62 | 52 | 0 | 10 |
+| `support` | 45 | 9 | 0 | 36 |
+| `billing` | 23 | 4 | 0 | 19 |
+| `connector` | 22 | 2 | 0 | 20 |
+| `workspace` | 19 | 7 | 0 | 12 |
+| `project` | 17 | 15 | 0 | 2 |
+| `workflow` | 16 | 5 | 0 | 11 |
+| `dataset` | 15 | 12 | 0 | 3 |
+| `parameter` | 14 | 2 | 0 | 12 |
+| `data-app` | 12 | 1 | 0 | 11 |
+| `folder` | 8 | 8 | 0 | 0 |
+| `snippet` | 8 | 1 | 0 | 7 |
+| `automation` | 7 | 1 | 0 | 6 |
+| `user` | 7 | 3 | 0 | 4 |
+| `webhook` | 7 | 0 | 0 | 7 |
+| `addon` | 6 | 0 | 0 | 6 |
+| `batch` | 6 | 5 | 0 | 1 |
+| `file` | 6 | 5 | 0 | 1 |
+| `agent` | 5 | 1 | 0 | 4 |
+| `ai` | 5 | 2 | 0 | 3 |
+| `annotation` | 5 | 1 | 0 | 4 |
+| `client-app` | 5 | 0 | 0 | 5 |
+| `notification` | 5 | 1 | 0 | 4 |
+| `schedule` | 5 | 0 | 0 | 5 |
+| `template` | 5 | 0 | 0 | 5 |
+| `browse` | 4 | 2 | 0 | 2 |
+| `external-key` | 4 | 0 | 0 | 4 |
+| `trash` | 3 | 3 | 0 | 0 |
+| `activity` | 2 | 1 | 0 | 1 |
+| `job` | 2 | 2 | 0 | 0 |
+| `report` | 1 | 1 | 0 | 0 |
+
+## `activity`
+
+Verified: `activity.list`
+
+| Command | State | Note |
+|---|---|---|
+| `activity.export` | observed blocker | server_error: see sweep report |
+
+## `agent`
+
+Verified: `agent.session.list`
+
+## `ai`
+
+Verified: `ai.condition.generate`, `ai.expression.generate`
+
+| Command | State | Note |
+|---|---|---|
+| `ai.retention.condition` | observed blocker | permission: POST /workspaces/4/projects/24/sql_generation/retention_policy -> HTTP 403 4PERM001 PERMISSION_UNDEFINED, error_object {code:76,message:'Permissions have not been set c |
+| `ai.sql.generate` | observed blocker | backend_error: Fix held (dataset_id required and sent as query param -- request reached backend and got a domain-specific conflict, not an empty api_error) |
+| `ai.suggestion.list` | observed blocker | backend_error: Fix held: release UnifiedPromptSpec (suggestion_type + params, optional dataset_id/dataview_id) shape accepted and dispatched to a real job (id 381), which failed fo |
+
+## `annotation`
+
+Verified: `annotation.list`
+
+## `automation`
+
+Verified: `automation.list`
+
+## `batch`
+
+Verified: `batch.bulk-delete`, `batch.delete`, `batch.get`, `batch.list`, `batch.update`
+
+| Command | State | Note |
+|---|---|---|
+| `batch.create` | CLI defect fixed, untried since | 2.0.16 (mapping items carry expected_destination_c_type (TEXT/NUMERIC/DATE) |
+
+## `billing`
+
+Verified: `billing.stripe.history`, `billing.stripe.payment-method.list`, `billing.stripe.status`, `billing.subscription.get`
+
+| Command | State | Note |
+|---|---|---|
+| `billing.chargebee-plan` | observed blocker | backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 400 4SUBS014 'Chargebee plan not found for the given workspace' (workspace 4 is n |
+| `billing.invoice.get` | observed blocker | blocked_missing_fixture: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: billing invoice list answered HTTP 500, so no invoice id was observed |
+| `billing.invoice.list` | observed blocker | backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 500 with empty body on GET /workspaces/4/subscription_v1/invoices |
+| `billing.stripe.preview-invoice` | observed blocker | backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 400 4SUBS037 'Failed to perform subscription operation' |
+| `billing.stripe.upcoming-invoice` | observed blocker | backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 400 4SUBS074 'Upcoming invoice not found' (no active Stripe subscription on works |
+| `billing.stripe.usage` | observed blocker | backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 400 5GENR010 UNKNOWN_ERROR 'Unknown error occurred |
+
+## `browse`
+
+Verified: `browse.project`, `browse.workspace`
+
+| Command | State | Note |
+|---|---|---|
+| `browse.folder` | observed blocker | cli_error: rejects folder id 0 although folder.root reports id 0 as the root |
+| `browse.root` | observed blocker | server_error: see sweep report |
+
+## `client-app`
+
+| Command | State | Note |
+|---|---|---|
+| `client-app.list` | observed blocker | forbidden: backend_code=4GENR012 INVALID_TOKEN_FOR_CLIENT_APPS: 'Cannot access this API with API-tokens' on GET /workspaces/4/clientapps |
+
+## `connector`
+
+Verified: `connector.active`, `connector.list`
+
+| Command | State | Note |
+|---|---|---|
+| `connector.ai.session.list` | observed blocker | cli_error: backend returned HTTP 200 but the CLI raised api_error (envelope mismatch) |
+| `connector.connection.list` | observed blocker | server_error: see sweep report |
+| `connector.get` | observed blocker | validation_error: HTTP 400 'Invalid connector key' for a key returned by connector.list |
+| `connector.query.generate` | observed blocker | blocked_missing_fixture: No real connector connection exists in workspace 4 (connector.list shows all is_added:false; connector.active returns []), matching the documented capabili |
+| `connector.query.status` | observed blocker | blocked_missing_fixture: No real connector connection exists in workspace 4 (connector list shows all is_added:false; connector active returns []) and creating one requires externa |
+
+## `dashboard`
+
+Verified: `dashboard.action`, `dashboard.analytics`, `dashboard.archive`, `dashboard.cancel-generation`, `dashboard.canvas.get`, `dashboard.canvas.restore`, `dashboard.canvas.save`, `dashboard.chat.edit`, `dashboard.chat.history`, `dashboard.context.create`, `dashboard.context.delete`, `dashboard.context.extract`, `dashboard.context.list`, `dashboard.context.update`, `dashboard.create-blank`, `dashboard.delete`, `dashboard.descriptor-data`, `dashboard.duplicate`, `dashboard.exemplar.extract`, `dashboard.figure-intent`, `dashboard.get`, `dashboard.get-by-url`, `dashboard.job-by-url`, `dashboard.list`, `dashboard.og-card`, `dashboard.page.plan`, `dashboard.pages.add`, `dashboard.published.canvas`, `dashboard.published.share-page`, `dashboard.qa.ask`, `dashboard.qa.comment.create`, `dashboard.qa.comment.delete`, `dashboard.qa.feedback`, `dashboard.qa.session.create`, `dashboard.qa.session.delete`, `dashboard.qa.session.fork`, `dashboard.qa.session.get`, `dashboard.qa.session.list`, `dashboard.qa.session.rename`, `dashboard.qa.session.set-visibility`, `dashboard.qa.settings.get`, `dashboard.qa.settings.set`, `dashboard.query`, `dashboard.restore`, `dashboard.rls.assignment.list`, `dashboard.rls.assignment.set`, `dashboard.rls.column.list`, `dashboard.rls.value.list`, `dashboard.share`, `dashboard.signature.create`, `dashboard.signature.delete`, `dashboard.signature.list`, `dashboard.signature.update`, `dashboard.style.custom.create`, `dashboard.style.custom.delete`, `dashboard.style.custom.list`, `dashboard.style.custom.update`, `dashboard.style.default.get`, `dashboard.style.default.set`, `dashboard.style.derive`, `dashboard.style.extract-brand`, `dashboard.style.preset.list`, `dashboard.style.token.list`, `dashboard.suggestion.list`, `dashboard.swap-data`, `dashboard.tags.delete`, `dashboard.tags.list`, `dashboard.tags.merge`, `dashboard.tags.rename`, `dashboard.tags.set`, `dashboard.template.apply`, `dashboard.template.fit`, `dashboard.template.get`, `dashboard.template.list`, `dashboard.template.preview`, `dashboard.template.resolve-mapping`, `dashboard.templates.pending`, `dashboard.trash`, `dashboard.update`, `dashboard.v3.generate`, `dashboard.video-state`
+
+| Command | State | Note |
+|---|---|---|
+| `dashboard.create` | not supported | Not supported on release: backend returns HTTP 409 4DASH012 DASHBOARD_LEGACY_CREATION_RETIRED (legacy dashboard creation retired). Use dashboard.create-blank or dashboard.v3.generate. Dashboard sweep 2026-09-18, CLI 2.0.12. |
+| `dashboard.pdf.export` | not supported | Not supported from the CLI on release: backend HTTP 400 4GENR001 requires params.data to be the browser-hydrated DashboardData map and states it cannot rebuild it from stored descriptors (dashboard sweep and Haiku e2e, 2026-09-18). The route works only with a client render pass. |
+| `dashboard.data.draft` | observed blocker | blocked_missing_fixture: Dashboard 56 (create-blank/v3 engine) has no widgets in its canvas and getDraftData rejects with backend_code 4DASH004 DASHBOARD_WRONG_ENGINE: "This dashbo |
+| `dashboard.data.published` | observed blocker | blocked_missing_fixture: Same as dashboard.data.draft: backend_code 4DASH004 DASHBOARD_WRONG_ENGINE on /dashboards/56/getPublishData |
+| `dashboard.published-data-by-url` | observed blocker | blocked_missing_fixture: backend_code 4DASH004 DASHBOARD_WRONG_ENGINE on /dashboards/url/IuZl5tk5KcEHJWTy4tnhrA/getPublishData, same class of blocker as widget-data: this v3 dashbo |
+| `dashboard.published.data` | observed blocker | blocked_missing_fixture: Could not publish dashboard 59 to reach a live published state: `dashboard action 59 {action:publish-presentation}` failed twice with HTTP 500 outcome_unkn |
+| `dashboard.published.pdf-artifact` | observed blocker | blocked_missing_fixture: Same as dashboard.pdf-artifact: no real pdf job available; used job 313 (descriptor-data job) as the only real job id in hand and got backend_code 4DASH001 |
+| `dashboard.published.pdf.export` | observed blocker | backend_error: Got backend_code 4PERM002 PERMISSION_ERROR, "User lacks permission to perform given action" on POST /dashboards/url/IuZl5tk5KcEHJWTy4tnhrA/pdf (403), envelope: {"err |
+| `dashboard.published.video.export` | observed blocker | backend_error: backend_code 4PERM002 PERMISSION_ERROR, "User lacks permission to perform given action" on POST /dashboards/url/IuZl5tk5KcEHJWTy4tnhrA/video (403) |
+| `dashboard.source.list` | observed blocker | blocker; still broken, not one of the 11 CLI-fixed commands |
+| `dashboard.template.create` | observed blocker | backend: POST /dashboards/v3/templates -> HTTP 500, empty response_body, request_id:null, code:outcome_unknown |
+| `dashboard.template.delete` | observed blocker | blocked_missing_fixture: dashboard.template.create never produced an owned template (HTTP 500 both attempts, reconciled as not-committed via template list) |
+| `dashboard.templates.use` | observed blocker | skipped_out_of_scope: BRIEF instructs running templates.use "on that template" (i.e |
+| `dashboard.video.export` | observed blocker | backend_error: After publishing dashboard 56 (dashboard.share public + dashboard.action publish-presentation), the previously-documented "publish the dashboard before exporting a v |
+| `dashboard.widget-data` | observed blocker | blocked_missing_fixture: backend_code 4DASH004 DASHBOARD_WRONG_ENGINE, "This dashboard uses a different rendering engine -- use the matching endpoints", on POST /dashboards/56/widg |
+| `dashboard.widget-data-by-url` | observed blocker | blocked_missing_fixture: Same backend_code 4DASH004 DASHBOARD_WRONG_ENGINE, on POST /dashboards/url/IuZl5tk5KcEHJWTy4tnhrA/widgets/data |
+
+## `data-app`
+
+Verified: `data-app.list`
+
+## `dataset`
+
+Verified: `dataset.batch-data`, `dataset.bulk-delete`, `dataset.create`, `dataset.data`, `dataset.delete`, `dataset.file-settings.get`, `dataset.file-settings.undo`, `dataset.file-settings.update`, `dataset.get`, `dataset.list`, `dataset.restore`, `dataset.trash`
+
+| Command | State | Note |
+|---|---|---|
+| `dataset.bulk-update` | observed blocker | cli_error: Schema preconditions already flag this as BLOCKED[B07 DATASET_PATCH_UNTYPED]; reserved, not registered -- confirmed live |
+| `dataset.create-from-pdf` | observed blocker | backend: POST /workspaces/4/projects/24/datasets-from-pdf |
+
+## `external-key`
+
+| Command | State | Note |
+|---|---|---|
+| `external-key.list` | observed blocker | cli_error: not_authenticated although the same session authenticated elsewhere |
+
+## `file`
+
+Verified: `file.bulk-delete`, `file.delete`, `file.get`, `file.list`, `file.upload`
+
+| Command | State | Note |
+|---|---|---|
+| `file.update` | observed blocker | backend_error: CLI accepted the typed patch and submitted job 314 (handle_file on /workspaces/4/projects/21/files/50), then correctly reported timeout after 60s with recovery_comma |
+
+## `folder`
+
+Verified: `folder.bulk-delete`, `folder.create`, `folder.delete`, `folder.get`, `folder.list`, `folder.move`, `folder.trash`, `folder.update`
+
+## `job`
+
+Verified: `job.get`, `job.get-many`
+
+## `notification`
+
+Verified: `notification.list`
+
+## `parameter`
+
+Verified: `parameter.group.list`, `parameter.list`
+
+## `project`
+
+Verified: `project.bulk-delete`, `project.bulk-update`, `project.checkpoint.list`, `project.create`, `project.data-check.list`, `project.delete`, `project.list`, `project.pending-changes`, `project.publish-credentials`, `project.resource-dependencies`, `project.resource-dependencies.update`, `project.resource-status`, `project.sample-flow`, `project.update`, `project.user.add`
+
+| Command | State | Note |
+|---|---|---|
+| `project.user.update` | observed blocker | backend_error: HTTP 400 4PROJ010 ROLE_ALREADY_ASSIGNED: "Role already assigned to the user" -- targeted our own user (id 5, already project_admin as project owner) |
+
+## `report`
+
+Verified: `report.list`
+
+## `schedule`
+
+| Command | State | Note |
+|---|---|---|
+| `schedule.get` | observed blocker | blocked_missing_fixture: Not run: id source schedule.list failed with backend_error (5GENR011 NOT_IMPLEMENTED, HTTP 400), so no schedule_id was observed to use |
+| `schedule.list` | observed blocker | backend_error: backend_code=5GENR011 NOT_IMPLEMENTED: 'Not implemented' on GET /workspaces/4/projects/3/schedules |
+
+## `snippet`
+
+Verified: `snippet.list`
+
+## `support`
+
+Verified: `support.connector-profile.list`, `support.connector.list`, `support.feature-profile.list`, `support.feature.list`, `support.plan.chargebee-list`, `support.plan.list`, `support.plan.self-serve-list`, `support.user.list-all`, `support.workspace.list`
+
+## `template`
+
+| Command | State | Note |
+|---|---|---|
+| `template.list` | observed blocker | cli_error: backend returned HTTP 200 but the CLI raised api_error (envelope mismatch) |
+
+## `trash`
+
+Verified: `trash.add`, `trash.list`, `trash.restore`
+
+## `user`
+
+Verified: `user.get`, `user.preference.get`, `user.preference.update`
+
+## `view`
+
+Verified: `view.active-user.list`, `view.active-user.mark`, `view.ai.generate-data`, `view.ai.profile`, `view.bulk-delete`, `view.checkpoint.create`, `view.checkpoint.delete`, `view.checkpoint.list`, `view.conditional-format.create`, `view.conditional-format.delete-all`, `view.conditional-format.list`, `view.conditional-format.update`, `view.create`, `view.data-check.create`, `view.data-check.delete`, `view.data-check.get`, `view.data-check.list`, `view.data.get`, `view.data.query`, `view.delete`, `view.derivative.create`, `view.derivative.delete`, `view.derivative.list`, `view.derivative.update`, `view.draft.command`, `view.export.delete`, `view.export.get`, `view.export.list`, `view.export.publish-db`, `view.export.update`, `view.exportable-config.get`, `view.get`, `view.list`, `view.parameter-context`, `view.pipeline.edit`, `view.pipeline.get`, `view.pipeline.items`, `view.pipeline.rerun`, `view.preview`, `view.restore`, `view.task.add`, `view.task.delete`, `view.task.get`, `view.task.list`, `view.task.update`, `view.trash`, `view.version.apply`, `view.version.delete`, `view.version.get`, `view.version.list`, `view.version.update`
+
+| Command | State | Note |
+|---|---|---|
+| `view.ai.generation-info` | observed blocker | backend: GET /workspaces/4/projects/24/datasets/54/dataviews/76/data/generate -> HTTP 400 5GENR011 NOT_IMPLEMENTED 'Not implemented', request_id:null |
+| `view.checkpoint.get` | observed blocker | backend: GET /workspaces/4/projects/24/datasets/54/dataviews/76/pipeline/checkpoints/2 -> HTTP 500, empty response_body:{}, request_id:null, backend code: none surfaced (generic ap |
+| `view.checkpoint.update` | observed blocker | backend_error: CLI-side fix (payload now carries value:null as required) held: the correctly-shaped request was dispatched and the backend returned HTTP 500 (not a CLI-side crash): |
+| `view.data-check.update` | observed blocker | backend: PATCH .../pipeline/data-checks/3 -> HTTP 500, empty response_body, request_id:null, code:outcome_unknown |
+| `view.derivative.data` | observed blocker | backend: POST .../derivatives/4/data -> HTTP 500, empty response_body, request_id:null, code:outcome_unknown |
+| `view.export.create` | observed blocker | backend: CLI accepts the request (exit 0, job 358 accepted on POST /dataviews/76/actions), but job get 358 -> status:error, response:{"error":{"message":"'destination'"}} (a raw Py |
+| `view.exportable-config.apply` | observed blocker | cli_error: Schema's own runnable_example (config:{tasks:[]}) fails: job_failed, response:{reason:(quote)dependencies(quote)} -- a raw Python KeyError, not a structured validation m |
+| `view.task.preview` | observed blocker | backend_error: Fix held: the COPY task_spec is accepted and a task_preview job (406) is created; the job then fails backend-side with 'Object of type datetime is not JSON serializa |
+| `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)) |
+
+## `webhook`
+
+| Command | State | Note |
+|---|---|---|
+| `webhook.list` | observed blocker | cli_error: api_error with no HTTP status recorded |
+
+## `workflow`
+
+Verified: `workflow.graph`, `workflow.list`, `workflow.workspace-datasets`, `workflow.workspace-exports`, `workflow.workspace-sources`
+
+## `workspace`
+
+Verified: `workspace.app-usage`, `workspace.get`, `workspace.list`, `workspace.segment.list`, `workspace.segment.update`, `workspace.storage-breakdown`, `workspace.user.list`
+
+Evidence collected on CLI releases 1.1.5 through 2.0.17; each row's release is recorded in `docs/release-capability-matrix.json` (`evidence_version`). A row verified 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.15 → mammoth_cli-2.0.17}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/batch.md

@@ -12,7 +12,7 @@ Expected success: `BatchBulkDeleteResult` in the standard JSON envelope; mutatio
 
 Run: `mammoth batch create`. Exact input fields: `mammoth schema get batch.create --output json --no-input`.
 
-Example: `mammoth batch create 123 123 --input '{"mapping": {"sample_key": "Status"}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth batch create 123 123 --input '{"mapping": [{"source_c_name": "column_1", "destination_c_name": "column_1", "expected_destination_c_type": "TEXT"}]}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `BatchCreateResult` in the standard JSON envelope; mutation `benign_mutation`, confirmation `none`, wait policy `returns_job`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 

{mammoth_cli-2.0.15 → mammoth_cli-2.0.17}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -92,7 +92,7 @@ Expected success: `ViewCheckpointUpdateResult` in the standard JSON envelope; mu
 
 Run: `mammoth view conditional-format create`. Exact input fields: `mammoth schema get view.conditional-format.create --output json --no-input`.
 
-Example: `mammoth view conditional-format create 123 123 --input '{"rule": {"sample_key": "Status"}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth view conditional-format create 123 123 --input '{"rule": {"cf_type": "RULE", "payload": {"FORMAT": {"name": "Flag open orders", "color": "red", "applies_to": "row", "column_ids": "[]"}, "CONDITION": {"OR": [{"column_1": {"CONTAINS": {"VALUE": ["Open"]}}}]}}}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `ViewConditionalFormatCreateResult` in the standard JSON envelope; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -100,7 +100,7 @@ Expected success: `ViewConditionalFormatCreateResult` in the standard JSON envel
 
 Run: `mammoth view conditional-format delete-all`. Exact input fields: `mammoth schema get view.conditional-format.delete-all --output json --no-input`.
 
-Example: `mammoth view conditional-format delete-all 123 123 --input '{"rule_id": "rule-1"}' --output json --no-input`. Illustrative only: append `--yes` after observing an owned target.
+Example: `mammoth view conditional-format delete-all 123 123 --input '{"rule_id": "bca0ff33bd6f8ed1"}' --output json --no-input`. Illustrative only: append `--yes` after observing an owned target.
 
 Expected success: `ViewConditionalFormatDeleteAllResult` in the standard JSON envelope; mutation `destructive`, confirmation `prompt_or_yes`, wait policy `not_async`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -446,7 +446,7 @@ Expected success: `ViewExportPublishDbResult` in the standard JSON envelope; mut
 
 Run: `mammoth view export publish-db-update`. Exact input fields: `mammoth schema get view.export.publish-db-update --output json --no-input`.
 
-Example: `mammoth view export publish-db-update 123 --input '{"patch": [{"op": "replace", "path": "credentials", "value": "postgres"}]}' --output json --no-input`. Illustrative only: append `--yes` after observing an owned target.
+Example: `mammoth view export publish-db-update 123 --input '{"patch": [{"op": "replace", "path": "credentials", "value": {"odbc_type": "postgres"}}]}' --output json --no-input`. Illustrative only: append `--yes` after observing an owned target.
 
 Expected success: `ViewExportPublishDbUpdateResult` in the standard JSON envelope; mutation `external_effect`, confirmation `yes_always`, wait policy `not_async`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -612,7 +612,7 @@ Expected success: `ViewRestoreResult` in the standard JSON envelope; mutation `b
 
 Run: `mammoth view task add`. Exact input fields: `mammoth schema get view.task.add --output json --no-input`.
 
-Example: `mammoth view task add 123 --input '{"task_spec": {"DATAVIEW_ID": 123, "SEQUENCE_NUMBER": 1, "COPY": {}}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth view task add 123 --input '{"task_spec": {"DATAVIEW_ID": 123, "SEQUENCE_NUMBER": 1, "COPY": [{"SOURCE": "column_1", "AS": {"COLUMN": "Copy of column 1", "TYPE": "TEXT", "INTERNAL_NAME": "column_9"}}], "VERSION": 2}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `ViewTaskAddResult` in the standard JSON envelope; mutation `reversible_pipeline`, confirmation `none`, wait policy `always_wait`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -644,7 +644,7 @@ Expected success: `ViewTaskListResult` in the standard JSON envelope; mutation `
 
 Run: `mammoth view task preview`. Exact input fields: `mammoth schema get view.task.preview --output json --no-input`.
 
-Example: `mammoth view task preview 123 --input '{"task_spec": {"DATAVIEW_ID": 123, "SEQUENCE_NUMBER": 1, "COPY": {}}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth view task preview 123 --input '{"task_spec": {"DATAVIEW_ID": 123, "SEQUENCE_NUMBER": 1, "COPY": [{"SOURCE": "column_1", "AS": {"COLUMN": "Copy of column 1", "TYPE": "TEXT", "INTERNAL_NAME": "column_9"}}], "VERSION": 2}}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `ViewTaskPreviewResult` in the standard JSON envelope; mutation `read`, confirmation `none`, wait policy `always_wait`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -652,7 +652,7 @@ Expected success: `ViewTaskPreviewResult` in the standard JSON envelope; mutatio
 
 Run: `mammoth view task update`. Exact input fields: `mammoth schema get view.task.update --output json --no-input`.
 
-Example: `mammoth view task update 123 123 --input '{"task_spec": {"DATAVIEW_ID": 123, "SEQUENCE_NUMBER": 1, "COPY": {}}, "dataset_id": 456}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth view task update 123 123 --input '{"task_spec": {"DATAVIEW_ID": 123, "SEQUENCE_NUMBER": 1, "COPY": [{"SOURCE": "column_1", "AS": {"COLUMN": "Copy of column 1", "TYPE": "TEXT", "INTERNAL_NAME": "column_9"}}], "VERSION": 2}, "dataset_id": 456}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `ViewTaskUpdateResult` in the standard JSON envelope; mutation `reversible_pipeline`, confirmation `none`, wait policy `always_wait`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 
@@ -668,7 +668,7 @@ Expected success: `ViewTransformAddColumnResult` in the standard JSON envelope;
 
 Run: `mammoth view transform add-sql`. Exact input fields: `mammoth schema get view.transform.add-sql --output json --no-input`.
 
-Example: `mammoth view transform add-sql 123 --input '{"query": "SELECT region, SUM(revenue) FROM data GROUP BY region", "dataset_id": 456}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
+Example: `mammoth view transform add-sql 123 --input '{"query": "SELECT region, SUM(revenue) AS revenue FROM \"view:123\" GROUP BY region", "dataset_id": 456}' --output json --no-input`. Runnable only after resolving schema-required IDs and input from observed reads.
 
 Expected success: `ViewTransformAddSqlResult` in the standard JSON envelope; mutation `reversible_pipeline`, confirmation `none`, wait policy `always_wait`. On nonzero exit, inspect the JSON error envelope and its `recovery_commands`; do not guess request fields. See [representative envelopes](../machine-output.md) for concrete success/error shapes.
 

{mammoth_cli-2.0.15 → mammoth_cli-2.0.17}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/resources.md

@@ -6,9 +6,11 @@ id instead. Run `view list DATASET_ID --project PROJECT_ID` to get it. Do not
 dig through `dataset get` and its `dependencies` field for a view id; `view
 list` is the supported route.
 
-Discover exact contracts, then upload and read back explicit parents:
+Discover exact contracts, then upload and read back explicit parents. A new
+project takes its name as the positional argument:
 
 ```bash
+mammoth project create 'PROJECT NAME' --output json --no-input
 mammoth schema get file.upload --output json --no-input
 mammoth file upload ./SOURCE.csv --project PROJECT_ID --output json --no-input
 mammoth dataset list --project PROJECT_ID --output json --no-input
@@ -17,7 +19,9 @@ mammoth view get VIEW_ID --project PROJECT_ID --output json --no-input
 ```
 
 `file upload` takes the local path as its positional argument; there is no
-`--source`/`--file` option. `dataset delete` is asynchronous: re-read
+`--source`/`--file` option. Its result carries the status the platform holds
+for each created dataset: `ready`, or `need_action` with a `next_command`, in
+which case follow [need-action](need-action.md) before looking for a view. `dataset delete` is asynchronous: re-read
 `dataset list` (the id disappears once the job completes) before reporting.
 
 Use display names from the exact view schema. For settings, folders and other

{mammoth_cli-2.0.15 → mammoth_cli-2.0.17}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/transforms.md

@@ -30,8 +30,14 @@ lists them. Pick the operation by what it does, not by its name:
 mammoth view transform set-values VIEW_ID --project PROJECT_ID \
   --input '{"dataset_id":DATASET_ID,"existing_column":"revenue","values":[{"value":0}],"condition":{"column":"revenue","operator":"IS_EMPTY"}}' \
   --output json --no-input
+mammoth view data get VIEW_ID DATASET_ID --project PROJECT_ID --output json --no-input
 ```
 
+Then confirm from the read-back that blank rows are now `0` and non-blank
+rows kept their values. If non-matching rows changed too, the condition was
+not applied: stop, do not build joins or summaries on this view, and report
+it.
+
 - `filter` keeps matching rows by default (`filter_type: "SHOW"`); to drop
   rows, say so: `{"condition":{"column":"units","operator":"LT","value":0},"filter_type":"REMOVE"}`. For each operation, a successful result should contain a returned
 task/job reference or updated view envelope; then verify with `view task list`,
@@ -64,6 +70,44 @@ mammoth schema get view.transform.join --output json --no-input
 mammoth view transform join VIEW_ID --project PROJECT_ID --input INPUT_JSON --output json --no-input
 ```
 
+## Aggregate or summarise
+
+For a grouped summary (totals per region, counts per status) use the typed
+`pivot` when the live schema lists it, or a SQL task. A SQL task must be one
+SELECT that names the view as the quoted table `"view:VIEW_ID"` (or its quoted
+display name) with display-name columns; unquoted or placeholder table names
+(`data`, `__TABLE__`) are rejected with "table name ... not found" or "only
+select queries allowed". The result replaces the view's columns, so run it on
+a copy (`view create` with `clone_from`) or as the last step:
+
+```bash
+mammoth schema get view.transform.pivot --output json --no-input
+mammoth view transform add-sql VIEW_ID --project PROJECT_ID \
+  --input '{"dataset_id":DATASET_ID,"query":"SELECT region, SUM(amount) AS total_amount, COUNT(*) AS order_count FROM \"view:VIEW_ID\" GROUP BY region"}' \
+  --output json --no-input
+mammoth view data get VIEW_ID DATASET_ID --project PROJECT_ID --output json --no-input
+```
+
+Read the data back after every value-changing step (`view data get`, or
+`view preview`); a task that executed is not proof it changed the rows you
+meant, and a join that matched nothing shows nulls, not a filled default. A
+join that leaves most rows unmatched is not evidence about the source data
+until you have sampled the key column on both sides (`view data get` on
+each view) and confirmed an earlier step did not rewrite the key or the
+values you are summing.
+
+## How to look at your data
+
+- Schema and types: `view get VIEW_ID` (falls back to discovery) or
+  `dataset get DATASET_ID`; the column list with display names is what every
+  transform input must use.
+- Rows and values: `view data get VIEW_ID DATASET_ID` (paged) or
+  `view preview VIEW_ID` for a sample; use these after every value-changing
+  step and before reporting any number.
+- What actually ran: `view task list VIEW_ID`, `view task get VIEW_ID TASK_ID`,
+  `view pipeline get VIEW_ID` (state, auto_run, executing task).
+- Async completion: `job get JOB_ID` / `job wait JOB_ID`.
+
 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:
@@ -81,8 +125,12 @@ free-form lists. Observed shapes:
   `reorder`, `null` for commands). Prefer `view draft *` for submit/discard.
 - `view task update VIEW_ID TASK_ID --input '{"dataset_id":DATASET_ID,"task_spec":{...}}'`
   sends `{"patches":[{"op":"replace","path":"params","value":task_spec}]}`;
-  pass `patches` directly for other paths. `view task preview` needs the
-  task's internal column names (`view columns`), not display names.
+  pass `patches` directly for other paths. Raw `task_spec` bodies use the
+  backend param-template shape with internal column names, e.g. COPY is
+  `{"COPY":[{"SOURCE":"column_1","AS":{"COLUMN":"Copy","TYPE":"TEXT","INTERNAL_NAME":"column_9"}}],"VERSION":2,...}`;
+  prefer the typed `view transform *` commands, which build these for you.
+  `view task preview` currently fails on the backend for views with a DATE
+  column (`datetime is not JSON serializable`), so do not rely on it.
 - `view checkpoint update` sends `{"patches":[{"op":"command","path":"approve","value":null}]}`;
   the release backend answered HTTP 500 to that shape, so treat checkpoint
   approval as unavailable until `checkpoint get` succeeds again.

{mammoth_cli-2.0.15 → mammoth_cli-2.0.17}/mammoth_cli/commands/file.py

@@ -11,6 +11,7 @@ SDK method named by the command's reviewed manifest ``sdk_symbol``.
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from typing import Any
 
 from mammoth_cli.errors.envelope import (
@@ -214,25 +215,64 @@ def file_upload(invocation: Invocation) -> HandlerResult:
     )
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
-    # The SDK waits for the upload to finish and returns the created dataset
-    # id(s) as a bare int/list. Wrap it in a labeled result so the output reads
-    # as a finished dataset rather than an anonymous number. When the caller
-    # opts out of waiting (``wait_for_completion: false``) the bare job id is
-    # returned unchanged.
-    if not document.get("wait_for_completion", True):
-        return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
-    return _upload_result(data), _meta(invocation, auth.workspace_id, resolved_project(invocation))
-
-
-def _upload_result(value: Any) -> dict[str, Any]:
-    """Shape the SDK upload return (int | list[int] | None) into a labeled result."""
+        # The SDK waits for the upload job and returns the created dataset
+        # id(s) as a bare int/list. When the caller opts out of waiting
+        # (``wait_for_completion: false``) the bare job id is returned unchanged.
+        if not document.get("wait_for_completion", True):
+            return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+        # A finished upload job does not mean a usable dataset: a CSV with an
+        # ambiguous date column lands in ``need_action`` with no view. Report
+        # the status the platform holds for each dataset, not an assumed one.
+        result = _upload_result(data, lambda dataset_id: _dataset_status(service, dataset_id))
+    return result, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+_DATASET_GET_SYMBOL = "mammoth.api.datasets.DatasetsAPI.get"
+
+
+def _dataset_status(service: Any, dataset_id: int) -> tuple[str, dict[str, Any] | None]:
+    """Read ``(status, status_info)`` for one dataset; ``unknown`` if the read fails."""
+    try:
+        response = service.call(_DATASET_GET_SYMBOL, dataset_id=dataset_id)
+    except CliError:
+        return "unknown", None
+    dataset = response.get("dataset", response) if isinstance(response, dict) else {}
+    status = dataset.get("status") if isinstance(dataset, dict) else None
+    status_info = dataset.get("status_info") if isinstance(dataset, dict) else None
+    return (
+        status if isinstance(status, str) else "unknown",
+        status_info if isinstance(status_info, dict) else None,
+    )
+
+
+def _upload_result(
+    value: Any, read_status: Callable[[int], tuple[str, dict[str, Any] | None]]
+) -> dict[str, Any]:
+    """Shape the SDK upload return (int | list[int] | None) into a labeled result.
+
+    ``status`` is ``ready`` only when every created dataset reads back as
+    ``ready``; otherwise it is the first non-ready status so a caller that
+    checks one field sees the dataset that still needs work. ``datasets``
+    carries the per-dataset status, and a ``need_action`` dataset also gets
+    the recovery route so the caller does not have to know the recipe.
+    """
     if isinstance(value, list):
         ids = [int(v) for v in value]
     elif isinstance(value, int):
         ids = [value]
     else:
         ids = []
-    result: dict[str, Any] = {"status": "ready", "dataset_ids": ids}
+    datasets: list[dict[str, Any]] = []
+    for dataset_id in ids:
+        status, status_info = read_status(dataset_id)
+        entry: dict[str, Any] = {"id": dataset_id, "status": status}
+        if status_info:
+            entry["status_info"] = status_info
+        if status == "need_action":
+            entry["next_command"] = f"mammoth dataset file-settings get {dataset_id}"
+        datasets.append(entry)
+    overall = next((d["status"] for d in datasets if d["status"] != "ready"), "ready")
+    result: dict[str, Any] = {"status": overall, "dataset_ids": ids, "datasets": datasets}
     if len(ids) == 1:
         result["dataset_id"] = ids[0]
     return result