mammoth-cli 2.0.36__tar.gz → 2.0.37__tar.gz

{mammoth_cli-2.0.36 → mammoth_cli-2.0.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.36
+Version: 2.0.37
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -203,8 +203,9 @@ one-time login, and works from the shipped skill. The long form is
 [docs/agent-prompt.md](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agent-prompt.md).
 
 ```text
-Use Mammoth Analytics only through the `mammoth` CLI in bash; run
-`export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once. Onboard me first:
+Use Mammoth Analytics only through the `mammoth` CLI in bash, never the web
+app in a browser; run `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once.
+Onboard me first:
 1. If `mammoth --version` fails, install, then re-check (new shell if needed):
    curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | bash
 2. Run `mammoth auth status`. If it shows no credentials or a
@@ -217,8 +218,9 @@ Use Mammoth Analytics only through the `mammoth` CLI in bash; run
 3. Require `mammoth doctor` to pass, then run `mammoth skill show` and
    follow the guide it prints.
 Work inside `mammoth project ensure 'PROJECT NAME'` unless I name a project;
-take ids only from reads; `schema get COMMAND_ID` before a new command; read
-results back before reporting.
+take ids only from reads; find a command with `schema find "GOAL IN PLAIN
+WORDS"` or `view transform --help`, and `schema get COMMAND_ID` before a new
+command; read results back before reporting.
 TASK: <what to achieve, and how you will know it is done>
 ```
 

{mammoth_cli-2.0.36 → mammoth_cli-2.0.37}/README.md

@@ -175,8 +175,9 @@ one-time login, and works from the shipped skill. The long form is
 [docs/agent-prompt.md](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/agent-prompt.md).
 
 ```text
-Use Mammoth Analytics only through the `mammoth` CLI in bash; run
-`export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once. Onboard me first:
+Use Mammoth Analytics only through the `mammoth` CLI in bash, never the web
+app in a browser; run `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once.
+Onboard me first:
 1. If `mammoth --version` fails, install, then re-check (new shell if needed):
    curl -fsSL https://raw.githubusercontent.com/EdgeMetric/mammothsdk/main/mammoth-cli/installers/mammoth-install.sh | bash
 2. Run `mammoth auth status`. If it shows no credentials or a
@@ -189,8 +190,9 @@ Use Mammoth Analytics only through the `mammoth` CLI in bash; run
 3. Require `mammoth doctor` to pass, then run `mammoth skill show` and
    follow the guide it prints.
 Work inside `mammoth project ensure 'PROJECT NAME'` unless I name a project;
-take ids only from reads; `schema get COMMAND_ID` before a new command; read
-results back before reporting.
+take ids only from reads; find a command with `schema find "GOAL IN PLAIN
+WORDS"` or `view transform --help`, and `schema get COMMAND_ID` before a new
+command; read results back before reporting.
 TASK: <what to achieve, and how you will know it is done>
 ```
 

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

{mammoth_cli-2.0.36 → mammoth_cli-2.0.37}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mammoth-cli
-version: 2.0.36
-description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines, dashboards, exports, and handoffs."
+version: 2.0.37
+description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines (join, merge, pivot, filter, clean), dashboards, exports, and handoffs."
 ---
 
 # Mammoth CLI
@@ -10,6 +10,19 @@ Use this skill for Mammoth shell work, not for Python SDK integration. The
 CLI is the contract: it validates every request locally, returns one JSON
 envelope, and needs no flag for that when you pipe its output.
 
+## What Mammoth is
+
+Mammoth Analytics is a no-code data platform. Data comes in from files, URLs
+or connectors and lands in a **dataset**. It is cleaned, joined, reshaped and
+calculated in a **pipeline** of tasks on a **view**, and the result is
+published as a dashboard or delivered as a CSV, a database table, a BI feed
+or another dataset. The pipeline re-runs when new data arrives, so build the
+steps in Mammoth rather than computing a result locally. The web app and
+this CLI call the same API: every task in the web app's Transform menu is a
+`mammoth view transform` command. The data model, the high-level
+capabilities and the full web-to-CLI map are in
+[about Mammoth](references/about-mammoth.md).
+
 ## Start
 
 ```bash
@@ -42,6 +55,38 @@ before the next step.
 - Commands that start platform work wait up to 300 s for the job; on
   `timeout` use the `job get` recovery command printed, do not resubmit.
 
+## Find the command for a goal
+
+State the goal in plain words; the search knows common phrasing, and
+`view transform --help` is the Transform menu with one line per task:
+
+```bash
+mammoth schema find "merge two datasets"   # -> view.transform.join
+mammoth view transform --help              # every data transformation
+```
+
+| Goal | Command |
+|---|---|
+| Combine two datasets on a key (merge, VLOOKUP) | `view transform join`; one value per key: `view transform lookup` |
+| Add rows to an existing dataset | `file upload FILE --input '{"append_to_ds_id": DATASET_ID}'` |
+| Keep or remove rows | `view transform filter` |
+| Remove duplicate rows | `view transform discard-duplicates` |
+| Totals, counts, averages per group | `view transform pivot` |
+| A calculated column | `view transform math` |
+| Blanks to a constant, or to the previous row's value | `view transform set-values` (`IS_EMPTY`), `view transform fill-missing` |
+| Clean text | `view transform text`, `replace`, `bulk-replace` |
+| Change a column's type | `view transform convert-type` |
+| Rank, running total, previous row | `view transform window` |
+| A dashboard | `dashboard create-blank` ([dashboards](references/recipes/dashboards.md)) |
+| Deliver the rows | `view export csv`, `view export postgres` (and other destinations), `view export dataset` |
+
+A search with no full match returns `suggestions` and a `hint`. Before you
+conclude the CLI cannot do something the web app does, check
+`view transform --help` and "Not a pipeline step" in
+[about Mammoth](references/about-mammoth.md). Do not switch to the web app
+in a browser, or compute the result locally, for work the CLI covers;
+report a real gap with the command you tried.
+
 ## Calling a command
 
 - Ids are positionals; request fields are one `--input '{...}'` document;
@@ -89,6 +134,8 @@ before the next step.
 
 ## Route only what the task needs
 
+- **What Mammoth is, its data model, which feature fits a business goal, or
+  a web-app task you cannot find in the CLI:** [about Mammoth](references/about-mammoth.md)
 - **Cold start, task plan, or unsupported route:** [task start](references/task-start.md)
 - **Login, profiles, and authorized scope:** [auth](references/auth.md)
 - **Nested input, output envelopes, confirmations, jobs, or recovery:**

mammoth_cli-2.0.37/mammoth_cli/bundled_skill/mammoth-cli/references/about-mammoth.md

@@ -0,0 +1,144 @@
+# What Mammoth is, and what it can do
+
+Read this when the task is stated as a business goal ("combine these files",
+"a monthly summary per region", "feed this to Power BI") and you need to know
+which Mammoth feature does it, or when you think the CLI cannot do something
+the web app can.
+
+## Why Mammoth exists
+
+Mammoth Analytics is a cloud platform that turns raw business data into
+output people can trust and that stays current, without code. It has two
+layers:
+
+- **Preparation (the engine).** Data comes in from files, URLs or
+  connectors. It is cleaned, reshaped, joined and calculated in a
+  **pipeline**: an ordered list of tasks on a **view**. The pipeline re-runs
+  when new data arrives, so a monthly report is built once and refreshed,
+  not rebuilt.
+- **Output.** Dashboards (and presentations, documents and Q&A pages) are
+  built from a prepared view. Data is also delivered: CSV downloads,
+  databases, cloud storage, BI tools, or another Mammoth dataset. Every
+  number is computed from the prepared data, never written by a model.
+
+People use it to replace manual spreadsheet work: an analyst automating a
+recurring report, a small practice producing client deliverables, a team
+feeding clean data to Tableau or Power BI. Every step is visible and
+repeatable, which is the point: someone else can inspect, re-run or take
+over the work. So, as an agent, build the steps **in Mammoth** (as pipeline
+tasks, dashboards and exports) rather than computing a result locally and
+uploading it; a local result does not refresh and cannot be inspected.
+
+## How Mammoth organises data
+
+```
+workspace            account and billing; an API token belongs to one workspace
+└─ project           a container with its own members; work stays inside one
+   └─ dataset        data from an upload, URL or connector; each import is a batch
+      └─ view        a working copy of the dataset's rows; a dataset can have several
+         ├─ pipeline tasks run top to bottom; each `view transform` adds one at the end
+         ├─ exports   CSV, databases, cloud storage, BI tools, another dataset
+         └─ dashboards built from the view's prepared rows
+```
+
+- An upload returns a **dataset** id. Transforms, joins, exports and
+  dashboards take a **view** id (`view list DATASET_ID`).
+- Columns have a **display name** (what people see, and what every CLI
+  input uses) and an internal name (`column_7`), which you never type.
+- A task that ran is part of the view: later data refreshes run it again.
+  Draft mode (`view draft enter` / `submit`) holds several tasks and runs
+  them together.
+
+## What it can do, and where that is in the CLI
+
+| Goal | Web app | CLI |
+|---|---|---|
+| Bring data in | Data → new dataset | `file upload`, `dataset create` (URL), `connector ...` |
+| Add rows to existing data | a new batch on the dataset | `file upload FILE --input '{"append_to_ds_id": DATASET_ID}'` |
+| Clean and reshape | View → Transform menu | `view transform OPERATION` (table below) |
+| Combine two sources | Transform → Join, Lookup | `view transform join`, `view transform lookup` |
+| Summarise | Transform → Group & Pivot | `view transform pivot`, `view transform crosstab` |
+| 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 ...` |
+| 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` |
+
+Whether a route ran on release is in [capabilities](capabilities.md); read
+it before you promise a deliverable. `schedule` is not implemented on
+release.
+
+## The Transform menu, command by command
+
+The web app groups its pipeline tasks in a Transform menu. Each data task is
+a `mammoth view transform` command; `mammoth view transform --help` lists
+them with one line each, and `mammoth schema get view.transform.join` (or
+any other operation) gives the input. Send to Dataset is `view export dataset`; Data Check and
+Checkpoint Alert are the `view data-check` and `view checkpoint` families.
+
+| You want to | Web app task | Command |
+|---|---|---|
+| Keep or remove rows that match a condition | Conditional Filter | `filter` (`filter_type` `SHOW` or `REMOVE`) |
+| Remove duplicate rows | Remove Duplicate Rows | `discard-duplicates` |
+| Keep the first or last N rows by an order | Show Top/Bottom Rows | `limit-rows` (`n`, `order_by`, `bottom`) |
+| Write a value where a condition holds, or a label or bucket column | Label & Insert Values | `set-values` |
+| Fill blanks with the previous or next row's value | Fill Missing Values | `fill-missing` |
+| Find and replace one value | Find & Replace | `replace` |
+| Map many spellings to one value | Bulk Replace | `bulk-replace` |
+| Change case or trim spaces | Text Formatting | `text` |
+| Take part of a text value (characters or regex) | Extract Text | `substring` |
+| Split one column into several | Split Into Multiple Columns | `split` |
+| Join several columns into one text column | Combine Columns & Text | `combine-columns` |
+| Change a column's type | Convert Column Type | `convert-type` |
+| Calculate a column from others | Math Function | `math` |
+| Rank, running total, previous or next row | Window function | `window` |
+| Nth smallest or largest across columns | Obtain Large or Small Values | `small-large` |
+| Take a year, month, weekday from a date | Extract Date Part | `extract-date` |
+| Days (or months, ...) between two dates | Calculate Date Difference | `date-diff` |
+| Shift a date by an interval | Add / Subtract Date Values | `increment-date` |
+| Add an empty column | Add Column | `add-column` |
+| Copy a column under a new name | Copy Columns | `copy-columns` |
+| Remove columns | Remove Column | `delete-columns` |
+| Add columns from another view by matching keys | Join | `join` (`INNER`, `LEFT`, `RIGHT`, `OUTER`) |
+| Bring one value per key from another view | Lookup | `lookup` |
+| Totals, counts, averages per group | Group & Pivot | `pivot` (replaces the view's columns) |
+| A rows-by-columns summary table | Group & Pivot (crosstab) | `crosstab` (writes a new dataset) |
+| Turn wide columns into label/value rows | Unpivot | `unnest` |
+| Read fields out of a JSON column | Extract JSON | `json-extract` |
+| Classify, tag or summarise rows with AI | Generative AI | `ai` |
+| One SQL query over the view | AI SQL Query | `add-sql` (replaces the view's columns), `generate-sql` (from plain words) |
+| Copy rows into another dataset, refreshed with the pipeline | Send to Dataset | `view export dataset` (not a `view transform`) |
+
+`join` or `lookup`: `join` adds the chosen columns from every matching row
+(a key that repeats on the other side repeats rows); `lookup` brings one
+value per key into one new column. Before either, confirm the key columns
+in both views have the same type and values; recipes/transforms.md has the
+read-back.
+
+## Not a pipeline step, and the nearest route
+
+- **Rename a column.** The web app's rename is a display change, not a
+  task; the CLI has no rename command. Name new columns when you create them
+  (`new_column`, `as_name`); for an existing column, `copy-columns` under
+  the new name.
+- **Sort.** There is no sort task, and the CLI has no sort command. For
+  "top N by X" use `limit-rows` with `order_by`; for a rank column use
+  `window` (`RANK`, `ROW_NUMBER`).
+- **Union or append two views.** There is no union task. Upload a file into
+  an existing dataset with `append_to_ds_id`, or send a view's rows into an
+  existing dataset with `view export dataset` (`target_ds_id` and
+  `save_as_mode` `APPEND_TO_DS`; that mode is untried on release).
+- **Hide or reorder columns.** Display changes in the web app; they do not
+  change the data.
+
+## The web app and the CLI
+
+Both call the same API. Do not switch to the web app in a browser for a
+task the CLI covers. Before you conclude that the CLI cannot do something,
+run `mammoth view transform --help`, search in plain words (`mammoth schema
+find "merge two datasets"` finds `join`; a search with no full match lists
+`suggestions`), and read the section above. If it is still missing, report
+the gap with the command you tried; do not work around it in the browser or
+by computing the result locally.

{mammoth_cli-2.0.36 → mammoth_cli-2.0.37}/mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md

@@ -46,14 +46,17 @@ or secrets in an argument, prompt, transcript, or checkpoint.
 
    Do not print, echo, or copy secret-bearing inputs. A failed status, login,
    or doctor check stops the task before discovery and business commands.
-4. Discover instead of guessing. Run `mammoth schema list/find/get --output
-   json --no-input` for local CLI routes; `mammoth capability list --output
-   json --no-input` is an API-binding inventory and can omit typed/local
-   routes. Check [capabilities](capabilities.md) for whether a route is
-   proven, not supported, or untried on release before building a plan on
-   it. Then resolve workspace/project/dataset/view
+4. Discover instead of guessing. Search with the goal in plain words
+   (`mammoth schema find "merge two datasets"` finds the join), then run
+   `mammoth schema get COMMAND_ID` for local CLI routes; `mammoth view transform
+   --help` lists every data transformation; `mammoth schema list` is the
+   complete inventory. `mammoth capability list` is an API-binding inventory
+   and can omit typed/local routes. Check [capabilities](capabilities.md)
+   for whether a route is proven, not supported, or untried on release
+   before building a plan on it. Then resolve workspace/project/dataset/view
    parents with reads. Use display names returned by the exact view schema.
-5. Translate the business intent into a plan the agent chooses. Submit only
+5. Translate the business intent into a plan the agent chooses;
+   [about Mammoth](about-mammoth.md) maps goals to features. Submit only
    supported operations against the active project (`project ensure` sets it;
    `--project` overrides) with structured `--input`. Do not use private
    HTTP/SDK escape hatches or local data processing as a substitute.

{mammoth_cli-2.0.36 → mammoth_cli-2.0.37}/mammoth_cli/commands/schema.py

@@ -56,31 +56,98 @@ _GROUP_DISCOVERY_PURPOSES = {
     "dataset": "data import tables CSV spreadsheet",
     "file": "source file storage",
     "view": "transform query clean analyze data pipeline",
-    "dashboard": "build visualize share charts analytics",
+    "dashboard": "build visualize share chart charts report analytics",
     "workflow": "automate pipeline orchestration",
 }
 
 _COMMAND_DISCOVERY_PURPOSES = {
-    "file.upload": "upload import CSV spreadsheet XLSX source data",
+    "file.upload": (
+        "upload import CSV spreadsheet XLSX source data append add rows union stack "
+        "a file into an existing dataset"
+    ),
     "file.upload-folder": "upload source-data directory folder",
     "view.export.csv": "export download local CSV file artifact",
+    "view.export.dataset": (
+        "send copy branch out rows into a dataset in another project append union stack rows"
+    ),
+    # One entry per ``view transform`` command, in the words a user states a
+    # goal in rather than Mammoth's own task names.  This is the CLI's version
+    # of the web app's Transform menu; keep every transform listed.
+    "view.transform.add-column": "add column new empty blank column",
+    "view.transform.add-sql": "sql query select statement replaces every column",
+    "view.transform.ai": (
+        "ai llm prompt generative classify categorize categorise sentiment enrich "
+        "summarize summarise rows into a new column"
+    ),
+    "view.transform.bulk-replace": (
+        "find replace strip characters text values mapping standardize standardise "
+        "normalize normalise variants many to one"
+    ),
+    "view.transform.combine-columns": (
+        "combine concatenate concat columns values into one column separator"
+    ),
+    "view.transform.convert-type": (
+        "convert type cast numeric number text date column parse to number to date"
+    ),
+    "view.transform.copy-columns": "copy duplicate rename column into a new column name",
+    "view.transform.crosstab": (
+        "crosstab cross tab pivot table matrix rows by columns summary into a new dataset"
+    ),
+    "view.transform.date-diff": "date difference days between two date columns age duration",
+    "view.transform.delete-columns": "delete drop remove columns",
     "view.transform.discard-duplicates": (
-        "duplicate duplicates dedup deduplicate remove repeated rows"
+        "duplicate duplicates dedup dedupe deduplicate remove repeated rows unique distinct"
     ),
-    "view.transform.convert-type": "convert type cast numeric text date column",
-    "view.transform.fill-missing": "fill missing null empty impute carry forward values",
-    "view.transform.join": "join blend lookup merge matching keys rows",
     "view.transform.extract-date": (
         "extract date part year month day hour minute second week quarter weekday "
         "month_text into a new column"
     ),
-    "view.transform.date-diff": "date difference days between two date columns age duration",
+    "view.transform.fill-missing": (
+        "fill missing null empty blank blanks impute carry forward fill down values"
+    ),
+    "view.transform.filter": (
+        "filter rows keep drop exclude remove delete rows where condition subset"
+    ),
+    "view.transform.generate-sql": (
+        "generate sql from natural language intent question and run it as a task"
+    ),
     "view.transform.increment-date": "add subtract days months years to a date column shift",
-    "view.transform.math": "math arithmetic multiply divide add subtract formula expression amount",
-    "view.transform.pivot": "pivot group by aggregate sum count summary per region total",
-    "view.transform.set-values": "set values assign overwrite blank empty default where condition",
-    "view.transform.text": "text case upper lower title trim whitespace normalise",
-    "view.transform.bulk-replace": "find replace strip characters text values mapping",
+    "view.transform.join": (
+        "join blend merge combine enrich match matching keys rows add columns from another "
+        "second view views dataset datasets table tables vlookup"
+    ),
+    "view.transform.json-extract": "json extract parse nested fields keys into columns",
+    "view.transform.limit-rows": "limit top bottom first last n rows order by sorted head",
+    "view.transform.lookup": (
+        "lookup look up vlookup reference table map code to name enrich one value "
+        "from another view dataset"
+    ),
+    "view.transform.math": (
+        "math arithmetic multiply divide add subtract formula expression amount "
+        "calculate compute ratio percentage round"
+    ),
+    "view.transform.pivot": (
+        "pivot group by aggregate aggregation sum count average summary summarize "
+        "summarise per region total"
+    ),
+    "view.transform.replace": "find replace substitute text value in columns",
+    "view.transform.set-values": (
+        "set values assign overwrite blank empty default where condition label "
+        "category bucket flag if then conditional value"
+    ),
+    "view.transform.small-large": "nth smallest largest value across columns",
+    "view.transform.split": "split column by delimiter separator into columns",
+    "view.transform.substring": "substring left right characters regex pattern extract part text",
+    "view.transform.text": (
+        "text case upper uppercase lower lowercase title trim whitespace normalise normalize"
+    ),
+    "view.transform.unnest": (
+        "unnest unpivot melt wide to long columns into label value rows reshape"
+    ),
+    "view.transform.window": (
+        "window rank row number running total cumulative sum moving average lag lead "
+        "previous next row partition"
+    ),
 }
 
 # A compact string scope is retained for existing discovery consumers.  These
@@ -138,9 +205,52 @@ _DISCOVERY_SYNONYMS: dict[str, tuple[str, ...]] = {
     "asynchronous": ("async", "job", "wait"),
     "async": ("job", "wait", "poll"),
     "poll": ("job", "wait", "status"),
+    # British spellings search the same as the American ones.
+    "summarise": ("summarize",),
+    "standardise": ("standardize",),
+    "normalise": ("normalize",),
+    "categorise": ("categorize",),
 }
 _DISCOVERY_STOPWORDS = frozenset(
-    {"a", "an", "the", "me", "please", "for", "to", "of", "by", "with", "can", "i"}
+    {
+        "a",
+        "an",
+        "the",
+        "me",
+        "please",
+        "for",
+        "to",
+        "of",
+        "by",
+        "with",
+        "can",
+        "i",
+        # Filler in goal phrasing ("merge my two datasets"); a command never
+        # turns on these words, so they must not sink an otherwise good match.
+        "my",
+        "our",
+        "two",
+        "another",
+        "other",
+        "into",
+        "from",
+        "and",
+        "all",
+        "each",
+        "this",
+        "that",
+        "how",
+        "do",
+        "want",
+        "need",
+    }
+)
+# How many near misses a search with no full match returns.
+_MAX_SUGGESTIONS = 5
+_NO_MATCH_HINT = (
+    "No command matched every word. 'suggestions' match some of them; try fewer or other "
+    "words. 'mammoth view transform --help' lists every data transformation (join, pivot, "
+    "filter, dedupe, math, ...), and 'mammoth schema list' is the complete inventory."
 )
 _TOKEN_RE = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
 
@@ -967,15 +1077,21 @@ def find_schemas(
     the included ``full_schema_command`` to fetch the authoritative detail.
     Every whitespace-separated term must occur in a command name, its examples,
     or its stable operation-purpose text, making the result deterministic and
-    easy to compose in scripts.
+    easy to compose in scripts.  When no command carries every term, the result
+    adds ``suggestions`` (the commands that carry the most terms) and a ``hint``,
+    so a cold caller who phrased the goal in other words is not left with an
+    empty list.
     """
-    terms = _query_tokens(query)
+    # A query made only of filler words keeps them, rather than matching
+    # every command.
+    terms = _query_tokens(query) or tuple(_tokens(query))
     # Clamp caller-provided bounds instead of allowing an accidental unbounded
     # discovery response.  A negative cursor is a usage mistake, not a request
     # to wrap around the catalog.
     bounded_limit = max(1, min(int(limit), _MAX_FIND_LIMIT))
     offset = max(0, int(cursor))
     ranked_matches: list[tuple[int, dict[str, Any]]] = []
+    near_misses: list[tuple[int, int, dict[str, Any], list[str]]] = []
     for record in load_commands():
         if record.get("disposition") == "alias":
             continue
@@ -994,13 +1110,11 @@ def find_schemas(
         )
         searchable = " ".join(source for _, source in sources).casefold()
         searchable_tokens = _tokens(f"{primary_text} {searchable}")
+        matched_terms = [term for term in terms if _token_aliases(term) & searchable_tokens]
+        if not matched_terms:
+            continue
         score = 0
-        matched = True
-        for term in terms:
-            aliases = _token_aliases(term)
-            if not (aliases & searchable_tokens):
-                matched = False
-                break
+        for term in matched_terms:
             if term in _tokens(primary_text):
                 score += 100
             elif term in _tokens(searchable):
@@ -1011,29 +1125,29 @@ def find_schemas(
             # command-id ordering breaks all remaining ties.
             if term in searchable_tokens:
                 score += 10
-        if matched:
-            # Purpose and command-specific hints are stronger than generic
-            # family words such as ``data`` or ``show``.
-            score += 5 * sum(
-                1 for term in terms if any(term in source.casefold() for _, source in sources[:2])
-            )
-            command_purpose = _COMMAND_DISCOVERY_PURPOSES.get(command_id, "").casefold()
-            score += 100 * sum(1 for term in terms if term in _tokens(command_purpose))
-            action = command_path.split()[1] if len(command_path.split()) > 1 else ""
-            if "show" in terms and action in {"list", "get", "browse"}:
-                score += 80
-            ranked_matches.append(
-                (
-                    score,
-                    {
-                        "command_id": command_id,
-                        "command_path": command_path,
-                        "mutation_class": record["mutation_class"],
-                        "confirmation": record["confirmation"],
-                        "full_schema_command": (f"mammoth schema get {command_id}"),
-                    },
-                )
-            )
+        # Purpose and command-specific hints are stronger than generic
+        # family words such as ``data`` or ``show``.
+        score += 5 * sum(
+            1
+            for term in matched_terms
+            if any(term in source.casefold() for _, source in sources[:2])
+        )
+        command_purpose = _COMMAND_DISCOVERY_PURPOSES.get(command_id, "").casefold()
+        score += 100 * sum(1 for term in matched_terms if term in _tokens(command_purpose))
+        action = command_path.split()[1] if len(command_path.split()) > 1 else ""
+        if "show" in matched_terms and action in {"list", "get", "browse"}:
+            score += 80
+        entry = {
+            "command_id": command_id,
+            "command_path": command_path,
+            "mutation_class": record["mutation_class"],
+            "confirmation": record["confirmation"],
+            "full_schema_command": (f"mammoth schema get {command_id}"),
+        }
+        if len(matched_terms) == len(terms):
+            ranked_matches.append((score, entry))
+        else:
+            near_misses.append((len(matched_terms), score, entry, matched_terms))
     ranked_matches.sort(key=lambda item: (-item[0], item[1]["command_id"]))
     total_matches = len(ranked_matches)
     page = [match for _, match in ranked_matches[offset : offset + bounded_limit]]
@@ -1048,13 +1162,23 @@ def find_schemas(
         if has_more
         else None
     )
-    return {
+    result: dict[str, Any] = {
         "query": query,
         "matches": page,
         "total_matches": total_matches,
         "truncated": has_more,
         "continuation": continuation,
     }
+    if total_matches == 0:
+        # Most terms first, then the ordinary score: a command that carries
+        # two of three words beats one that carries a single common word.
+        near_misses.sort(key=lambda item: (-item[0], -item[1], item[2]["command_id"]))
+        result["suggestions"] = [
+            {**entry, "matched_terms": matched}
+            for _, _, entry, matched in near_misses[:_MAX_SUGGESTIONS]
+        ]
+        result["hint"] = _NO_MATCH_HINT
+    return result
 
 
 def get_schema(command_id: str) -> dict[str, Any] | None:

{mammoth_cli-2.0.36 → mammoth_cli-2.0.37}/mammoth_cli/skills/steering.py

@@ -25,7 +25,9 @@ DEFAULT_STEERING_PATH = "AGENTS.md"
 STEERING_BODY = """## Mammoth Analytics
 
 Use the `mammoth` CLI for all Mammoth work; do not call the REST API or the
-Python SDK directly. Before the first Mammoth command in a session run
+Python SDK directly, and do not drive the web app in a browser: every web
+Transform-menu task is a `mammoth view transform` command (`mammoth view
+transform --help`). Before the first Mammoth command in a session run
 `mammoth doctor` (it must pass), then `mammoth skill show` and follow that
 guide. If `mammoth` is missing, install it with `pip install mammoth-cli`
 (or `uv tool install mammoth-cli`). If `mammoth auth status` shows no

{mammoth_cli-2.0.36 → mammoth_cli-2.0.37}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mammoth-cli"
-version = "2.0.36"
+version = "2.0.37"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"