mammoth-cli 2.0.71__tar.gz → 2.0.73__tar.gz

{mammoth_cli-2.0.71 → mammoth_cli-2.0.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.71
+Version: 2.0.73
 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.32
+Requires-Dist: mammoth-io<0.8,>=0.7.33
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.0.71 → mammoth_cli-2.0.73}/mammoth_cli/app.py

@@ -44,6 +44,7 @@ from mammoth_cli.output.policy import (
 from mammoth_cli.runtime import executor, validate
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.strict import validate_extra_args
+from mammoth_cli.runtime.verify import with_verify
 from mammoth_cli.services.positionals import PositionalSpec, resolve_positionals
 
 OUTPUT_MODES = VALID_OUTPUTS
@@ -823,7 +824,8 @@ def _execute(invocation: Invocation) -> None:
             raise not_implemented_error(invocation.command_id, sdk_symbol)
         if invocation.dry_run:
             return _dry_run(handler, invocation)
-        return handler(invocation)
+        data, meta = handler(invocation)
+        return _apply_verify(invocation.command_id, data), meta
 
     executor.run(
         invocation.command_id,
@@ -835,6 +837,19 @@ def _execute(invocation: Invocation) -> None:
     )
 
 
+def _apply_verify(command_id: str, data: Any) -> Any:
+    """Add the automatic write read-back to a real, mutating, API-backed result.
+
+    A read command and a command with no reviewed ``sdk_symbol`` (a local or
+    not-yet-backed command) are returned unchanged; ``--dry-run`` never
+    reaches this at all, since it returns before the handler's real call.
+    """
+    record = command_by_id(command_id) or {}
+    if record.get("mutation_class") == "read" or not record.get("sdk_symbol"):
+        return data
+    return with_verify(data)
+
+
 def _dry_run(handler: Handler, invocation: Invocation) -> tuple[Any, dict[str, Any]]:
     """Run ``handler`` until its request would leave; report that request.
 

{mammoth_cli-2.0.71 → mammoth_cli-2.0.73}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: mammoth-cli
-version: 2.0.71
+version: 2.0.73
 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
 
-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.
+Use this skill for Mammoth shell work, not Python SDK integration. The CLI
+is the contract: it validates requests locally and returns one JSON
+envelope, with no flag needed for that when piped.
 
 ## What Mammoth is
 
@@ -18,9 +18,8 @@ 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
+this CLI call the same API: every Transform-menu task is a `mammoth view
+transform` command. The data model, capabilities and full web-to-CLI map:
 [about Mammoth](references/about-mammoth.md).
 
 ## Start
@@ -30,13 +29,13 @@ mammoth doctor                          # auth, endpoint, connectivity, version;
 mammoth project ensure 'PROJECT NAME'   # get-or-create; becomes the active project
 ```
 
-`doctor` failing is a precondition failure, not a reason to try the business
-command anyway. When the connection check fails with a 502, 504 or timeout,
-`mammoth doctor --input '{"wait": 300}'` probes again for up to that many
-seconds; go on only when it passes. Production is the `app` endpoint; use `release` only when the
-task names it, and check `meta.profile`/`auth status` `endpoint` match the
-intended environment before doing anything. If no profile has credentials,
-tell the operator to run `mammoth auth login` in their own terminal (add
+`doctor` failing is a precondition failure, not a reason to proceed anyway.
+When the connection check fails with a 502, 504 or timeout, `mammoth doctor
+--input '{"wait": 300}'` probes again for up to that many seconds; continue
+only once it passes. Production is the `app` endpoint; use `release` only
+when named, and check `meta.profile`/`auth status` `endpoint` match before
+continuing. If no profile has credentials, tell the operator to run
+`mammoth auth login` in their own terminal (add
 `--profile NAME` only for a profile other than `default`; [auth](references/auth.md)
 says where the token comes from) and wait; never ask for the token in chat,
 never read one from a file or environment variable, never run `auth login`
@@ -65,12 +64,13 @@ State the goal in plain words; the search knows common phrasing, and
 ```bash
 mammoth schema find "merge two datasets"   # -> view.transform.join
 mammoth view transform --help              # every data transformation
+mammoth schema find "join two datasets; remove duplicates; build a dashboard"   # 1 call, 1 result per goal
 ```
 
 | 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, or combine two sources | `file upload FILE --input '{"append_to_ds_id": DATASET_ID}'`; then `discard-duplicates` and diff `row_count` before/after ([about Mammoth](references/about-mammoth.md#view-settings-and-what-has-no-command)) |
+| Add rows to an existing dataset, or combine sources | Local file: `file upload FILE --input '{"append_to_ds_id": DATASET_ID}'`. Already in Mammoth: `view export dataset VIEW_ID --input '{"dataset_name": "NAME"}'`, then per further source `view export dataset VIEW_ID --input '{"dataset_name": "NAME", "target_ds_id": DATASET_ID, "save_as_mode": "APPEND_TO_DS"}'` — combine first, clean once; then `discard-duplicates` and diff `row_count` before/after ([about Mammoth](references/about-mammoth.md#view-settings-and-what-has-no-command)) |
 | Keep or remove rows | `view transform filter` |
 | Remove duplicate rows | `view transform discard-duplicates` |
 | Totals, counts, averages per group — just to read the number | `view data aggregate` (read-only: `--input '{"group_by": [...], "aggregations": [{"column": ..., "function": "SUM"}]}'` or `{"metric": {...}}`); never add a `pivot` task just to answer a question |
@@ -83,38 +83,36 @@ mammoth view transform --help              # every data transformation
 | Rank, running total, previous row | `view transform window` |
 | A dashboard | `dashboard v3 generate`, then `chat edit` ([dashboards](references/recipes/dashboards.md)) |
 | Deliver the rows | `view export csv`, `view export postgres` (and other destinations), `view export dataset` |
-| Run something on a schedule or on new data (refresh, append, alert) | `automation create`: a condition (`at_specific_time`, new file in a folder, ...) and tasks (`run_data_retrieval`, `append_data`, `send_an_alert`, `pull_cloud_files`). `schedule create` only pulls a connector's data. A dataset made from an uploaded file has no source to refresh from; say so. Full recipe, including a known `automation get` backend caveat: [recurring work](references/recipes/scheduling.md) |
+| Run something on a schedule or on new data (refresh, append, alert) | `automation create`: a condition (`at_specific_time`, new file in a folder, ...) and tasks (`run_data_retrieval`, `append_data`, `send_an_alert`, `pull_cloud_files`). `schedule create` only pulls a connector's data. A dataset from an uploaded file or URL is a one-time copy with no source to refresh; say so. Full recipe, including a known `automation get` backend caveat: [recurring work](references/recipes/scheduling.md) |
 
 Call a find result (or `suggestions` entry) from its `accepted_fields` and
-`agent_example`. Before you
-conclude the CLI cannot do something the web app does, check
-`view transform --help` and "View settings, and what has no command" 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.
+`agent_example`. Before concluding the CLI cannot do something the web app
+does, check `view transform --help` and "View settings, and what has no
+command" in [about Mammoth](references/about-mammoth.md). Do not switch to
+the browser, or compute locally, for work the CLI covers; report a real gap
+with the command tried.
 
 ## Several files, one deliverable
 
 Users often upload related files without saying how they relate ("make a
-dashboard from t_a and t_b"). Work it out from the data before you build:
-
-1. Upload every file. Each upload result carries a `view` preview of what
-   Mammoth made of the file (`view_id`, column types, sample rows,
-   `column_warnings`, and `before_dashboard`). Do not open the local files
-   (`cat`, `head`): what counts is what Mammoth made of them. Run `view data
-   get VIEW_ID` for each view. The warnings list numbers or dates stored as
-   text, and blanks, each with the fix.
+dashboard from t_a and t_b"). Work it out from the data before building:
+
+1. Upload every file. Each result carries a `view` preview of what Mammoth
+   made of it (`view_id`, column types, sample rows, `column_warnings`,
+   `before_dashboard`). Do not open the local files (`cat`, `head`) — what
+   Mammoth made of them is what counts. Run `view data get VIEW_ID` per view;
+   warnings list numbers/dates stored as text, and blanks, each with its fix.
 2. Find the keys. A column in one view whose values appear in a column of
    the other (`customer_id` and `id`, `order_ref` and `order_no`) is a
    foreign key; the view with many rows per key is the main one.
 3. Make the keys match before the join: same type (`convert-type`), same
    case and padding (`text`), no blanks (`set-values`, `filter`).
 4. Act on every `column_warnings` entry for a column the deliverable uses:
-   run its `fix` (`convert-type` to `NUMERIC` or `DATE`; the values that are
-   not numbers become empty). A text `price` cannot be summed on a dashboard.
-   Then decide on each `blank_values` entry: fill, filter, or keep. Write one
-   line for each in your report (the column, the count, what you did and
-   why). A blank that you saw but did not mention is a miss.
+   run its `fix` (`convert-type` to `NUMERIC`/`DATE`; non-numeric values
+   become empty) — a text `price` cannot be summed on a dashboard. Then
+   decide each `blank_values` entry: fill, filter, or keep, and report one
+   line per entry (column, count, what and why). A blank seen but unmentioned
+   is a miss.
 5. `view transform join` the lookup view into the main view (`LEFT`). The
    result's `join_check` gives `match_rate`, `unmatched_rows` and
    `unmatched_keys`; put them in your report, and stop to compare the keys
@@ -123,9 +121,9 @@ dashboard from t_a and t_b"). Work it out from the data before you build:
    (`math`, `qty * price`, `new_column`), the `fix` in `before_dashboard`.
    A dashboard sees only the columns the view had when it was made.
 7. Build the dashboard from the joined view with one sentence
-   ([dashboards](references/recipes/dashboards.md)) that charts the sum of
-   revenue. Do not sum a unit price. Fix each `deliverable_check` warning,
-   or say in the report why not.
+   ([dashboards](references/recipes/dashboards.md)) charting the sum of
+   revenue, not a unit price. Fix each `deliverable_check` warning, or say
+   why not.
 
 For the defaults that most pipelines use (new column or overwrite, `LEFT`
 joins, date steps), see
@@ -136,7 +134,7 @@ your report. If no column links the files, ask before you combine them.
 ## Calling a command
 
 - Ids are positionals; request fields are one `--input '{...}'` document;
-  there are no per-field flags (`project create NAME`, not `--name`).
+  no per-field flags (`project create NAME`, not `--name`).
 - `mammoth skill show --input '{"file": "references/recipes/transforms.md"}'`
   prints any file of this skill; `mammoth skill agents-md install` writes a
   steering block into a repository's AGENTS.md so later sessions start here.
@@ -150,10 +148,10 @@ your report. If no column links the files, ask before you combine them.
   status, row_count, `metadata` columns and types, pipeline state);
   `view get ... --input '{"fields": "__full"}'` or `view list ... --input
   '{"full": true}'` returns the dependency and display trees too.
-- Column inputs and expressions use the exact **display names** the view
+- Column inputs/expressions use the exact **display names** the view
   returns, never backend aliases.
-- `--dry-run` on any API-backed command resolves everything and reports the
-  request instead of sending it; use it before a write you are not sure of.
+- `--dry-run` on any API-backed command resolves and reports the request
+  instead of sending it; use before a write you are unsure of.
 - Deletes need `--yes`; high-impact ones (`project delete`, access changes)
   also need `--confirm ID`, and `schema get` shows which. Preserve requested
   deliverables; cleanup is exact-ID authorized and
@@ -167,14 +165,13 @@ your report. If no column links the files, ask before you combine them.
 - A success envelope proves the call, not the outcome. After a row-scoped
   change (set-values, filter, replace, join, fill) run `view data get
   VIEW_ID` (50 rows by default, `limit` to change) and check rows the
-  condition should have touched and rows it should not have. Sample the
-  target column *before* the change so the after-read has a comparison.
+  condition should and should not have touched. Sample the target column
+  *before* the change for comparison.
 - A uniform result (every amount 0, every region "Unknown", most join rows
   unmatched) means the previous step went wrong; stop and re-inspect it.
 - `column_warnings` on a data read and `join_check` on a join are findings,
-  not decoration: fix each one the deliverable depends on, or say in the
-  report why you kept it. `view data get` pages with `{"offset": 51,
-  "limit": 50}`.
+  not decoration: fix each the deliverable depends on, or say why kept.
+  `view data get` pages with `{"offset": 51, "limit": 50}`.
 - A timeout, exit 7 or interruption does not prove failure; reconcile an
   `outcome_unknown` (`job get`, `view task list`) before replaying.
 - Check an answer with no write against the question (a trend: time
@@ -182,9 +179,9 @@ your report. If no column links the files, ask before you combine them.
 - After a write, run `mammoth project check PROJECT_ID` and fix each
   `to_report` line, or give it one line in the report.
 - Run the [report checklist](references/report-checklist.md) before stating
-  a number or calling a step done. When files here disagree,
-  [capabilities](references/capabilities.md) wins over a recipe, and a recipe
-  over the generated command catalog.
+  a number or calling a step done. When files disagree,
+  [capabilities](references/capabilities.md) wins over a recipe, which wins
+  over the generated catalog.
 
 ## Route only what the task needs
 
@@ -204,9 +201,9 @@ your report. If no column links the files, ask before you combine them.
   [recovery](references/recovery.md) — failure modes by message and the
   stop-condition list
 - **A known command family or exact command:** [command catalog](references/command-index.md)
-  — a lookup for the one command you need, not upfront reading; each entry
-  carries its release status line, and a `not supported` or `observed
-  blocker` entry names the route to use instead
+  — a lookup for one command, not upfront reading; each entry carries its
+  release status line, and a `not supported`/`observed blocker` entry names
+  the route to use instead
 - **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
@@ -214,9 +211,9 @@ your report. If no column links the files, ask before you combine them.
 
 ## Handoff checklist
 
-Before yielding work, write a nonsecret checkpoint with the intent and
-acceptance criteria; authorized profile/workspace/project; observed resource
-parents; verified evidence hashes; known jobs and unknown outcomes; remaining
-objectives; and exact cleanup ownership. The receiving agent validates that
-record and re-reads remote state before deciding what to do next. The handoff
+Before yielding work, write a nonsecret checkpoint: intent and acceptance
+criteria; authorized profile/workspace/project; observed resource parents;
+verified evidence hashes; known jobs and unknown outcomes; remaining
+objectives; exact cleanup ownership. The receiving agent validates that
+record and re-reads remote state before deciding what to do next — a handoff
 is not a resume command or a grant of authority.

{mammoth_cli-2.0.71 → mammoth_cli-2.0.73}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/resources.md

@@ -122,4 +122,7 @@ not sufficient. `dataset.create` waits for its asynchronous work; only the
 `weburl` creation type is proven, other freeform variants remain unqualified.
 If the schema does not accept a URL,
 report URL import unsupported; do not silently substitute local processing. A
-4/5/7 envelope is a failed or uncertain operation, not a usable dataset.
+4/5/7 envelope is a failed or uncertain operation, not a usable dataset. A
+`weburl` dataset is a one-time copy: it keeps no source details, so it cannot be
+scheduled to refresh (see [recurring work](scheduling.md)); say so rather than
+promising a refreshable source.

{mammoth_cli-2.0.71 → mammoth_cli-2.0.73}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/scheduling.md

@@ -43,6 +43,10 @@ mammoth automation create 'Nightly refresh' --yes --input '{
 }'
 ```
 
+`run_data_retrieval` only refreshes a cloud-connected dataset; a dataset made
+from an uploaded file or a URL (`weburl`) is a one-time copy with no source
+details to refresh from — say so rather than scheduling one.
+
 The other three task types take the shapes documented in `schema get
 automation.create` under `tasks[].details`:
 

{mammoth_cli-2.0.71 → mammoth_cli-2.0.73}/mammoth_cli/commands/registry.py

@@ -152,16 +152,60 @@ def _schema_get(invocation: Invocation) -> HandlerResult:
     return schema_cmd.brief_schema(entry), {}
 
 
+#: Above this many ';'-separated goals in one 'schema find' call, an agent is
+#: almost certainly pasting something else (a whole plan, a sentence with
+#: semicolons) rather than a real goal list; reject with a clear message
+#: instead of silently running dozens of searches.
+_MAX_FIND_GOALS = 12
+
+_EMPTY_QUERY_ERROR = CliError(
+    code="empty_search_query",
+    message="The schema search query must contain at least one word.",
+    exit_status=EXIT_USAGE,
+    hint="For the complete inventory, use 'mammoth schema list'.",
+)
+
+
+def _cap_inline_detail(result: dict[str, Any], keep: int) -> None:
+    """Strip inline ``accepted_fields``/``agent_example`` past the top `keep`."""
+    for key in ("matches", "suggestions"):
+        for entry in (result.get(key) or [])[keep:]:
+            entry.pop("accepted_fields", None)
+            entry.pop("agent_example", None)
+
+
 def _schema_find(invocation: Invocation) -> HandlerResult:
     query = _require_arg(invocation, "search query")
     if not query.strip():
+        raise _EMPTY_QUERY_ERROR
+    if ";" not in query:
+        return schema_cmd.find_schemas(query), {}
+    # Several goals in one call ("join customers onto orders; remove
+    # duplicate rows; build a dashboard"): run the existing single-goal
+    # search per goal instead of round-tripping once per goal.
+    goals = [goal.strip() for goal in query.split(";") if goal.strip()]
+    if not goals:
+        raise _EMPTY_QUERY_ERROR
+    if len(goals) > _MAX_FIND_GOALS:
         raise CliError(
-            code="empty_search_query",
-            message="The schema search query must contain at least one word.",
+            code="too_many_goals",
+            message=(
+                f"schema find accepts at most {_MAX_FIND_GOALS} ';'-separated goals per "
+                f"call; got {len(goals)}."
+            ),
             exit_status=EXIT_USAGE,
-            hint="For the complete inventory, use 'mammoth schema list'.",
+            hint="Split the goals across more than one 'schema find' call.",
         )
-    return schema_cmd.find_schemas(query), {}
+    results = [schema_cmd.find_schemas(goal) for goal in goals]
+    if len(results) > 1:
+        # Cap inline accepted_fields/agent_example to the top match per goal
+        # so a multi-goal envelope stays small even when every goal has
+        # several candidates.
+        for result in results:
+            _cap_inline_detail(result, 1)
+    return {
+        "goals": [{"goal": goal, **result} for goal, result in zip(goals, results, strict=True)]
+    }, {}
 
 
 def _log_path(_: Invocation) -> HandlerResult:

{mammoth_cli-2.0.71 → mammoth_cli-2.0.73}/mammoth_cli/commands/schema.py

@@ -68,7 +68,8 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "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"
+        "send copy branch out create save the result rows into a new project from an "
+        "existing append appending union stack monthly rows across datasets views"
     ),
     # One entry per typed export destination, in the way users name the
     # destination rather than Mammoth's route spelling (which a two-word
@@ -195,7 +196,14 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "view.transform.date-diff": "date dates difference days between two date columns age duration",
     "view.transform.delete-columns": "delete drop remove columns",
     "view.transform.discard-duplicates": (
-        "duplicate duplicates dedup dedupe deduplicate remove repeated rows unique distinct"
+        "duplicate duplicates dedup dedupe deduplicate remove repeated rows unique distinct "
+        # "order"/"number" are kept as generic identifying-column vocabulary
+        # ("dedupe by an order/number/key"), not the specific business noun
+        # "order id" -- "order" also can't be dropped as a data word since
+        # view.transform.sort's own purpose text already uses it (sort
+        # order), so any query pairing "order" with dedupe words needs it
+        # covered here to reach a full match.
+        "by order number key column"
     ),
     "view.transform.extract-date": (
         "extract date part year month day hour minute second week quarter weekday "
@@ -211,8 +219,8 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "view.transform.generate-sql": "generate write sql query from natural language intent question",
     "view.transform.increment-date": "add subtract days months years to a date column shift",
     "view.transform.join": (
-        "join blend merge combine enrich match matching keys rows add columns from another "
-        "second view views dataset datasets table tables vlookup"
+        "join blend merge combine enrich match matching key 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 head",
@@ -223,7 +231,7 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "view.transform.math": (
         "math arithmetic multiply multiplication divide add subtract formula "
         "expression amount calculate compute ratio percentage round new column "
-        "conditional threshold greater than if text"
+        "conditional threshold greater than if text times"
     ),
     "view.transform.pivot": (
         "pivot group by aggregate aggregation sum count average summary summarize "
@@ -235,7 +243,7 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "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"
+        "category bucket flag if then conditional add a column with a constant value"
     ),
     "view.transform.small-large": "nth smallest largest value across columns",
     "view.transform.sort": (
@@ -261,6 +269,14 @@ _COMMAND_DISCOVERY_PURPOSES = {
         "distribution spread histogram top most common frequent values breakdown share "
         "percentage profile"
     ),
+    "view.create": "start a new one from an existing dataset, duplicate",
+    "dataset.list": "list every dataset in a project workspace",
+    # "month"/"week" are kept as generic calendar-grouping vocabulary (a
+    # group-by dimension any dataset can have), not a specific business
+    # value -- and neither can be dropped as a data word anyway, since
+    # view.data.explore's own purpose text already uses both for its trend
+    # feature.
+    "view.data.aggregate": "group and sum totals by month week without changing the pipeline",
     # Goals users state in their own words, one entry per command the agent's
     # system prompt used to spell out by hand.
     "dashboard.suggestion.list": "ideas suggest suggestions what to show put on a board chart",
@@ -349,6 +365,22 @@ _SCOPE_REQUIREMENTS: dict[str, dict[str, Any]] = {
 _MAX_FIND_RESULTS = 20
 # Outranks any word-overlap score: a command named by its full path comes first.
 _NAMED_COMMAND_BOOST = 10_000
+# Bag-of-words scoring cannot tell "create a NEW VIEW from an existing
+# DATASET" (view.create) apart from "create a DATASET from an existing
+# VIEW" (view.export.dataset): the two goals share the exact same word set,
+# and only word order says which resource is being made and which already
+# exists. No purpose text or synonym can encode that; this pair of small
+# adjacency checks is the intentionally scoped exception. Extend the two
+# dicts, never the regex, if another goal collides the same way.
+_NEW_OBJECT_HINTS: dict[str, str] = {
+    "view.create": "view",
+    "view.export.dataset": "dataset",
+}
+_EXISTING_OBJECT_HINTS: dict[str, str] = {
+    "view.create": "dataset",
+    "view.export.dataset": "view",
+}
+_OBJECT_ADJACENCY_BOOST = 150
 _MAX_FIND_LIMIT = 100
 # How many of a find's top matches carry inline accepted_fields/agent_example.
 # 35% of all eval tool calls were command discovery (schema find -> schema
@@ -372,6 +404,12 @@ _DISCOVERY_SYNONYMS: dict[str, tuple[str, ...]] = {
     "csv": ("spreadsheet", "file", "upload"),
     "local": ("file", "download", "csv", "artifact"),
     "download": ("export", "file", "csv", "artifact", "local"),
+    # "combine" alone is ambiguous between joining on a key and appending
+    # rows; kept a weak alias match (not a literal word) here so a bare
+    # "combine datasets" still favors join's own literal "combine" purpose
+    # text, while "combine ... by appending rows" still resolves to the
+    # export -- its own literal "append"/"union"/"stack" carry that case.
+    "combine": ("append", "union", "stack", "merge"),
     # "publish" a dataset almost always means one of the typed exports
     # (Power BI, a live DB connection, a webhook, ...); every export
     # command's path literally contains "export", so this one alias covers
@@ -454,6 +492,12 @@ _DISCOVERY_STOPWORDS = frozenset(
         "using",
         "than",
         "via",
+        # Filler prepositions in goal phrasing ("datasets as rows", "datasets
+        # in a project", "join two datasets on a key"); no command turns on
+        # any of these.
+        "as",
+        "in",
+        "on",
     }
 )
 # How many near misses a search with no full match returns.
@@ -669,6 +713,42 @@ def _adjacent_compound_forms(terms: tuple[str, ...]) -> dict[str, frozenset[str]
     return {term: frozenset(compounds) for term, compounds in forms.items()}
 
 
+@cache
+def _command_vocabulary_tokens() -> frozenset[str]:
+    """Every token that names a command or appears in its curated purpose text.
+
+    Distinguishes genuine CLI vocabulary from a data word -- a column,
+    table, or other business noun from the caller's own data (``orders``,
+    ``revenue``, ``store``) -- riding along in a goal. Counts a command's own
+    id/path (``user``, ``workspace``, ``invoice`` are real resource nouns a
+    command is named after) plus ``_COMMAND_DISCOVERY_PURPOSES``/
+    ``_GROUP_DISCOVERY_PURPOSES`` -- text hand-curated specifically to
+    describe what a command is for. Deliberately excludes ``human_example``/
+    ``agent_example`` and OpenAPI-derived operation hints: those are
+    illustrative sample values (a placeholder project name like "Revenue
+    report", a sample filename like "sales.csv") reused verbatim across
+    dozens of unrelated commands, so counting them would make almost any
+    plausible business noun look like real vocabulary and defeat this
+    check. A term absent from this set is not something any command is
+    named after or actually about, so :func:`find_schemas` drops it from a
+    goal's required terms rather than letting it sink an otherwise complete
+    match.
+    """
+    vocabulary: set[str] = set()
+    for record in load_commands():
+        if record.get("disposition") == "alias":
+            continue
+        command_id = str(record["command_id"])
+        command_path = str(record["command_path"])
+        text = (
+            f"{command_id} {command_path} "
+            f"{_COMMAND_DISCOVERY_PURPOSES.get(command_id, '')} "
+            f"{_GROUP_DISCOVERY_PURPOSES.get(command_path.split()[0], '')}"
+        )
+        vocabulary.update(_tokens(text))
+    return frozenset(vocabulary)
+
+
 def _compact_contract(record: dict[str, Any]) -> dict[str, Any]:
     """Return the bounded, honest contract used by discovery clients.
 
@@ -1405,8 +1485,26 @@ def find_schemas(
     """
     # A query made only of filler words keeps them, rather than matching
     # every command.
-    terms = _query_tokens(query) or tuple(_tokens(query))
-    compound_forms = _adjacent_compound_forms(terms)
+    raw_terms = _query_tokens(query) or tuple(_tokens(query))
+    compound_forms = _adjacent_compound_forms(raw_terms)
+    # A term no command's discovery-purpose text would ever say is a data
+    # word (a column/table/business noun from the caller's own data, not CLI
+    # vocabulary) riding along in the goal; drop it before the all-terms
+    # rule and scoring so it can't sink an otherwise complete match. If
+    # every term would be dropped, keep them all -- a query that is nothing
+    # but data words still deserves its ordinary near-miss treatment rather
+    # than becoming a match-everything wildcard. A literal full-path lookup
+    # (the ``named`` check below) always uses the un-dropped ``raw_terms``,
+    # so naming a command by its exact path never depends on this filter.
+    vocabulary = _command_vocabulary_tokens()
+    cli_terms = tuple(
+        term
+        for term in raw_terms
+        if (_token_aliases(term) & vocabulary)
+        or (compound_forms.get(term, frozenset()) & vocabulary)
+    )
+    terms = cli_terms or raw_terms
+    query_cf = query.casefold()
     # 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.
@@ -1464,6 +1562,12 @@ def find_schemas(
         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
+        new_object = _NEW_OBJECT_HINTS.get(command_id)
+        if new_object and re.search(rf"\bnew\s+{new_object}s?\b", query_cf):
+            score += _OBJECT_ADJACENCY_BOOST
+        existing_object = _EXISTING_OBJECT_HINTS.get(command_id)
+        if existing_object and re.search(rf"\bexisting\s+{existing_object}s?\b", query_cf):
+            score += _OBJECT_ADJACENCY_BOOST
         is_support = command_id.startswith("support.")
         entry = {
             "command_id": command_id,
@@ -1484,7 +1588,7 @@ def find_schemas(
         # A query that spells out this command's whole path (``aggregate view
         # data ...``) asks for it by name, whatever goal words ride along.
         path_tokens = set(_tokens(command_path))
-        named = len(path_tokens) >= 3 and path_tokens <= set(terms)
+        named = len(path_tokens) >= 3 and path_tokens <= set(raw_terms)
         if named:
             score += _NAMED_COMMAND_BOOST
         if named or len(matched_terms) == len(terms):