mammoth-cli 2.0.30__tar.gz → 2.0.32__tar.gz

{mammoth_cli-2.0.30 → mammoth_cli-2.0.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.30
+Version: 2.0.32
 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.13
+Requires-Dist: mammoth-io<0.8,>=0.7.14
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.13
 Requires-Dist: pyyaml<7,>=6
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
 
 Use [Mammoth Analytics](https://mammoth.io) from a terminal. The `mammoth`
 command covers data import and export, transformations, project organization,
-automation, and administration. Its interface is designed to be readable at a
+automation, and administration. Its interface is readable at a
 shell and predictable in scripts and agent runs.
 
 [![PyPI](https://img.shields.io/pypi/v/mammoth-cli)](https://pypi.org/project/mammoth-cli/)
@@ -38,14 +38,14 @@ shell and predictable in scripts and agent runs.
 [![License](https://img.shields.io/pypi/l/mammoth-cli)](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/LICENSE)
 
 - **Human-friendly by default.** In a terminal, commands print a readable table.
-- **Agent-native.** When output is piped, you get a stable JSON envelope with a
+- **Agent-native.** When you pipe the output, you get a stable JSON envelope with a
   documented schema, exit codes, and error codes — no flags required.
 - **Guarded mutations.** Commands expose their confirmation policy; promptless
   destructive operations require an explicit `--yes`.
 - **Discoverable.** `mammoth capability list` and `mammoth schema get` describe
   every command, so an agent can learn the surface at runtime.
 
-The CLI is built on the public [`mammoth-io`](https://pypi.org/project/mammoth-io/)
+The CLI uses the public [`mammoth-io`](https://pypi.org/project/mammoth-io/)
 SDK. It adds no second HTTP client and calls no private SDK members.
 
 See the [capability matrix](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/release-capability-matrix.md)
@@ -103,8 +103,7 @@ history, or command arguments. On POSIX, put the required JSON credentials in a
 private owner-only (0600) file outside the repository and pass its path to:
 
 ```bash
-mammoth auth login --input /private/path/credentials.json --storage file \
- 
+mammoth auth login --input /private/path/credentials.json --storage file
 ```
 
 On Windows, use the approved OS keyring instead; do not use a file fallback
@@ -136,8 +135,7 @@ To pin it for a whole session, `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1`
 the private, permission-checked file described above:
 
 ```bash
-mammoth auth login --input /private/path/credentials.json --storage file \
- 
+mammoth auth login --input /private/path/credentials.json --storage file
 ```
 
 Feed multi-field requests as one document instead of many flags:
@@ -210,9 +208,10 @@ Use Mammoth Analytics only through the `mammoth` CLI in bash; run
 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, print exactly this
-   and wait until I say done: "In the Mammoth web app open account settings,
-   create an API key (key + secret) and note your workspace id, then run in
-   your own terminal: mammoth auth login" — never ask for, read, or pass a key
+   and wait until I say done: "In the Mammoth web app open Workspace settings
+   → API Tokens → Create token, copy the key and the secret (shown once), and
+   note the workspace id (the number after /workspaces/ in the address bar),
+   then run in your own terminal: mammoth auth login" — never ask for, read, or pass a key
    or secret yourself, and never run auth login.
 3. Require `mammoth doctor` to pass, then run `mammoth skill show` and
    follow the guide it prints.

{mammoth_cli-2.0.30 → mammoth_cli-2.0.32}/README.md

@@ -2,7 +2,7 @@
 
 Use [Mammoth Analytics](https://mammoth.io) from a terminal. The `mammoth`
 command covers data import and export, transformations, project organization,
-automation, and administration. Its interface is designed to be readable at a
+automation, and administration. Its interface is readable at a
 shell and predictable in scripts and agent runs.
 
 [![PyPI](https://img.shields.io/pypi/v/mammoth-cli)](https://pypi.org/project/mammoth-cli/)
@@ -10,14 +10,14 @@ shell and predictable in scripts and agent runs.
 [![License](https://img.shields.io/pypi/l/mammoth-cli)](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/LICENSE)
 
 - **Human-friendly by default.** In a terminal, commands print a readable table.
-- **Agent-native.** When output is piped, you get a stable JSON envelope with a
+- **Agent-native.** When you pipe the output, you get a stable JSON envelope with a
   documented schema, exit codes, and error codes — no flags required.
 - **Guarded mutations.** Commands expose their confirmation policy; promptless
   destructive operations require an explicit `--yes`.
 - **Discoverable.** `mammoth capability list` and `mammoth schema get` describe
   every command, so an agent can learn the surface at runtime.
 
-The CLI is built on the public [`mammoth-io`](https://pypi.org/project/mammoth-io/)
+The CLI uses the public [`mammoth-io`](https://pypi.org/project/mammoth-io/)
 SDK. It adds no second HTTP client and calls no private SDK members.
 
 See the [capability matrix](https://github.com/EdgeMetric/mammothsdk/blob/main/mammoth-cli/docs/release-capability-matrix.md)
@@ -75,8 +75,7 @@ history, or command arguments. On POSIX, put the required JSON credentials in a
 private owner-only (0600) file outside the repository and pass its path to:
 
 ```bash
-mammoth auth login --input /private/path/credentials.json --storage file \
- 
+mammoth auth login --input /private/path/credentials.json --storage file
 ```
 
 On Windows, use the approved OS keyring instead; do not use a file fallback
@@ -108,8 +107,7 @@ To pin it for a whole session, `export MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1`
 the private, permission-checked file described above:
 
 ```bash
-mammoth auth login --input /private/path/credentials.json --storage file \
- 
+mammoth auth login --input /private/path/credentials.json --storage file
 ```
 
 Feed multi-field requests as one document instead of many flags:
@@ -182,9 +180,10 @@ Use Mammoth Analytics only through the `mammoth` CLI in bash; run
 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, print exactly this
-   and wait until I say done: "In the Mammoth web app open account settings,
-   create an API key (key + secret) and note your workspace id, then run in
-   your own terminal: mammoth auth login" — never ask for, read, or pass a key
+   and wait until I say done: "In the Mammoth web app open Workspace settings
+   → API Tokens → Create token, copy the key and the secret (shown once), and
+   note the workspace id (the number after /workspaces/ in the address bar),
+   then run in your own terminal: mammoth auth login" — never ask for, read, or pass a key
    or secret yourself, and never run auth login.
 3. Require `mammoth doctor` to pass, then run `mammoth skill show` and
    follow the guide it prints.

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

{mammoth_cli-2.0.30 → mammoth_cli-2.0.32}/mammoth_cli/app.py

@@ -330,6 +330,13 @@ class _LeafGroup(TyperGroup):
 class _EnvelopeGroup(TyperGroup):
     """Root group that renders Click usage errors as the machine error envelope.
 
+    It also materialises top-level command groups lazily (see
+    :func:`_load_top_level_group`): ``list_commands`` and ``get_command`` know
+    every group by name from the manifest, but a group's Click tree is only
+    built when it is invoked, completed or listed in ``--help``. Reading
+    ``commands`` directly materialises them all, so tools that walk the tree
+    still see the full surface.
+
     Click's standalone error handling prints a human ``Usage: ... Error: ...``
     message and exits, even under ``--output json``: an agent driving the CLI
     then receives un-parseable prose (or, for a leaf that also parents
@@ -345,6 +352,28 @@ class _EnvelopeGroup(TyperGroup):
     on.
     """
 
+    @property  # type: ignore[override]
+    def commands(self) -> dict[str, Any]:
+        loaded: dict[str, Any] = self.__dict__.setdefault("_eager_commands", {})
+        for name in _LAZY_GROUP_NAMES:
+            if name not in loaded:
+                loaded[name] = _load_top_level_group(name)
+        return loaded
+
+    @commands.setter
+    def commands(self, value: Any) -> None:
+        self.__dict__["_eager_commands"] = dict(value or {})
+
+    def list_commands(self, ctx: Any) -> list[str]:
+        eager = self.__dict__.get("_eager_commands", {})
+        return [*eager, *(name for name in _LAZY_GROUP_NAMES if name not in eager)]
+
+    def get_command(self, ctx: Any, cmd_name: str) -> Any:
+        eager: dict[str, Any] = self.__dict__.setdefault("_eager_commands", {})
+        if cmd_name not in eager and cmd_name in _LAZY_GROUP_NAMES:
+            eager[cmd_name] = _load_top_level_group(cmd_name)
+        return eager.get(cmd_name)
+
     def main(self, *args: Any, **kwargs: Any) -> Any:
         if not kwargs.get("standalone_mode", True):
             return super().main(*args, **kwargs)
@@ -888,68 +917,55 @@ def _short_type(type_name: str) -> str:
     return " | ".join(part.strip().rsplit(".", 1)[-1] for part in text.split("|"))[:40]
 
 
-def build_app() -> typer.Typer:
-    """Construct the full Typer command tree from the command manifests."""
-    root = typer.Typer(
-        name="mammoth",
-        help=(
-            "Command-line interface for the Mammoth Analytics platform.\n\n"
-            "Start with 'mammoth doctor' to check access, 'mammoth schema find QUERY' "
-            "to locate a command, and 'mammoth schema get COMMAND_ID' for its full input schema."
-        ),
+def _command_records() -> list[dict[str, Any]]:
+    return [r for r in load_commands() if r.get("disposition") != "alias"]
+
+
+@cache
+def _command_tree() -> tuple[dict[tuple[str, ...], str], frozenset[tuple[str, ...]]]:
+    """Map every command path to its id, and name the container nodes.
+
+    A "container command" sits at a node that also has deeper subcommands
+    (e.g. ``dataset file-settings``, which also has ``... undo`` / ``... update``).
+    """
+    path_to_command = {
+        tuple(r["command_path"].split()): r["command_id"] for r in _command_records()
+    }
+    prefixes: set[tuple[str, ...]] = set()
+    for tokens in path_to_command:
+        for depth in range(1, len(tokens)):
+            prefixes.add(tokens[:depth])
+    return path_to_command, frozenset(prefixes & path_to_command.keys())
+
+
+def _group_typer(tokens: tuple[str, ...], command_id: str | None) -> typer.Typer:
+    if command_id is not None:
+        # This node is both a group and an invocable command.
+        sub = typer.Typer(
+            cls=_LeafGroup,
+            no_args_is_help=False,
+            invoke_without_command=True,
+            context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+        )
+        sub.callback()(_build_leaf(command_id, is_group_callback=True))
+        return sub
+    return typer.Typer(
+        help=_GROUP_DESCRIPTIONS.get(tokens[0], f"Commands for {' '.join(tokens)}."),
         no_args_is_help=True,
-        add_completion=True,
-        cls=_EnvelopeGroup,
         context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
     )
 
-    @root.callback()
-    def _root(
-        version: bool = typer.Option(
-            False, "--version", callback=_version_callback, is_eager=True, help="Show version."
-        ),
-    ) -> None:
-        """Root callback holding eager global options."""
 
-    records = [r for r in load_commands() if r.get("disposition") != "alias"]
-    path_to_command: dict[tuple[str, ...], str] = {
-        tuple(r["command_path"].split()): r["command_id"] for r in records
-    }
-    all_paths = set(path_to_command)
-    # A "container command" sits at a node that also has deeper subcommands
-    # (e.g. `dataset file-settings`, which also has `... undo` / `... update`).
-    containers = {
-        tokens
-        for tokens in all_paths
-        if any(other != tokens and other[: len(tokens)] == tokens for other in all_paths)
-    }
-
-    groups: dict[tuple[str, ...], typer.Typer] = {(): root}
-
-    def _make_group(tokens: tuple[str, ...]) -> typer.Typer:
-        command_id = path_to_command.get(tokens)
-        if command_id is not None:
-            # This node is both a group and an invocable command.
-            sub = typer.Typer(
-                cls=_LeafGroup,
-                no_args_is_help=False,
-                invoke_without_command=True,
-                context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
-            )
-            sub.callback()(_build_leaf(command_id, is_group_callback=True))
-        else:
-            sub = typer.Typer(
-                help=_GROUP_DESCRIPTIONS.get(tokens[0], f"Commands for {' '.join(tokens)}."),
-                no_args_is_help=True,
-                context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
-            )
-        return sub
+def _populate(base: tuple[str, ...], group: typer.Typer) -> None:
+    """Register every command below ``base`` (exclusive) on ``group``."""
+    path_to_command, containers = _command_tree()
+    groups: dict[tuple[str, ...], typer.Typer] = {base: group}
 
     def _group_for(tokens: tuple[str, ...]) -> typer.Typer:
         if tokens in groups:
             return groups[tokens]
         parent = _group_for(tokens[:-1])
-        sub = _make_group(tokens)
+        sub = _group_typer(tokens, path_to_command.get(tokens))
         top_level = tokens[0]
         parent.add_typer(
             sub,
@@ -960,15 +976,16 @@ def build_app() -> typer.Typer:
         groups[tokens] = sub
         return sub
 
+    below = {t: c for t, c in path_to_command.items() if t[: len(base)] == base and t != base}
     # Ensure every container group exists (parents before children).
-    for tokens in sorted(containers, key=len):
+    for tokens in sorted((t for t in below if t in containers), key=len):
         _group_for(tokens)
 
     # Register every non-container command as a leaf under its parent group.
     # A command_id with a bespoke, fully-typed callback overrides the generic
     # leaf at the same registered name and path; the manifest-driven surface
     # is otherwise unchanged.
-    for tokens, command_id in sorted(path_to_command.items()):
+    for tokens, command_id in sorted(below.items()):
         if tokens in containers:
             continue
         record = command_by_id(command_id)
@@ -980,11 +997,88 @@ def build_app() -> typer.Typer:
             context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
         )(callback)
 
+
+@cache
+def _top_level_typer(name: str) -> typer.Typer:
+    """Build (once) the Typer sub-app for one top-level command group."""
+    path_to_command, _ = _command_tree()
+    sub = _group_typer((name,), path_to_command.get((name,)))
+    _populate((name,), sub)
+    return sub
+
+
+# Top-level groups are converted to Click on first use. Building the leaf
+# callbacks and ``--help`` text for all ~550 commands, then letting Typer
+# convert every one of them, used to cost most of the CLI's start-up time on
+# every invocation; a run touches one group.
+_LAZY_GROUP_NAMES: list[str] = []
+_LAZY_SETTINGS: dict[str, Any] = {}
+
+
+def _load_top_level_group(name: str) -> Any:
+    from typer.models import TyperInfo
+
+    info = TyperInfo(
+        _top_level_typer(name),
+        name=name,
+        help=_GROUP_DESCRIPTIONS.get(name, f"Commands for {name}."),
+        rich_help_panel=_ROOT_HELP_PANELS.get(name),
+    )
+    return typer.main.get_group_from_info(info, **_LAZY_SETTINGS)
+
+
+def build_app() -> typer.Typer:
+    """Construct the Typer command tree from the command manifests.
+
+    Top-level leaves (``doctor``, ``version``, ...) are registered here; every
+    top-level group is materialised by :class:`_EnvelopeGroup` on demand.
+    """
+    root = typer.Typer(
+        name="mammoth",
+        help=(
+            "Command-line interface for the Mammoth Analytics platform.\n\n"
+            "Start with 'mammoth doctor' to check access, 'mammoth schema find QUERY' "
+            "to locate a command, and 'mammoth schema get COMMAND_ID' for its full input schema."
+        ),
+        no_args_is_help=True,
+        add_completion=True,
+        cls=_EnvelopeGroup,
+        context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+    )
+
+    @root.callback()
+    def _root(
+        version: bool = typer.Option(
+            False, "--version", callback=_version_callback, is_eager=True, help="Show version."
+        ),
+    ) -> None:
+        """Root callback holding eager global options."""
+
+    path_to_command, containers = _command_tree()
+    top_names = sorted({tokens[0] for tokens in path_to_command})
+    lazy: list[str] = []
+    for name in top_names:
+        if (name,) in containers or (name,) not in path_to_command:
+            lazy.append(name)
+            continue
+        command_id = path_to_command[(name,)]
+        root.command(
+            name=name,
+            help=_command_help(command_id, command_by_id(command_id)),
+            rich_help_panel=_ROOT_HELP_PANELS.get(name),
+            context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+        )(BESPOKE.get(command_id) or _build_leaf(command_id))
+    _LAZY_GROUP_NAMES[:] = lazy
+    _LAZY_SETTINGS.update(
+        pretty_exceptions_short=root.pretty_exceptions_short,
+        rich_markup_mode=root.rich_markup_mode,
+        suggest_commands=root.suggest_commands,
+    )
     return root
 
 
 def registered_command_paths() -> set[str]:
-    """Return every registered command path by walking the built Typer tree.
+    """Return every registered command path by walking the built Typer trees.
 
     Container commands (a node that is both a group and invocable) are counted
     by their own path as well as their subcommands.
@@ -998,14 +1092,20 @@ def registered_command_paths() -> set[str]:
                 paths.add(" ".join((*prefix, name)))
         for group in instance.registered_groups:
             sub = group.typer_instance
-            if sub is None or not group.name:
+            name = group.name
+            if sub is None or not name:
                 continue
-            node = (*prefix, group.name)
-            if getattr(sub.info, "invoke_without_command", False) and sub.registered_callback:
+            node = (*prefix, name)
+            if sub.registered_callback is not None:
                 paths.add(" ".join(node))
             walk(sub, node)
 
-    walk(build_app(), ())
+    walk(app, ())
+    for name in _LAZY_GROUP_NAMES:
+        sub = _top_level_typer(name)
+        if sub.registered_callback is not None:
+            paths.add(name)
+        walk(sub, (name,))
     return paths
 
 
@@ -1020,7 +1120,9 @@ def _root_click_command() -> Any:
     the tree is fixed for the process lifetime (:data:`app` is built once at
     import time).
     """
-    return typer.main.get_command(app)
+    root: Any = typer.main.get_command(app)
+    root.commands  # noqa: B018 -- materialise every lazy top-level group
+    return root
 
 
 def command_option_names(command_path: str) -> set[str]:

{mammoth_cli-2.0.30 → mammoth_cli-2.0.32}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.30
+version: 2.0.32
 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."
 ---
 
@@ -8,7 +8,7 @@ description: "Use Mammoth Analytics from a terminal: install or authenticate the
 
 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 never needs a flag to do so when its output is piped.
+envelope, and needs no flag for that when you pipe its output.
 
 ## Start
 
@@ -21,8 +21,9 @@ mammoth project ensure 'PROJECT NAME'   # get-or-create; becomes the active proj
 command anyway. 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 the exact `mammoth auth login --profile PROFILE` command to
-run in their own terminal and wait; never ask for a key or secret in chat,
+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 key and secret come from) and wait; never ask for a key or secret in chat,
 never read one from a file or environment variable, never run `auth login`
 yourself. If any envelope carries `meta.update_available`, run its `command`
 before the next step.
@@ -62,7 +63,8 @@ before the next step.
   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.
-- Destructive commands need `--yes --confirm ID`. Preserve requested
+- 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
   never means delete-all-owned-resources: delete only ids this run created,
   one per call, and read back that they are gone.

{mammoth_cli-2.0.30 → mammoth_cli-2.0.32}/mammoth_cli/bundled_skill/mammoth-cli/references/auth.md

@@ -17,8 +17,12 @@ An agent never receives the key or secret. When `auth status` reports a
 missing profile or `has_credentials=false`, stop and hand the login to the
 human operator:
 
-1. Tell the operator the exact command to run in **their own** terminal. For
-   production it is just:
+1. Tell the operator where the credentials come from: in the Mammoth web app,
+   **Workspace settings → API Tokens → Create token** gives a key and a secret;
+   the web app shows the secret only once (on an existing token, **Generate new
+   secret** replaces it). The workspace id is the number after `/workspaces/`
+   in the web app's address bar. Then give the exact command to run in
+   **their own** terminal. For production it is:
 
    ```bash
    mammoth auth login
@@ -30,6 +34,10 @@ human operator:
    hidden input, then the workspace id, so no secret enters chat, argv, or
    history. Credentials are per environment: a release key never
    authenticates on `app`.
+   On macOS the Keychain may show a dialog about `mammoth-cli`; tell the
+   operator to choose **Always Allow**. If the keychain cannot be used (for
+   example over SSH), login falls back to the owner-only file, or the operator
+   runs `mammoth auth login --storage file`.
 2. Wait for the operator to confirm, then re-run
    `mammoth auth status --profile PROFILE` and
    `mammoth doctor --profile PROFILE`.

{mammoth_cli-2.0.30 → mammoth_cli-2.0.32}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities-misc.md

@@ -33,7 +33,7 @@ Ran once: `automation.create`, `automation.delete`, `automation.list`
 
 | Command | State | Note |
 |---|---|---|
-| `automation.get` | observed blocker | backend_error: SUSPECTED DEFECT: automation.get on the id just returned by automation.create (id=1) returns HTTP 500 empty body every time (3 retries, several seconds apart), not e |
+| `automation.get` | observed blocker | backend_error: SUSPECTED DEFECT: automation.get on the id that automation.create returned (id=1) returns HTTP 500 empty body every time (3 retries, several seconds apart), not even |
 | `automation.update` | observed blocker | cli_error: CLI rejected 'name' field; error message says accepted field is 'patch' (nested patch object), not documented in agent_example |
 
 ## `batch`

{mammoth_cli-2.0.30 → mammoth_cli-2.0.32}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/automation.md

@@ -30,7 +30,7 @@ Example: `mammoth automation get 123`. Placeholders are illustrative; resolve ID
 
 Result: `AutomationGetResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
 
-Status on release: observed blocker — backend_error: SUSPECTED DEFECT: automation.get on the id just returned by automation.create (id=1) returns HTTP 500 empty body every time (3 retries, several seconds apart), not e. Re-check before relying on it.
+Status on release: observed blocker — backend_error: SUSPECTED DEFECT: automation.get on the id that automation.create returned (id=1) returns HTTP 500 empty body every time (3 retries, several seconds apart), not even. Re-check before relying on it.
 
 ### `automation.list`
 

{mammoth_cli-2.0.30 → mammoth_cli-2.0.32}/mammoth_cli/bundled_skill/mammoth-cli/references/handoff.md

@@ -11,15 +11,18 @@ operator logs in from their own terminal as described in [auth](auth.md).
 
 ## Required record
 
-Include `format: "mammoth-agent-handoff"`, `format_version`, producer
-`cli_version`, `sdk_version`, `contract_schema_version`, and `skill_version`
-(the `version:` field in this skill's `SKILL.md` frontmatter; `mammoth
---version` gives the other two);
-the intent and acceptance criteria; authorized `profile` name and exact
-workspace/project scope; observed resources with dataset/view parents and
-dependencies; last verified state and hashes of bounded secret-free evidence;
-pending known jobs and `unknown_outcomes`; completed actions; remaining
-objectives; and a cleanup owner plus dependency order.
+Include `format: "mammoth-agent-handoff"`, `format_version`, and the producer
+versions: `cli_version`, `sdk_version`, `contract_schema_version`, and
+`skill_version`. `skill_version` is the `version:` field in this skill's
+`SKILL.md` frontmatter; `mammoth --version` gives the other two. Also include
+the intent and acceptance criteria and the authorized `profile` name and exact
+workspace/project scope. Then add:
+
+- observed resources with dataset/view parents and dependencies;
+- the last verified state and hashes of bounded secret-free evidence;
+- pending known jobs and `unknown_outcomes`;
+- completed actions and remaining objectives;
+- a cleanup owner plus dependency order.
 
 Never include API keys, API secrets, tokens, headers, credentials files, raw
 secret-bearing input, or unredacted response bodies. IDs and display names are

{mammoth_cli-2.0.30 → mammoth_cli-2.0.32}/mammoth_cli/bundled_skill/mammoth-cli/references/jobs-drafts.md

@@ -5,7 +5,11 @@ A command's `wait_policy` (visible via `mammoth schema get`) determines what
 happens with the job, so you do not have to guess:
 
 - `always_wait` and `start_or_wait` commands resolve the job for you and return
-  the final result. You do NOT wait manually.
+  the final result. You do NOT wait manually. A `view transform` success
+  envelope says `"status": "done"` and `"pipeline_state": "ready"`: the
+  pipeline has finished, so do not poll its `future_id`; verify the values
+  with `view data get`. (With SDK ≤ 0.7.13 the same envelope said
+  `"processing"`; it meant the same thing.)
 - Only a `returns_job` command normally needs you to wait on the job id
   explicitly:
   ```bash