deepcell-cli 0.6.1__tar.gz → 0.6.2__tar.gz

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepcell-cli
-Version: 0.6.1
+Version: 0.6.2
 Summary: Build and revise .deepcell documents from a terminal — the reasoning, the calculations, the document and the deck, with the links between them
 Author-email: DeepCell <hello@deepcell.net>
 License-Expression: MIT
@@ -166,8 +166,8 @@ deepcell defs apply model.deepcell --ops ops.json     # many ops, atomically
 | Document surface | `doc` — outline, blocks, body, links, lint |
 | Deck surface | `deck` — slides, ordering, binding, branding |
 | Change review | `changes list / diff / revert`, `impact` |
-| Version control | `log`, `diff`, `restore` |
-| Sync | `clone`, `status`, `pull`, `push`, `commit`, `merge` |
+| Version control | `log`, `diff`, `restore`, `commit` |
+| Sync (people, not agents) | `clone`, `status`, `pull`, `push`, `merge` |
 | Import / export | `import`, `ingest`, `to-excel`, `to-docx`, `to-pptx`, `to-pdf` |
 | Reasoning | `reasoning`, `reasoning-diff`, `claim`, `assumption` |
 | Delivery | `viewer`, `share create / list / revoke` |
@@ -218,7 +218,9 @@ deepcell push -m "Updated assumptions"   # upload
 deepcell pull                            # fetch cloud changes
 ```
 
-A `.deepcell/` metadata directory tracks the project link and sync state. `push` refuses to clobber cloud changes — it asks you to `pull` first. See `deepcell guide revise/history`.
+A `.deepcell/` metadata directory tracks the project link and sync state. `push` refuses to clobber cloud changes — it asks you to `pull` first. See `deepcell help clone`.
+
+Sync moves *bytes*, not the commands that read them: `query`, `describe --lint`, `cat` and every other read address the project on the server, so inside a clone they answer from the cloud's HEAD and not from the file you just edited. `push` first, then read back. Sync is a human workflow for this reason and is unavailable over MCP.
 
 ## Import & export
 

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/README.md

@@ -134,8 +134,8 @@ deepcell defs apply model.deepcell --ops ops.json     # many ops, atomically
 | Document surface | `doc` — outline, blocks, body, links, lint |
 | Deck surface | `deck` — slides, ordering, binding, branding |
 | Change review | `changes list / diff / revert`, `impact` |
-| Version control | `log`, `diff`, `restore` |
-| Sync | `clone`, `status`, `pull`, `push`, `commit`, `merge` |
+| Version control | `log`, `diff`, `restore`, `commit` |
+| Sync (people, not agents) | `clone`, `status`, `pull`, `push`, `merge` |
 | Import / export | `import`, `ingest`, `to-excel`, `to-docx`, `to-pptx`, `to-pdf` |
 | Reasoning | `reasoning`, `reasoning-diff`, `claim`, `assumption` |
 | Delivery | `viewer`, `share create / list / revoke` |
@@ -186,7 +186,9 @@ deepcell push -m "Updated assumptions"   # upload
 deepcell pull                            # fetch cloud changes
 ```
 
-A `.deepcell/` metadata directory tracks the project link and sync state. `push` refuses to clobber cloud changes — it asks you to `pull` first. See `deepcell guide revise/history`.
+A `.deepcell/` metadata directory tracks the project link and sync state. `push` refuses to clobber cloud changes — it asks you to `pull` first. See `deepcell help clone`.
+
+Sync moves *bytes*, not the commands that read them: `query`, `describe --lint`, `cat` and every other read address the project on the server, so inside a clone they answer from the cloud's HEAD and not from the file you just edited. `push` first, then read back. Sync is a human workflow for this reason and is unavailable over MCP.
 
 ## Import & export
 

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepcell-cli"
-version = "0.6.1"
+version = "0.6.2"
 description = "Build and revise .deepcell documents from a terminal — the reasoning, the calculations, the document and the deck, with the links between them"
 readme = "README.md"
 license = "MIT"

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/__init__.py

@@ -9,4 +9,4 @@ same thing, and a third is stamped into ``docs/cli-surface.json`` by
 reports a version it is not, and skipping the regen lands a red build.
 """
 
-__version__ = "0.6.1"
+__version__ = "0.6.2"

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/capabilities.py

@@ -33,6 +33,7 @@ MCP_ALLOWED_COMMANDS = frozenset(
         "cell-meta",
         "changes",
         "claim",
+        "commit",
         "deck",
         "defs",
         "describe",
@@ -61,13 +62,23 @@ MCP_ALLOWED_COMMANDS = frozenset(
         "rm",
         "rules",
         "share",
-        "variant",
         "viewer",
         "whoami",
+        # `workspace` is the pre-rename spelling of `project` — a hidden alias
+        # of the same Group. Hidden is not unreachable: `_parse_command`
+        # dispatches through Click, which runs a hidden command like any other,
+        # so the alias needs a policy of its own or it is reachable with none
+        # declared. It carries `project`'s policy because it IS `project`.
+        "workspace",
         "write",
     }
 )
 
+#: Allowed spellings that are aliases of another allowed command. They need an
+#: MCP policy (they run) but must NOT reach the tool catalog: documenting a
+#: second spelling of `project` would put back the row the alias is hidden from.
+MCP_ALIAS_COMMANDS = frozenset({"workspace"})
+
 # Reason codes are stable data rendered into help, guide, MCP errors, and the
 # for-agent page.  The detail is for maintainers and structured clients; user
 # prose remains translated at its own surface.
@@ -80,10 +91,6 @@ MCP_BLOCKED_COMMANDS: dict[str, dict[str, str]] = {
         "reason": "local_checkout",
         "detail": "creates and updates a local Git working copy",
     },
-    "commit": {
-        "reason": "local_checkout",
-        "detail": "reads local sync state and commits a working copy",
-    },
     "login": {
         "reason": "interactive_auth",
         "detail": "opens or polls an interactive browser authentication flow",
@@ -132,6 +139,15 @@ MCP_BLOCKED_COMMANDS: dict[str, dict[str, str]] = {
         "reason": "shared_host_install",
         "detail": "would inspect or replace the CLI installed on the MCP host",
     },
+    "variant": {
+        "reason": "local_checkout",
+        "detail": (
+            "branches the whole file set, and only a working copy can use one: "
+            "`checkout` resets a local tree, and no write command takes a "
+            "`--variant`, so a caller with no clone cannot put anything on a "
+            "branch for `diff` or `merge` to act on"
+        ),
+    },
     "verify-email": {
         "reason": "interactive_auth",
         "detail": "prompts for a verification token sent out of band",

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/capability-contract.json

@@ -427,9 +427,9 @@
           "reason": "not_dispatched"
         },
         "mcp": {
-          "available": false,
-          "detail": "reads local sync state and commits a working copy",
-          "reason": "local_checkout"
+          "available": true,
+          "detail": null,
+          "reason": null
         }
       }
     },
@@ -5817,9 +5817,9 @@
           "reason": "not_dispatched"
         },
         "mcp": {
-          "available": true,
-          "detail": null,
-          "reason": null
+          "available": false,
+          "detail": "branches the whole file set, and only a working copy can use one: `checkout` resets a local tree, and no write command takes a `--variant`, so a caller with no clone cannot put anything on a branch for `diff` or `merge` to act on",
+          "reason": "local_checkout"
         }
       }
     },
@@ -5848,9 +5848,9 @@
           "reason": "not_dispatched"
         },
         "mcp": {
-          "available": true,
-          "detail": null,
-          "reason": null
+          "available": false,
+          "detail": "branches the whole file set, and only a working copy can use one: `checkout` resets a local tree, and no write command takes a `--variant`, so a caller with no clone cannot put anything on a branch for `diff` or `merge` to act on",
+          "reason": "local_checkout"
         }
       }
     },
@@ -5879,9 +5879,9 @@
           "reason": "not_dispatched"
         },
         "mcp": {
-          "available": true,
-          "detail": null,
-          "reason": null
+          "available": false,
+          "detail": "branches the whole file set, and only a working copy can use one: `checkout` resets a local tree, and no write command takes a `--variant`, so a caller with no clone cannot put anything on a branch for `diff` or `merge` to act on",
+          "reason": "local_checkout"
         }
       }
     },
@@ -5910,9 +5910,9 @@
           "reason": "not_dispatched"
         },
         "mcp": {
-          "available": true,
-          "detail": null,
-          "reason": null
+          "available": false,
+          "detail": "branches the whole file set, and only a working copy can use one: `checkout` resets a local tree, and no write command takes a `--variant`, so a caller with no clone cannot put anything on a branch for `diff` or `merge` to act on",
+          "reason": "local_checkout"
         }
       }
     },
@@ -5941,9 +5941,9 @@
           "reason": "not_dispatched"
         },
         "mcp": {
-          "available": true,
-          "detail": null,
-          "reason": null
+          "available": false,
+          "detail": "branches the whole file set, and only a working copy can use one: `checkout` resets a local tree, and no write command takes a `--variant`, so a caller with no clone cannot put anything on a branch for `diff` or `merge` to act on",
+          "reason": "local_checkout"
         }
       }
     },

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/commands/help_cmd.py

@@ -257,6 +257,19 @@ def help_cmd(
     if command:
         path = " ".join(command)
         entry = commands.get(path)
+        if entry is None:
+            # A HIDDEN command is absent from the listing on purpose but still
+            # runs, so asking for it by name must answer. `clone` is the case:
+            # `cli/README.md` points a person at `deepcell help clone`, and the
+            # listing it is hidden from is not the same question as the flags it
+            # takes. Only reached on an explicit name — the index, the stage
+            # filters and every generated surface still see the visible set.
+            hidden_entry = build_commands(include_hidden=True).get(path)
+            if hidden_entry is not None:
+                entry = {
+                    **hidden_entry,
+                    "capability": get_command_capability(path),
+                }
         if entry is None:
             # `build_commands()` keys leaf commands only, so a group path misses
             # the table. Asking what is under `defs` is a well-formed question
@@ -267,6 +280,16 @@ def help_cmd(
             children = sorted(
                 name for name in commands if name.startswith(f"{path} ")
             )
+            if not children:
+                # A hidden GROUP is keyed nowhere — `build_commands` keys leaves
+                # — so `deepcell help variant` has to find its children the same
+                # way, in the hidden-inclusive tree.
+                all_commands = build_commands(include_hidden=True)
+                children = sorted(
+                    name for name in all_commands if name.startswith(f"{path} ")
+                )
+                if children:
+                    commands = {**all_commands, **commands}
             if children:
                 if ctx.fmt == "json":
                     output({"group": path, "commands": children}, ctx.fmt)

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/commands/sync.py

@@ -1,6 +1,10 @@
-"""Sync commands: clone, pull, push, status, commit.
+"""Sync commands: clone, pull, push, status.
 
-Git-like sync between a local folder and a cloud DeepCell workspace.
+Git-like sync between a local folder and a cloud DeepCell workspace. Every
+command here genuinely reads or writes a local working copy — that is the
+membership rule, and `commit` failed it: it posts to
+`/workspaces/{slug}/versions/commit` and touches no local file, so it lives in
+`version.py` with the rest of the server-side history commands.
 """
 
 from __future__ import annotations
@@ -742,63 +746,3 @@ def push(ctx: Ctx, message: str) -> None:
             "push again"
         )
         raise click.exceptions.Exit(1)
-
-
-# -- commit (server-side pending) ---------------------------------------------
-
-
-@click.command()
-@click.option("-m", "--message", default=None, help="Commit message.")
-@pass_ctx
-def commit(ctx: Ctx, message: str | None) -> None:
-    """Commit changes staged on the server by something other than you.
-
-    You almost certainly do not need this. `defs`, `edit`, `write` and
-    `reasoning` each commit their own change with their own `-m` — there is no
-    staging area they queue into. This commits what a *different* actor left
-    pending on the server, such as files created by an agent session.
-
-    Nothing staged is a no-op, not an error.
-    """
-    root, state = _require_sync_root(ctx)
-    slug = state.workspace_slug
-
-    # `-m` is no longer `required=True`, so this reaches the server even when
-    # the caller gave no message. The server checks "is anything staged"
-    # first and answers the no-op; a commit that will actually write still
-    # 422s without a message, and that is re-raised below as a usage error.
-    #
-    # It used to be rejected by Click during parsing, so a worker whose defs
-    # ops had each already committed and who reasonably tried to finalize got
-    # "Missing option '-m' / '--message'" — an argument-syntax error for a
-    # command with nothing to do. That is what the 2026-08-02 CLI eval hit.
-    data = ctx.client.post(
-        f"/workspaces/{slug}/versions/commit",
-        json={"message": message or ""},
-    )
-
-    # A commit with nothing staged is a benign no-op (the endpoint answers
-    # 200 with committed=false, sha=null) — report it instead of slicing a
-    # null sha.
-    if isinstance(data, dict) and data.get("committed") is False:
-        echo_info(
-            "Nothing to commit — no pending changes. `defs`, `edit`, `write` "
-            "and `reasoning` each commit their own change, so there is "
-            "normally nothing here to finalize."
-        )
-        return
-
-    sha = (data.get("sha") or "")[:8] if isinstance(data, dict) else ""
-    # Staged content is committed either way (the server persists invalid
-    # .deepcell on purpose), so report the errors rather than letting a clean
-    # "Committed" line stand in for them — parity with write/push.
-    invalid = echo_validation_map(
-        data.get("validation") if isinstance(data, dict) else None
-    )
-    if invalid:
-        echo_warning(
-            f"Committed ({sha}), but {len(invalid)} file(s) have validation "
-            f"error(s): {', '.join(invalid)} — fix the errors above"
-        )
-        raise click.exceptions.Exit(1)
-    echo_success(f"Committed ({sha}): {message}")

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/commands/version.py

@@ -1,4 +1,4 @@
-"""Version control commands: log, diff, restore."""
+"""Version control commands: log, diff, restore, commit."""
 
 from __future__ import annotations
 
@@ -7,7 +7,8 @@ import click
 from deepcell_cli.errors import APIError
 from deepcell_cli.context import Ctx, pass_ctx
 from deepcell_cli.output import (
-    echo_error, echo_info, echo_success, echo_warning, output, output_mutation, print_plain,
+    echo_error, echo_info, echo_success, echo_validation_map, echo_warning,
+    output, output_mutation, print_plain,
 )
 
 
@@ -443,3 +444,73 @@ def restore(ctx: Ctx, revision: str, filename: str | None, yes: bool) -> None:
             "Recover them from a newer revision (`deepcell log`, then "
             "`deepcell download <file> --revision <sha>`)."
         )
+
+
+# -- commit (finalize what another actor staged server-side) -------------------
+
+
+@click.command()
+@click.option("-m", "--message", default=None, help="Commit message.")
+@pass_ctx
+def commit(ctx: Ctx, message: str | None) -> None:
+    """Commit changes staged on the server by something other than you.
+
+    You almost certainly do not need this. `defs`, `edit`, `write` and
+    `reasoning` each commit their own change with their own `-m` — there is no
+    staging area they queue into. This commits what a *different* actor left
+    pending on the server, such as files created by an agent session.
+
+    Nothing staged is a no-op, not an error.
+    """
+    # Addressed by workspace, like everything else in this module. It used to
+    # live in `sync.py` and call `_require_sync_root`, which reads
+    # `.deepcell/sync.json` — for nothing but the slug, because the work is
+    # entirely server-side: `POST /workspaces/{slug}/versions/commit` stages
+    # nothing locally and reads no local file.
+    #
+    # That invented clone requirement cost the command the callers it exists
+    # for. It raised "Not inside a synced workspace" for anyone standing
+    # anywhere else, and it was blocked over MCP as `local_checkout` — a reason
+    # untrue of it. An agent, which is precisely who leaves changes staged,
+    # could not finalize them from any transport.
+    slug = ctx.require_workspace()
+
+    # `-m` is no longer `required=True`, so this reaches the server even when
+    # the caller gave no message. The server checks "is anything staged"
+    # first and answers the no-op; a commit that will actually write still
+    # 422s without a message, and that is re-raised below as a usage error.
+    #
+    # It used to be rejected by Click during parsing, so a worker whose defs
+    # ops had each already committed and who reasonably tried to finalize got
+    # "Missing option '-m' / '--message'" — an argument-syntax error for a
+    # command with nothing to do. That is what the 2026-08-02 CLI eval hit.
+    data = ctx.client.post(
+        f"/workspaces/{slug}/versions/commit",
+        json={"message": message or ""},
+    )
+
+    # A commit with nothing staged is a benign no-op (the endpoint answers
+    # 200 with committed=false, sha=null) — report it instead of slicing a
+    # null sha.
+    if isinstance(data, dict) and data.get("committed") is False:
+        echo_info(
+            "Nothing to commit — no pending changes. `defs`, `edit`, `write` "
+            "and `reasoning` each commit their own change, so there is "
+            "normally nothing here to finalize."
+        )
+        return
+
+    sha = (data.get("sha") or "")[:8] if isinstance(data, dict) else ""
+    # Staged content is committed either way (the server persists invalid
+    # .deepcell on purpose), so report the errors rather than letting a clean
+    # "Committed" line stand in for them — parity with write/push.
+    invalid = echo_validation_map(
+        data.get("validation") if isinstance(data, dict) else None
+    )
+    if invalid:
+        echo_warning(
+            f"Committed ({sha}), but {len(invalid)} file(s) have validation "
+            f"error(s): {', '.join(invalid)} — fix the errors above"
+        )
+        raise click.exceptions.Exit(1)
+    echo_success(f"Committed ({sha}): {message}")

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/main.py

@@ -442,11 +442,11 @@ from deepcell_cli.commands.impact import impact  # noqa: E402
 from deepcell_cli.commands.export_docx import to_docx  # noqa: E402
 from deepcell_cli.commands.export_pdf import to_pdf  # noqa: E402
 from deepcell_cli.commands.export_pptx import to_pptx  # noqa: E402
-from deepcell_cli.commands.version import log, diff, restore  # noqa: E402
+from deepcell_cli.commands.version import log, diff, restore, commit  # noqa: E402
 from deepcell_cli.commands.changes import changes  # noqa: E402
 from deepcell_cli.commands.variant import variant  # noqa: E402
 from deepcell_cli.commands.grep import grep  # noqa: E402
-from deepcell_cli.commands.sync import clone, pull, push, sync_status, commit  # noqa: E402
+from deepcell_cli.commands.sync import clone, pull, push, sync_status  # noqa: E402
 from deepcell_cli.commands.merge import merge  # noqa: E402
 from deepcell_cli.commands.import_cmd import import_cmd  # noqa: E402
 from deepcell_cli.commands.ingest import ingest  # noqa: E402
@@ -499,13 +499,34 @@ cli.add_command(log)
 cli.add_command(diff)
 cli.add_command(restore)
 cli.add_command(changes)
-cli.add_command(variant)
 cli.add_command(grep)
+cli.add_command(commit)
+
+# Local sync and variants: registered, working, and HIDDEN. Both are a person's
+# workflow at a terminal with a clone, and neither is discoverable any more —
+# `surface.py`, `main`'s own help and `docs/cli-commands.md`'s coverage test all
+# skip hidden commands, so they produce no help row and no entry in any
+# generated surface. Muscle memory and existing scripts keep working, and
+# `deepcell help <name>` still answers for each.
+#
+# Sync moves BYTES while every read addresses the project on the server, so a
+# clone is a working copy the read path cannot see. Variants branch the whole
+# file set, and no write command takes a variant, so a branch is only reachable
+# by checking it out onto disk. Both are therefore clone-shaped all the way
+# down, which is precisely what the agent surfaces do not have.
+#
+# The cost is deliberate and was weighed: the `variants` and `merge` domains
+# leave `docs/backend-cli-semantic-contracts.yaml`, because a hidden command is
+# absent from the capability contract the domain resolves through. Those two
+# backend domains now have no taught CLI command.
+for _person_only in (variant, clone, pull, push, sync_status, merge):
+    _person_only.hidden = True
+
+cli.add_command(variant)
 cli.add_command(clone)
 cli.add_command(pull)
 cli.add_command(push)
 cli.add_command(sync_status, "status")
-cli.add_command(commit)
 cli.add_command(merge)
 cli.add_command(import_cmd, "import")
 cli.add_command(ingest)

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/mcp_server.py

@@ -24,6 +24,7 @@ from click.testing import CliRunner
 from mcp.server.fastmcp import FastMCP
 
 from deepcell_cli.capabilities import (
+    MCP_ALIAS_COMMANDS,
     MCP_ALLOWED_COMMANDS,
     MCP_BLOCKED_COMMANDS as MCP_BLOCK_POLICY,
     blocked_mcp_commands,
@@ -48,7 +49,7 @@ AUTO_CONFIRM: dict[str, list[str]] = {
 # Top-level commands documented in TOOL_DESCRIPTION. Must stay equal to the
 # registered Click commands minus BLOCKED_COMMANDS — tests/test_mcp_server.py
 # cross-checks both directions so the catalog can't silently drift.
-DOCUMENTED_COMMANDS = frozenset(MCP_ALLOWED_COMMANDS)
+DOCUMENTED_COMMANDS = frozenset(MCP_ALLOWED_COMMANDS) - MCP_ALIAS_COMMANDS
 
 TOOL_DESCRIPTION = """\
 Run a DeepCell CLI command. Structured results are JSON; `cat` prints raw XML
@@ -136,9 +137,6 @@ Available commands:
     replace <file> <old> <new>
                                 String-replace in XML (last resort — prefer defs;
                                 `edit --replace` is a deprecated alias)
-    variant list                List variants
-    variant create <name>       Create a variant
-                                (Note: variant checkout/diff/merge need a LOCAL clone — blocked here)
     rm <file>                   Delete a file (auto-confirmed)
     log [--file F] [-n N]       Show version history
     diff <rev_a> [rev_b]        Diff between revisions
@@ -147,6 +145,9 @@ Available commands:
     changes diff <base> [head]  What one change did, semantically
     changes revert <base> <head>
                                 Undo one change as a new commit (auto-confirmed)
+    commit [-m MSG]             Finalize changes another actor left staged
+                                (Rare: every writer commits its own change.
+                                Nothing staged is a no-op, not an error.)
 
   VERIFY — change one thing, see everything it affects
     relationships <file>        Show relationship graph
@@ -182,7 +183,8 @@ Available commands:
 
   SYNC — local <-> cloud
     download <file> -o <path>   Download file to local path
-                                (the rest of sync is blocked here — see below)
+                                (Sync proper is blocked here — it needs a clone.
+                                Note `commit` is NOT sync: see REVISE.)
 
   LEARN — the five reference surfaces
     help [command]              Every command, flag, exit code and example.

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/stages.py

@@ -99,6 +99,10 @@ COMMAND_TIER: dict[str, str] = {
     "log": "revise",
     "diff": "revise",
     "restore": "revise",
+    # Filed under SYNC until it was read closely: it posts to
+    # `/workspaces/{slug}/versions/commit` and touches no local working copy,
+    # so it belongs with the other history commands, not with `clone`/`push`.
+    "commit": "revise",
     "rm": "revise",
     # VERIFY — the connectedness story: change one thing, see what it affects.
     "relationships": "verify",
@@ -132,7 +136,6 @@ COMMAND_TIER: dict[str, str] = {
     "status": "sync",
     "pull": "sync",
     "push": "sync",
-    "commit": "sync",
     "merge": "sync",
     "download": "sync",
     # LEARN — the five reference surfaces.

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/surface.py

@@ -502,7 +502,12 @@ def _describe_command(path: str, command: click.Command) -> dict[str, Any]:
     }
 
 
-def _walk(command: click.Command, path: str, out: dict[str, dict[str, Any]]) -> None:
+def _walk(
+    command: click.Command,
+    path: str,
+    out: dict[str, dict[str, Any]],
+    include_hidden: bool = False,
+) -> None:
     if isinstance(command, click.Group):
         # An `invoke_without_command=True` group is a command *as well as* a
         # group: `deepcell example --pack finance` runs, and the `--pack` is
@@ -515,13 +520,13 @@ def _walk(command: click.Command, path: str, out: dict[str, dict[str, Any]]) ->
         ctx = click.Context(command)
         for name in command.list_commands(ctx):
             sub = command.get_command(ctx, name)
-            if sub is not None and not sub.hidden:
-                _walk(sub, f"{path} {name}".strip(), out)
+            if sub is not None and (include_hidden or not sub.hidden):
+                _walk(sub, f"{path} {name}".strip(), out, include_hidden)
         return
     out[path] = _describe_command(path, command)
 
 
-def build_commands() -> dict[str, dict[str, Any]]:
+def build_commands(include_hidden: bool = False) -> dict[str, dict[str, Any]]:
     """Every invocable command, keyed by its full invocation path.
 
     Groups are walked rather than listed: ``defs`` is not a command, ``defs
@@ -534,6 +539,12 @@ def build_commands() -> dict[str, dict[str, Any]]:
     its own. ``test_surface_group_options`` fails on that shape rather than
     letting the option vanish the way ``example --pack`` did — the fix is to
     move the option onto the leaves, or make the group invocable.
+
+    ``include_hidden`` is for lookup by name only, never for codegen: a hidden
+    command is deliberately absent from every generated surface, but it still
+    runs, so ``deepcell help <name>`` must still answer for it. Hidden from the
+    index, answerable when asked for — the alternative is a command a person
+    can invoke and cannot read the flags of.
     """
     from deepcell_cli.main import cli
 
@@ -541,8 +552,8 @@ def build_commands() -> dict[str, dict[str, Any]]:
     ctx = click.Context(cli)
     for name in cli.list_commands(ctx):
         sub = cli.get_command(ctx, name)
-        if sub is not None and not sub.hidden:
-            _walk(sub, name, out)
+        if sub is not None and (include_hidden or not sub.hidden):
+            _walk(sub, name, out, include_hidden)
     return dict(sorted(out.items()))
 
 

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli/upgrade_check.py

@@ -95,7 +95,7 @@ class Index(NamedTuple):
 # first-answer-wins would then quietly stop noticing releases whenever the
 # earlier index lagged the later one. Nothing would fail; the check would just
 # say nothing forever, which is the failure mode this whole module is built to
-# avoid. (It is also what the TestPyPI era needed, when production PyPI 404'd.)
+# avoid.
 DEFAULT_INDEXES = (
     Index(
         f"https://pypi.org/pypi/{PACKAGE_NAME}/json",

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/src/deepcell_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepcell-cli
-Version: 0.6.1
+Version: 0.6.2
 Summary: Build and revise .deepcell documents from a terminal — the reasoning, the calculations, the document and the deck, with the links between them
 Author-email: DeepCell <hello@deepcell.net>
 License-Expression: MIT
@@ -166,8 +166,8 @@ deepcell defs apply model.deepcell --ops ops.json     # many ops, atomically
 | Document surface | `doc` — outline, blocks, body, links, lint |
 | Deck surface | `deck` — slides, ordering, binding, branding |
 | Change review | `changes list / diff / revert`, `impact` |
-| Version control | `log`, `diff`, `restore` |
-| Sync | `clone`, `status`, `pull`, `push`, `commit`, `merge` |
+| Version control | `log`, `diff`, `restore`, `commit` |
+| Sync (people, not agents) | `clone`, `status`, `pull`, `push`, `merge` |
 | Import / export | `import`, `ingest`, `to-excel`, `to-docx`, `to-pptx`, `to-pdf` |
 | Reasoning | `reasoning`, `reasoning-diff`, `claim`, `assumption` |
 | Delivery | `viewer`, `share create / list / revoke` |
@@ -218,7 +218,9 @@ deepcell push -m "Updated assumptions"   # upload
 deepcell pull                            # fetch cloud changes
 ```
 
-A `.deepcell/` metadata directory tracks the project link and sync state. `push` refuses to clobber cloud changes — it asks you to `pull` first. See `deepcell guide revise/history`.
+A `.deepcell/` metadata directory tracks the project link and sync state. `push` refuses to clobber cloud changes — it asks you to `pull` first. See `deepcell help clone`.
+
+Sync moves *bytes*, not the commands that read them: `query`, `describe --lint`, `cat` and every other read address the project on the server, so inside a clone they answer from the cloud's HEAD and not from the file you just edited. `push` first, then read back. Sync is a human workflow for this reason and is unavailable over MCP.
 
 ## Import & export
 

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/tests/test_mcp_server.py

@@ -63,11 +63,40 @@ class TestParseCommand:
         with pytest.raises(ValueError, match="verify-email.*blocked"):
             _parse_command("verify-email")
 
-    @pytest.mark.parametrize("cmd", ["clone", "status", "pull", "push", "commit", "merge"])
+    @pytest.mark.parametrize("cmd", ["clone", "status", "pull", "push", "merge"])
     def test_blocked_sync_commands(self, cmd):
         with pytest.raises(ValueError, match=f"{cmd}.*blocked"):
             _parse_command(cmd)
 
+    def test_variant_is_blocked(self):
+        """A branch you cannot write to is not a capability, it is a trap.
+
+        `variant checkout` resets a local working tree the MCP caller does not
+        have, and `variant diff` / `variant merge` resolve their workspace out
+        of `.deepcell/sync.json` — so the family refused itself here anyway,
+        with "Not inside a synced workspace" instead of a capability answer.
+        The deeper reason it stays blocked rather than being made to work: no
+        write command takes a variant, so an agent cannot put anything ON a
+        branch it creates, leaving `diff` and `merge` nothing to act on.
+        Scenarios are the in-place answer (`guide revise/scenarios`).
+        """
+        with pytest.raises(ValueError, match="variant.*blocked"):
+            _parse_command("variant create bear-case")
+        with pytest.raises(ValueError, match="variant.*blocked"):
+            _parse_command("variant list")
+        assert "variant" not in DOCUMENTED_COMMANDS
+
+    def test_commit_is_not_a_sync_command(self):
+        """`commit` sat in this list for its module, not its behaviour.
+
+        It posts to `/workspaces/{slug}/versions/commit` and reads no local
+        file, so `local_checkout` was never true of it. Blocking it kept the
+        one caller who needs it — an agent finalizing what it left staged —
+        from reaching it on any transport.
+        """
+        assert "commit" not in BLOCKED_COMMANDS
+        assert "commit" in _parse_command("commit -m 'finalize'")
+
     def test_auto_confirm_rm(self):
         result = _parse_command("rm model.deepcell")
         assert "-y" in result
@@ -275,7 +304,7 @@ class TestDeepcellToolOutput:
         # Blocked commands are refused with a clear, non-silent error (not run).
         for cmd in (
             "login", "logout", "register", "verify-email", "to-excel",
-            "clone", "status", "pull", "push", "commit", "merge",
+            "clone", "status", "pull", "push", "merge",
         ):
             out = deepcell(cmd)
             # The failure MARKER must lead: `guide exit-codes` tells agents to

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/tests/test_stages.py

@@ -113,12 +113,26 @@ def _lead_commands(bullet: str) -> list[str]:
 
 
 def _top_level() -> list[str]:
+    """Every registered top-level command, HIDDEN ONES INCLUDED.
+
+    Both questions below are about existence, not about the help index.
+    `clone`, `pull`, `push`, `status`, `merge` and `variant` are `hidden=True`
+    — retired from discovery, still registered and still runnable — so reading
+    them as "no longer exist" would delete their stage entries and, the next
+    time one is un-hidden, land it in a bucket `assert_fully_staged` exists to
+    forbid. A hidden command keeps its stage for the same reason it keeps its
+    MCP policy: it still runs.
+
+    An ALIAS is still excluded, and that is a different case: `workspace` is
+    the pre-rename spelling of `project`, the same Group under a second name.
+    It has no stage and no catalog row of its own because it is not a second
+    command — staging it would put a duplicate of every `project` row back into
+    the help index the alias exists to stay out of.
+    """
+    from deepcell_cli.capabilities import MCP_ALIAS_COMMANDS
+
     ctx = click.Context(cli)
-    return [
-        name
-        for name in cli.list_commands(ctx)
-        if not (cli.get_command(ctx, name) or click.Command(name)).hidden
-    ]
+    return [n for n in cli.list_commands(ctx) if n not in MCP_ALIAS_COMMANDS]
 
 
 def test_every_command_has_a_stage():
@@ -360,7 +374,12 @@ def test_the_docs_lead_list_reader_actually_reads_commands():
         for b in bullets
         for n in _lead_commands(b)
     }
-    assert {"query", "defs", "deck", "changes", "clone"} <= found, sorted(found)
+    # One sentinel per section, so a reader that went blind in any single one
+    # is caught. `download` heads SYNC's only bullet since `clone` and the rest
+    # of the sync family became hidden commands, which are named in the
+    # preamble's prose rather than in a stage-headed list — and prose is
+    # exactly what this reader is built NOT to read.
+    assert {"query", "defs", "deck", "changes", "download"} <= found, sorted(found)
 
 
 def test_the_lead_list_reader_stops_where_the_grouping_claim_stops():

{deepcell_cli-0.6.1 → deepcell_cli-0.6.2}/tests/test_upgrade_check.py

@@ -25,12 +25,12 @@ from deepcell_cli.main import cli
 
 PYPI = upgrade_check.DEFAULT_INDEXES[0].json_url
 
-# Two stand-ins for the multi-index tests below. `DEFAULT_INDEXES` names one
-# index (production PyPI) now that the package no longer ships to TestPyPI, but
-# `fetch_latest` still asks every index and takes the highest — the tuple is the
-# seam a mirror or a pre-release channel gets added at. Patching the module
-# global is what keeps that loop covered without inventing a second real index;
-# it is a plain attribute, so monkeypatch restores it cleanly.
+# Two stand-ins for the multi-index tests below. `DEFAULT_INDEXES` names a
+# single index, production PyPI, but `fetch_latest` still asks every index and
+# takes the highest — the tuple is the seam a mirror or a pre-release channel
+# gets added at. Patching the module global is what keeps that loop covered
+# without inventing a second real index; it is a plain attribute, so
+# monkeypatch restores it cleanly.
 MIRROR_A = "https://mirror-a.test/pypi/deepcell-cli/json"
 MIRROR_B = "https://mirror-b.test/pypi/deepcell-cli/json"
 _INSTALL_A = "pip install --upgrade --index-url https://mirror-a.test/simple/ deepcell-cli"
@@ -184,10 +184,10 @@ def _index_payload(version: str) -> dict:
 class TestFetchLatest:
     def test_the_default_index_is_production_pypi(self) -> None:
         # The package ships to production PyPI, which carries its dependencies
-        # too — so the notice's install line takes no --index-url and no
-        # --extra-index-url. Both were mandatory in the TestPyPI era, and a
-        # notice that prints them again sends the reader to an index this
-        # project no longer publishes to.
+        # too, so the notice's install line takes no --index-url and no
+        # --extra-index-url. A notice that pins an index sends the reader
+        # somewhere this project does not publish, and every later release is
+        # then invisible to them.
         assert len(upgrade_check.DEFAULT_INDEXES) == 1
         (index,) = upgrade_check.DEFAULT_INDEXES
         assert index.json_url == "https://pypi.org/pypi/deepcell-cli/json"