mammoth-cli 2.0.26__tar.gz → 2.0.27__tar.gz

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.26
+Version: 2.0.27
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -81,9 +81,9 @@ command. An agent does this by asking the operator to run the login below in
 their own terminal; the CLI never reads credentials from environment variables:
 
 ```bash
-mammoth skill list
-mammoth skill path
-# Read the installed SKILL.md before operating.
+mammoth skill show
+# Read the SKILL.md it prints before operating; `mammoth skill agents-md install`
+# writes a short steering block into AGENTS.md so future sessions start here.
 mammoth auth status
 # Compare the reported endpoint with the intended target before doctor.
 # Use app for production; use release only when explicitly intended.
@@ -214,8 +214,8 @@ Use Mammoth Analytics only through the `mammoth` CLI in bash; run
    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
    or secret yourself, and never run auth login.
-3. Require `mammoth doctor` to pass, then `cat` the SKILL.md at
-   `mammoth skill path` (data.canonical) and follow it.
+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.

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/README.md

@@ -53,9 +53,9 @@ command. An agent does this by asking the operator to run the login below in
 their own terminal; the CLI never reads credentials from environment variables:
 
 ```bash
-mammoth skill list
-mammoth skill path
-# Read the installed SKILL.md before operating.
+mammoth skill show
+# Read the SKILL.md it prints before operating; `mammoth skill agents-md install`
+# writes a short steering block into AGENTS.md so future sessions start here.
 mammoth auth status
 # Compare the reported endpoint with the intended target before doctor.
 # Use app for production; use release only when explicitly intended.
@@ -186,8 +186,8 @@ Use Mammoth Analytics only through the `mammoth` CLI in bash; run
    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
    or secret yourself, and never run auth login.
-3. Require `mammoth doctor` to pass, then `cat` the SKILL.md at
-   `mammoth skill path` (data.canonical) and follow it.
+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.

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

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.26
+version: 2.0.27
 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."
 ---
 
@@ -45,6 +45,9 @@ before the next step.
 
 - Ids are positionals; request fields are one `--input '{...}'` document;
   there are 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.
 - `COMMAND --help` lists the input fields with types; `mammoth schema get
   COMMAND_ID` is the full contract (add `--input '{"full": true}'` for the
   JSON Schema); `schema list` is the family index, `schema list view` one

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities.md

@@ -1,7 +1,7 @@
 # What is proven on release
 
 Generated from `docs/release-capability-matrix.json`; do not edit by hand.
-The CLI publishes 552 commands. 455 of them bind one of the 528 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (every `view transform *` command submits through `view.task.add`). 261 bound commands ran once successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer.
+The CLI publishes 554 commands. 455 of them bind one of the 528 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (every `view transform *` command submits through `view.task.add`). 261 bound commands ran once successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer.
 
 Status meanings:
 

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/mammoth_cli/bundled_skill/mammoth-cli/references/command-index.md

@@ -1,6 +1,6 @@
 # Published CLI command catalog
 
-This generated catalog is a lookup table for every command in the published CLI manifest, currently 552; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
+This generated catalog is a lookup table for every command in the published CLI manifest, currently 554; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
 
 Load only the applicable domain file:
 
@@ -35,7 +35,7 @@ Load only the applicable domain file:
 - [report](commands/report.md) — 1 published commands
 - [schedule](commands/schedule.md) — 5 published commands
 - [schema](commands/schema.md) — 3 published commands
-- [skill](commands/skill.md) — 5 published commands
+- [skill](commands/skill.md) — 7 published commands
 - [snippet](commands/snippet.md) — 8 published commands
 - [support](commands/support.md) — 45 published commands
 - [template](commands/template.md) — 5 published commands

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/skill.md

@@ -2,6 +2,16 @@
 
 Every command returns the standard JSON envelope. On nonzero exit, read the error envelope and its `recovery_commands`; do not guess request fields. "Status on release" is joined from `docs/release-capability-matrix.json`: *ran once* means one bounded live run succeeded on the named CLI release, *untried* means nobody has run it, *not supported* means the backend refuses it. When this file disagrees with [capabilities](../capabilities.md) or a recipe, they win. Envelope shapes: [machine output](../machine-output.md).
 
+### `skill.agents-md.install`
+
+Run: `mammoth skill agents-md install`. Exact input fields: `mammoth schema get skill.agents-md.install`.
+
+Example: `mammoth skill agents-md install`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `SkillAgentsMdInstallResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `skill.install`
 
 Run: `mammoth skill install`. Exact input fields: `mammoth schema get skill.install`.
@@ -32,6 +42,16 @@ Result: `SkillPathResult`; mutation `read`, confirmation `none`, wait policy `no
 
 Status on release: untried; no live run recorded.
 
+### `skill.show`
+
+Run: `mammoth skill show`. Exact input fields: `mammoth schema get skill.show`.
+
+Example: `mammoth skill show`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `SkillShowResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `skill.uninstall`
 
 Run: `mammoth skill uninstall`. Exact input fields: `mammoth schema get skill.uninstall`.

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md

@@ -19,7 +19,7 @@ or secrets in an argument, prompt, transcript, or checkpoint.
    your own initiative. The SDK (`mammoth-io`) comes with the CLI. If a later
    envelope shows `meta.update_available`, run the `command` it names before
    the next task step, then continue on the new version.
-2. Locate the installed guidance with `mammoth skill path` and read `SKILL.md`; open a reference only when the routing
+2. Read the installed guidance with `mammoth skill show` (`--input '{"file": "references/..."}'` prints one reference); open a reference only when the routing
    table sends you there. `references/commands/*.md` are per-command lookups,
    not upfront reading. If a skill install is required for the agent host,
    run `mammoth skill install` and verify ownership

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/mammoth_cli/commands/registry.py

@@ -175,9 +175,11 @@ HANDLERS: dict[str, Handler] = {
     "doctor": doctor_cmd.doctor,
     "completion.show": completion_cmd.completion_show,
     "completion.install": completion_cmd.completion_install,
+    "skill.agents-md.install": skill_cmd.skill_agents_md_install,
     "skill.install": skill_cmd.skill_install,
     "skill.list": skill_cmd.skill_list,
     "skill.path": skill_cmd.skill_path,
+    "skill.show": skill_cmd.skill_show,
     "skill.uninstall": skill_cmd.skill_uninstall,
     "skill.update": skill_cmd.skill_update,
     "capability.list": _capability_list,

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/mammoth_cli/commands/skill.py

@@ -57,3 +57,31 @@ def skill_path(invocation: Invocation) -> HandlerResult:
     """Show the canonical skill path and the computed destination paths."""
     agents, scope, _force = _options(invocation)
     return installer.path(agents, scope), {}
+
+
+def skill_show(invocation: Invocation) -> HandlerResult:
+    """Print the bundled SKILL.md, or one reference file, as text."""
+    from mammoth_cli.errors.envelope import CODE_RESOURCE_NOT_FOUND, EXIT_NOT_FOUND, CliError
+    from mammoth_cli.skills import steering
+
+    document = invocation.load_input() or {}
+    file = document.get("file")
+    try:
+        return steering.show(str(file) if file else None), {}
+    except FileNotFoundError as exc:
+        raise CliError(
+            code=CODE_RESOURCE_NOT_FOUND,
+            message=f"'{exc}' is not a file of the bundled skill.",
+            exit_status=EXIT_NOT_FOUND,
+            hint="Paths are relative to the skill directory, e.g. references/recipes/index.md.",
+            recovery_commands=["mammoth skill path"],
+        ) from exc
+
+
+def skill_agents_md_install(invocation: Invocation) -> HandlerResult:
+    """Write or refresh the <mammoth-cli> steering block in AGENTS.md (or the given path)."""
+    from mammoth_cli.skills import steering
+
+    document = invocation.load_input() or {}
+    path = document.get("path")
+    return steering.install_steering(str(path) if path else None), {}

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/mammoth_cli/services/command_contract.py

@@ -284,6 +284,10 @@ _LOCAL_CONTRACT_FIELDS: dict[str, tuple[FieldSpec, ...]] = {
         FieldSpec("run_id", required=False, annotation=str | None, default=None),
     ),
     "skill.list": (),
+    "skill.show": (FieldSpec("file", required=False, annotation=str | None, default=None),),
+    "skill.agents-md.install": (
+        FieldSpec("path", required=False, annotation=str | None, default=None),
+    ),
     "skill.path": (
         FieldSpec("agents", required=False, annotation=list[str] | None, default=None),
         FieldSpec("scope", required=False, annotation=str, default="user"),
@@ -348,9 +352,11 @@ _LOCAL_COMMANDS = frozenset(
         "schema.find",
         "schema.get",
         "schema.list",
+        "skill.agents-md.install",
         "skill.install",
         "skill.list",
         "skill.path",
+        "skill.show",
         "skill.uninstall",
         "skill.update",
         "upgrade",

mammoth_cli-2.0.27/mammoth_cli/skills/steering.py

@@ -0,0 +1,106 @@
+"""Steering text for agent instruction files, and the bundled-skill reader.
+
+``mammoth skill agents-md install`` writes one ``<mammoth-cli>…</mammoth-cli>``
+block into a repository's ``AGENTS.md`` (or ``CLAUDE.md``); re-running replaces
+the block in place, so upgrading the CLI and reinstalling refreshes stale
+instructions without duplicating them. ``mammoth skill show`` prints the
+bundled ``SKILL.md`` (or one of its reference files) so a cold-start agent
+loads the guide with one command instead of resolving a path and reading it.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from mammoth_cli import __version__
+from mammoth_cli.skills.installer import SKILL_NAME, canonical_skill_dir
+
+BLOCK_OPEN = "<mammoth-cli>"
+BLOCK_CLOSE = "</mammoth-cli>"
+DEFAULT_STEERING_PATH = "AGENTS.md"
+
+#: The steering block, without the tags. Kept short on purpose: it points the
+#: agent at ``mammoth skill show``, which holds the actual guide.
+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
+`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
+credentials, tell the operator the exact `mammoth auth login` command to run
+in their own terminal and wait; never ask for, read, or pass a key or secret.
+Piped output is compact JSON. Take ids only from reads; run `mammoth schema get
+COMMAND_ID` before a command you have not used; destructive commands need
+`--yes --confirm ID`, and only for ids this task created.
+"""
+
+_BLOCK_RE = re.compile(re.escape(BLOCK_OPEN) + r".*?" + re.escape(BLOCK_CLOSE) + r"\n?", re.DOTALL)
+
+
+def steering_block() -> str:
+    """The full block, tags included, as written into the instructions file."""
+    stamp = (
+        f"<!-- written by mammoth-cli {__version__}; "
+        "rerun `mammoth skill agents-md install` to refresh -->"
+    )
+    return f"{BLOCK_OPEN}\n{stamp}\n{STEERING_BODY}{BLOCK_CLOSE}\n"
+
+
+def install_steering(path: str | None = None, cwd: Path | None = None) -> dict[str, object]:
+    """Create or refresh the steering block in ``path`` (default ``AGENTS.md``).
+
+    Returns:
+        ``{"path", "action", "skill_version"}`` where ``action`` is
+        ``created`` (file did not exist), ``replaced`` (an earlier block was
+        updated in place), ``appended`` (file existed without a block) or
+        ``unchanged`` (the block was already current).
+    """
+    base = cwd or Path.cwd()
+    target = Path(path or DEFAULT_STEERING_PATH)
+    if not target.is_absolute():
+        target = base / target
+    block = steering_block()
+    if target.exists():
+        current = target.read_text(encoding="utf-8")
+        if _BLOCK_RE.search(current):
+            updated = _BLOCK_RE.sub(lambda _m: block, current, count=1)
+            action = "unchanged" if updated == current else "replaced"
+        else:
+            separator = "" if current.endswith("\n") or not current else "\n"
+            updated = f"{current}{separator}\n{block}" if current else block
+            action = "appended"
+    else:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        updated = block
+        action = "created"
+    if action != "unchanged":
+        target.write_text(updated, encoding="utf-8")
+    return {"path": str(target), "action": action, "skill_version": __version__}
+
+
+def show(file: str | None = None) -> dict[str, object]:
+    """Return the text of ``SKILL.md`` or of one bundled reference file.
+
+    Args:
+        file: A path relative to the skill directory, such as
+            ``references/recipes/transforms.md``. Defaults to ``SKILL.md``.
+
+    Raises:
+        FileNotFoundError: when ``file`` is not a bundled skill file (paths
+            outside the skill directory are refused the same way).
+    """
+    root = canonical_skill_dir().resolve()
+    relative = file or "SKILL.md"
+    candidate = (root / relative).resolve()
+    if root not in candidate.parents and candidate != root:
+        raise FileNotFoundError(relative)
+    if not candidate.is_file():
+        raise FileNotFoundError(relative)
+    return {
+        "skill": SKILL_NAME,
+        "file": relative,
+        "path": str(candidate),
+        "text": candidate.read_text(encoding="utf-8"),
+    }

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/pyproject.toml

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

{mammoth_cli-2.0.26 → mammoth_cli-2.0.27}/spec/manifests/commands/skill.yaml

@@ -99,6 +99,73 @@ commands:
   undo_test: null
   known_restrictions: null
   reviewed_by: primary
+- command_id: skill.agents-md.install
+  command_path: skill agents-md install
+  disposition: command
+  alias_of: null
+  operation_ids: []
+  positionals: []
+  options: []
+  sdk_symbol: mammoth_cli.skills.steering.install_steering
+  sdk_conversion: Call mammoth_cli.skills.steering.install_steering with validated request fields.
+  request_model: SkillAgentsMdInstallRequest
+  result_model: SkillAgentsMdInstallResult
+  mutation_class: benign_mutation
+  confirmation: none
+  wait_policy: not_async
+  pagination_policy: none
+  acceptance_evidence: live_read_only
+  live_test: null
+  live_exemption_reason: Local agent-skill file.
+  contract_fixture: null
+  required_fixture_guard: null
+  secret_fields: []
+  human_example: mammoth skill agents-md install --help
+  agent_example: mammoth skill agents-md install
+  unit_tests:
+  - UT-SKILL-AGENTS-MD-INSTALL
+  contract_tests:
+  - CT-SKILL-AGENTS-MD-INSTALL-HUMAN
+  - CT-SKILL-AGENTS-MD-INSTALL-JSON
+  - CT-SKILL-AGENTS-MD-INSTALL-ERROR
+  draft_test: null
+  undo_test: null
+  known_restrictions: 'Writes one <mammoth-cli>…</mammoth-cli> block into AGENTS.md in the current directory (--input ''{"path": "CLAUDE.md"}'' for another file); re-running replaces the block in place. Local file write only.'
+  reviewed_by: primary
+- command_id: skill.show
+  command_path: skill show
+  disposition: command
+  alias_of: null
+  operation_ids: []
+  positionals: []
+  options: []
+  sdk_symbol: mammoth_cli.skills.steering.show
+  sdk_conversion: Call mammoth_cli.skills.steering.show with validated request fields.
+  request_model: SkillShowRequest
+  result_model: SkillShowResult
+  mutation_class: read
+  confirmation: none
+  wait_policy: not_async
+  pagination_policy: none
+  acceptance_evidence: live_read_only
+  live_test: null
+  live_exemption_reason: Local agent-skill file.
+  contract_fixture: null
+  required_fixture_guard: null
+  secret_fields: []
+  human_example: mammoth skill show --help
+  agent_example: mammoth skill show
+  unit_tests:
+  - UT-SKILL-SHOW
+  contract_tests:
+  - CT-SKILL-SHOW-HUMAN
+  - CT-SKILL-SHOW-JSON
+  - CT-SKILL-SHOW-ERROR
+  draft_test: null
+  undo_test: null
+  known_restrictions: 'Prints the bundled SKILL.md under data.text; --input ''{"file": "references/recipes/transforms.md"}'' prints one reference file. Read-only, local.'
+  reviewed_by: primary
+
 - command_id: skill.uninstall
   command_path: skill uninstall
   disposition: command