deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/__init__.py

@@ -0,0 +1,12 @@
+"""DeepCell CLI — command-line interface for the DeepCell platform.
+
+``__version__`` is the *runtime* version — what `--version` prints, what the
+client header sends, and what the upgrade check compares against PyPI. The
+packaging version in ``cli/pyproject.toml`` is a second copy that must say the
+same thing, and a third is stamped into ``docs/cli-surface.json`` by
+``scripts/gen_cli_surface.py``. All three are pinned together by
+``cli/tests/test_version_parity.py`` — bumping one alone ships a build that
+reports a version it is not, and skipping the regen lands a red build.
+"""
+
+__version__ = "0.6.1"

deepcell_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as ``python -m deepcell_cli``."""
+
+from deepcell_cli.main import cli
+
+cli()

deepcell_cli/_findings.py

@@ -0,0 +1,84 @@
+"""Shared rendering for lint findings that cite a house rule.
+
+The highest-leverage place to put a cross-reference is the failure site: the
+agent is already there and already paying attention, so a rule id printed
+beside the finding costs zero navigation. This module is the one place that
+decides how that citation looks, so the three CLI surfaces that render
+findings — ``describe --lint``, ``reasoning lint``, and the post-write findings
+from ``reasoning add-*`` — cannot drift into three notations.
+
+Findings carry ``house_rule`` (e.g. ``"R8"``) only when their lint code
+enforces one. Most codes are structural checks no house rule claims, so an
+unstamped finding is normal and renders exactly as it did before.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+
+def rule_citation(finding: dict[str, Any]) -> str:
+    """Return ``" rule:R2"`` for a stamped finding, or ``""`` for the rest.
+
+    Includes its own leading space so callers can append unconditionally
+    without emitting a trailing space when there is no rule.
+    """
+    rule_id = finding.get("house_rule")
+    return f" rule:{rule_id}" if rule_id else ""
+
+
+def provenance(finding: dict[str, Any]) -> str:
+    """Return ``" (pre-existing)"`` / ``" (new)"``, or ``""`` when unknown.
+
+    A finding on its own does not say whether the change that surfaced it is
+    what caused it, and a caller who cannot tell reads every finding as damage
+    they just did. The 2026-08-02 CLI eval has the shape on tape: a worker
+    fixed one warning, the response came back carrying an `orphan_claim` that
+    had been true all along, and it spent four commands chasing a problem its
+    edit had not introduced.
+
+    Both states are labelled rather than only the surprising one. Marking just
+    the pre-existing ones would leave an unlabelled finding ambiguous between
+    "new" and "this surface does not know", which is the ambiguity the stamp
+    exists to remove. Surfaces with no baseline to compare against (the
+    read-only `reasoning lint`) send no stamp and render exactly as before.
+    """
+    pre_existing = finding.get("pre_existing")
+    if pre_existing is None:
+        return ""
+    return " (pre-existing)" if pre_existing else " (new)"
+
+
+def cited_rules_footer(findings: Iterable[dict[str, Any]]) -> str | None:
+    """Return one line telling the reader how to read the rules just cited.
+
+    One footer rather than a pointer per finding: a forty-finding lint would
+    otherwise repeat the same instruction forty times, which trains the reader
+    to skip it. ``None`` when there is nothing to point at.
+
+    Two lines at most — the house rules cited, and how to explain a lint code.
+    The second is capped at three codes because the footer is an affordance,
+    not a second copy of the findings list.
+    """
+    seen: list[str] = []
+    codes: list[str] = []
+    for finding in findings:
+        rule_id = finding.get("house_rule")
+        if rule_id and rule_id not in seen:
+            seen.append(rule_id)
+        code = finding.get("rule")
+        if code and code not in codes:
+            codes.append(code)
+
+    parts: list[str] = []
+    if seen:
+        parts.append("Cited rules: " + " · ".join(f"deepcell rules {r}" for r in seen))
+    # Every finding has a code, and `deepcell ref lint/<code>` explains what it
+    # flags and the fix — so this line is useful even when no house rule was
+    # cited, which is the majority case.
+    if codes:
+        parts.append(
+            "Explain a code: " + " · ".join(f"deepcell ref lint/{c}" for c in codes[:3])
+            + (" …" if len(codes) > 3 else "")
+        )
+    return "\n".join(parts) if parts else None

deepcell_cli/capabilities.py

@@ -0,0 +1,560 @@
+"""Authoritative cross-surface capability policy.
+
+The Click tree owns command syntax and ``backend/openapi.json`` owns Jingwei
+methods, paths, and schemas.  This module owns the facts neither source can
+express by itself: which operations a CLI command reaches, which transports
+can run a command, and why an operation deliberately has no CLI route.
+
+``scripts/gen_cli_surface.py`` expands this policy against both authorities and
+writes the resulting contract into every runtime that needs it.  Keep entries
+keyed by OpenAPI ``operationId`` rather than copying paths or request schemas;
+codegen fails when an id disappears, a new operation is unclassified, or a
+command pattern matches nothing.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Transport policy
+# ---------------------------------------------------------------------------
+
+# Every top-level Click command is listed exactly once across these two
+# collections.  Default-allow would make a newly added destructive command
+# remotely callable until somebody happened to audit it.
+MCP_ALLOWED_COMMANDS = frozenset(
+    {
+        "assumption",
+        "cat",
+        "cell-meta",
+        "changes",
+        "claim",
+        "deck",
+        "defs",
+        "describe",
+        "diff",
+        "doc",
+        "doctor",
+        "download",
+        "edit",
+        "example",
+        "grep",
+        "guide",
+        "help",
+        "impact",
+        "import",
+        "ingest",
+        "log",
+        "ls",
+        "project",
+        "query",
+        "reasoning",
+        "reasoning-diff",
+        "ref",
+        "relationships",
+        "replace",
+        "restore",
+        "rm",
+        "rules",
+        "share",
+        "variant",
+        "viewer",
+        "whoami",
+        "write",
+    }
+)
+
+# 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.
+MCP_BLOCKED_COMMANDS: dict[str, dict[str, str]] = {
+    "account": {
+        "reason": "identity_destructive",
+        "detail": "exports or irreversibly deletes the caller's account",
+    },
+    "clone": {
+        "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",
+    },
+    "logout": {
+        "reason": "shared_credentials",
+        "detail": "mutates process-global CLI credentials on the MCP host",
+    },
+    "merge": {
+        "reason": "local_checkout",
+        "detail": "reads and mutates local sync and conflict state",
+    },
+    "pull": {
+        "reason": "local_checkout",
+        "detail": "updates files in a local Git working copy",
+    },
+    "push": {
+        "reason": "local_checkout",
+        "detail": "reads and uploads files from a local Git working copy",
+    },
+    "register": {
+        "reason": "interactive_auth",
+        "detail": "creates identity-bearing credentials through prompts",
+    },
+    "status": {
+        "reason": "local_checkout",
+        "detail": "compares the remote workspace with local sync state",
+    },
+    "to-docx": {
+        "reason": "binary_download",
+        "detail": "writes a binary export to the MCP server's filesystem",
+    },
+    "to-excel": {
+        "reason": "binary_download",
+        "detail": "writes a binary export to the MCP server's filesystem",
+    },
+    "to-pdf": {
+        "reason": "binary_download",
+        "detail": "writes a binary export to the MCP server's filesystem",
+    },
+    "to-pptx": {
+        "reason": "binary_download",
+        "detail": "writes a binary export to the MCP server's filesystem",
+    },
+    "upgrade": {
+        "reason": "shared_host_install",
+        "detail": "would inspect or replace the CLI installed on the MCP host",
+    },
+    "verify-email": {
+        "reason": "interactive_auth",
+        "detail": "prompts for a verification token sent out of band",
+    },
+}
+
+# The LangGraph in-process tool deliberately exposes a smaller service-layer
+# subset.  Its implementation table is checked against this declaration in
+# both directions; this list is the cross-surface availability decision, while
+# ``deepcell_tool._COMMANDS`` remains the parser/dispatcher implementation.
+IN_PROCESS_COMMANDS = frozenset(
+    {
+        "cat",
+        "defs apply",
+        "describe",
+        "example",
+        "guide",
+        "help",
+        "ls",
+        "query",
+        "ref",
+        "rules",
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Jingwei operation -> CLI command mapping
+# ---------------------------------------------------------------------------
+
+# Values are fnmatch patterns over leaf command paths in the generated Click
+# surface.  The generator expands them to exact names and rejects a pattern
+# that matches nothing.  An operation may support several commands and a
+# command may use several operations.
+ENDPOINT_COMMANDS: dict[str, tuple[str, ...]] = {
+    # Service/auth lifecycle.
+    "health_check_health_get": ("doctor",),
+    "claim_demo_auth_claim_demo_post": ("login", "register"),
+    "device_code_auth_device_code_post": ("login",),
+    "device_token_auth_device_token_post": ("login",),
+    "login_auth_login_post": ("login",),
+    "register_auth_register_post": ("register",),
+    "revoke_token_auth_revoke_token_post": ("logout",),
+    "send_verification_auth_send_verification_post": ("verify-email",),
+    "verify_email_auth_verify_email_post": ("verify-email",),
+    "get_me_auth_me_get": ("whoami",),
+    "export_me_auth_me_export_get": ("account export",),
+    "delete_me_auth_me_delete": ("account delete",),
+
+    # Primary document/query/edit routes.
+    "apply_defs_ops_endpoint_apply_defs_ops_post": (
+        "defs add-*",
+        "defs update-*",
+        "defs delete-*",
+        "defs rename-*",
+        "defs reorder-*",
+        "defs set-*",
+        "defs header *",
+        "defs apply",
+        # The Deck surface's structural ops. Same endpoint as `defs` — a deck
+        # op is a defs op; `deepcell deck` is a front door onto the flag-shaped
+        # subset of them, not a second route.
+        "deck add",
+        "deck add-slide",
+        "deck rename",
+        "deck rename-slide",
+        "deck reorder",
+        "deck reorder-slide",
+        "deck delete",
+        "deck delete-slide",
+        "deck bind",
+        "deck unbind",
+        "deck brand",
+        "doc stamp-ids",
+        "doc replace-block",
+        "doc insert-block",
+        "doc move-block",
+        "doc delete-block",
+        "doc set-body",
+        "doc patch-body",
+        "doc set-notation",
+    ),
+    "batch_edit_values_batch_edit_post": ("edit",),
+    "get_cell_meta_cell_meta_post": ("cell-meta",),
+    "list_defs_endpoint_defs_list_post": ("defs list",),
+    "show_defs_endpoint_defs_show_post": ("defs show",),
+    "describe_document_describe_post": ("describe",),
+    "query_deepcell_query_post": ("query",),
+    "get_relationships_relationships_post": ("relationships",),
+    "document_backlinks_document_backlinks_post": ("doc backlinks",),
+    "impact_impact_post": ("impact show",),
+    "review_impact_review_post": ("impact review",),
+    "apply_impact_apply_post": ("impact apply",),
+    "reopen_impact_reopen_post": ("impact reopen",),
+    "document_blocks_document_blocks_post": ("doc blocks",),
+    "document_links_document_links_post": ("doc links",),
+    "document_lint_document_lint_post": ("doc lint",),
+    "list_documents_document_list_post": ("doc list",),
+    "document_outline_document_outline_post": ("doc outline",),
+    "show_document_document_show_post": ("doc show",),
+
+    # Reasoning graph.
+    "edit_reasoning_edit_post": (
+        "reasoning add-*",
+        "reasoning update-*",
+        "reasoning delete-*",
+        "reasoning supersede-*",
+        "reasoning set-conclusion",
+    ),
+    "reasoning_graph_reasoning_graph_post": ("reasoning graph",),
+    "reasoning_lint_reasoning_lint_post": ("reasoning lint",),
+    "query_reasoning_query_post": ("reasoning impact",),
+
+    # Generated reference surfaces.
+    "list_all_examples_examples_get": ("example", "example list"),
+    "get_example_layer_examples__name__layer__layer__get": (
+        "example show",
+        "example get",
+    ),
+    "list_guide_topics_guide_get": ("guide",),
+    "list_domain_packs_guide_packs_index_get": ("guide",),
+    "get_capability_index_guide_capabilities_index_get": ("guide",),
+    "get_topic_guide__topic__get": ("guide",),
+    "list_ref_namespaces_ref_get": ("ref",),
+    "resolve_id_ref_resolve_get": ("ref",),
+    "search_surfaces_ref_search_get": ("ref",),
+    "list_namespace_entries_ref__namespace__get": ("ref",),
+    "get_namespace_entry_ref__namespace___name__get": ("ref",),
+    "list_house_rules_rules_get": ("rules",),
+    "get_house_rule_rules__rule_id__get": ("rules",),
+
+    # Import, ingestion, and export.
+    "import_file_import_post": ("import",),
+    "cn_extract_ingest_cn_extract_get": ("ingest cn extract",),
+    "cn_filings_ingest_cn_filings_get": ("ingest cn filings",),
+    "cn_search_ingest_cn_search_get": ("ingest cn search",),
+    "cn_statements_ingest_cn_statements_get": ("ingest cn statements",),
+    "to_docx_to_docx_post": ("to-docx",),
+    "to_excel_to_excel_post": ("to-excel",),
+    "to_pdf_to_pdf_post": ("to-pdf",),
+    "to_pptx_to_pptx_post": ("to-pptx",),
+
+    # Workspace files, history, variants, sync, and sharing.
+    "list_workspaces_workspaces_get": ("project list",),
+    "create_workspace_workspaces_post": ("project create",),
+    "get_workspace_workspaces__slug__get": (
+        "project use",
+        "project info",
+        "clone",
+        "pull",
+        "push",
+        "status",
+    ),
+    "list_workspace_files_workspaces__slug__files_get": (
+        "ls",
+        "grep",
+        "clone",
+        "pull",
+        "push",
+        "status",
+        "doctor",
+    ),
+    "get_workspace_file_workspaces__slug__files__filename__get": (
+        "cat",
+        "download",
+        "grep",
+        "query",
+        "claim *",
+        "assumption *",
+        "reasoning *",
+        "merge *",
+        "clone",
+        "pull",
+        "push",
+        "status",
+    ),
+    "create_or_update_workspace_file_workspaces__slug__files__filename__post": (
+        "write",
+        "replace",
+        "reasoning add-*",
+        "reasoning update-*",
+        "reasoning delete-*",
+        "reasoning supersede-*",
+        "reasoning set-conclusion",
+    ),
+    "delete_workspace_file_workspaces__slug__files__filename__delete": ("rm",),
+    "batch_commit_workspace_files_workspaces__slug__files_batch_post": ("push",),
+    "replace_in_workspace_file_workspaces__slug__files_replace_post": ("replace",),
+    "list_workspace_versions_workspaces__slug__versions_get": (
+        "log",
+        "clone",
+        "pull",
+        "push",
+        "status",
+    ),
+    "workspace_commit_pending_workspaces__slug__versions_commit_post": ("commit",),
+    "workspace_version_diff_workspaces__slug__versions_diff_get": ("diff",),
+    "workspace_version_restore_workspaces__slug__versions_restore_post": ("restore",),
+    "list_workspace_changes_workspaces__slug__changes_get": ("changes list",),
+    "workspace_change_diff_workspaces__slug__changes_diff_get": ("changes diff",),
+    "revert_workspace_change_workspaces__slug__changes_revert_post": (
+        "changes revert",
+    ),
+    "list_workspace_variants_workspaces__slug__variants_get": ("variant list",),
+    "get_variant_workspaces__slug__variants__name__get": (
+        "variant checkout",
+        "clone",
+        "pull",
+        "push",
+        "status",
+    ),
+    "create_workspace_variant_workspaces__slug__variants__name__post": ("variant create",),
+    "get_variant_diff_workspaces__slug__variants__name__diff_get": ("variant diff",),
+    "list_variant_files_workspaces__slug__variants__name__files_get": (
+        "clone",
+        "pull",
+        "push",
+        "status",
+    ),
+    "get_variant_file_workspaces__slug__variants__name__files__filename__get": (
+        "clone",
+        "pull",
+        "push",
+        "status",
+    ),
+    "create_or_update_variant_file_workspaces__slug__variants__name__files__filename__post": ("push",),
+    "merge_variant_into_main_workspaces__slug__variants__name__merge_post": ("variant merge",),
+    "merge_preview_merge_preview_post": ("merge *", "pull"),
+    "resolve_conflicts_merge_resolve_post": ("merge resolve",),
+    "list_share_links_workspaces__slug__shares_get": ("share list",),
+    "create_share_link_workspaces__slug__shares_post": ("share create",),
+    "revoke_share_link_workspaces__slug__shares__share_id__delete": ("share revoke",),
+}
+
+
+# ---------------------------------------------------------------------------
+# Explicit operations without a CLI route
+# ---------------------------------------------------------------------------
+
+# Every operation not in ENDPOINT_COMMANDS must appear here.  Grouped values
+# remain exact operation ids: adding a route under an existing tag still fails
+# codegen until somebody classifies that route deliberately.
+ENDPOINT_EXCEPTIONS: dict[str, tuple[str, str]] = {
+    # Service metadata, cache, telemetry, and server-owned lifecycle.
+    "root__get": ("service_metadata", "HTTP landing response, not an analytical capability"),
+    "version_info_version_get": ("service_metadata", "frontend/service version probe; CLI reports its installed version locally"),
+    "clear_cache_cache_clear_post": ("internal_ops", "operator-only cache maintenance"),
+    "get_cache_stats_cache_stats_get": ("internal_ops", "operator-only cache diagnostics"),
+    "record_unknown_command_cli_unknown_commands_post": ("implicit_client", "CLI telemetry emitted automatically, never invoked directly"),
+    "record_web_events_signals_web_post": ("frontend_only", "browser analytics collector"),
+    "create_demo_session_demo_session_post": ("implicit_client", "anonymous CLI session bootstrap performed by DeepCellClient"),
+    # The /demo gallery's preview panel. A CLI caller has the fixture itself —
+    # `deepcell example` and the shipped files — so a route whose whole job is
+    # to show a browser what is inside one before opening it has no verb.
+    "demo_example_preview_demo_examples__filename__preview_get": ("frontend_only", "gallery preview panel: which surfaces an example carries"),
+    "demo_example_thumbnail_demo_examples__filename__thumbnail_png_get": ("frontend_only", "gallery preview panel: the example's opening slide, rasterized"),
+    # The example as plain XML, for an agent that is NOT this CLI. A caller who
+    # has `deepcell` has the fixtures already (`deepcell example get`), so there
+    # is nothing here to wrap in a verb. What this route is for is the agent on
+    # the other side of a copied prompt — one that has never heard of DeepCell
+    # and needs a URL it can fetch to see the shape it is being asked to copy.
+    "demo_example_raw_demo_examples__filename__raw_get": ("frontend_only", "public example XML, for an outside agent handed a URL"),
+    "ensure_demo_workspace_demo_workspace_post": ("agent_runtime", "hosted-agent workspace bootstrap"),
+    "get_quota_agent_runs_quota_get": ("agent_runtime", "hosted chat run quota"),
+    "reserve_thread_agent_threads_reserve_post": ("agent_runtime", "hosted chat thread bookkeeping"),
+    # The anonymous run allowance, spent on every submit to the HOSTED agent.
+    # A CLI caller drives their own agent and their own model, so there is
+    # nothing here for a verb to wrap — the runs this counts are the ones the
+    # hosted chat makes on the caller's behalf, which the CLI never issues.
+    "reserve_run_agent_runs_reserve_post": ("agent_runtime", "hosted chat run reservation"),
+    # The same allowance, spent by a visitor on a share link. Doubly not a CLI
+    # surface: it is reached with a share token rather than a user identity.
+    "reserve_share_run_share__token__runs_reserve_post": ("agent_runtime", "hosted share-visitor run reservation"),
+
+    # The task record, which belongs to the workbench rail and its inspectors.
+    #
+    # A task is one CONVERSATION with the agent, and the CLI does not have
+    # conversations: its own writes are stamped with an operation id and a
+    # `DeepCell-Command` trailer, so `changes list` already says what was run
+    # and what it touched, without a thread to hang it from. A CLI mirror of
+    # these was built and removed — it could only report on work done in the
+    # browser, which is where the reader already is when they ask.
+    "list_workspace_tasks_workspaces__slug__tasks_get": ("frontend_only", "workbench task rail; a CLI session is not a task"),
+    "update_workspace_task_workspaces__slug__tasks__thread_id__patch": ("frontend_only", "task rename and scope, set from the rail and the composer shelf"),
+
+    # Browser/MCP authentication and account management not exposed as CLI verbs.
+    "claim_anonymous_auth_claim_anonymous_post": ("frontend_only", "browser anonymous-session claim flow"),
+    # Reads the HttpOnly ``browser_id`` cookie and nothing else, on purpose:
+    # accepting an identity from the request body would let anyone who guesses
+    # a visitor's browser_id probe their demo state from another machine. A CLI
+    # caller has no such cookie — its half of the claim flow is the
+    # ``device_id`` + ``anon_access_token`` body variant of /auth/claim-demo,
+    # which is already mapped above.
+    "pending_anonymous_work_auth_pending_anonymous_work_get": ("frontend_only", "browser claim prompt: does this browser still hold claimable demo work"),
+    "device_authorize_auth_device_authorize_post": ("frontend_only", "browser approval half of the device flow"),
+    "forgot_password_auth_forgot_password_post": ("frontend_only", "browser password recovery"),
+    "google_callback_auth_google_callback_get": ("frontend_only", "browser OAuth callback"),
+    "google_login_auth_google_login_get": ("frontend_only", "browser OAuth entry"),
+    "google_status_auth_google_status_get": ("frontend_only", "browser sign-in capability probe"),
+    "logout_auth_logout_post": ("frontend_only", "cookie logout; CLI uses the refresh-token revocation route"),
+    "update_me_auth_me_put": ("frontend_only", "account settings editor"),
+    "change_password_auth_me_password_put": ("frontend_only", "account settings editor"),
+    "get_my_quota_auth_me_quota_get": ("frontend_only", "account quota display"),
+    "password_requirements_auth_password_requirements_get": ("frontend_only", "registration/password form metadata"),
+    "refresh_auth_refresh_post": ("implicit_client", "DeepCellClient refreshes credentials automatically"),
+    "reset_password_auth_reset_password_post": ("frontend_only", "browser password recovery"),
+    "join_waitlist_auth_waitlist_post": ("frontend_only", "website waitlist form"),
+    "list_api_keys_auth_api_keys_get": ("frontend_only", "API keys are managed in account settings"),
+    "create_api_key_auth_api_keys_post": ("frontend_only", "API keys are managed in account settings"),
+    "revoke_api_key_auth_api_keys__key_id__delete": ("frontend_only", "API keys are managed in account settings"),
+    "verify_api_key_auth_api_keys_verify_post": ("mcp_auth", "MCP bearer verification performed by the server"),
+    # Frontend configuration, dashboards, uploads, and preview/share viewers.
+    "get_export_formats_config_export_formats_get": ("frontend_only", "download-menu capability metadata"),
+    "get_import_sources_config_import_sources_get": ("frontend_only", "browser import-menu metadata"),
+    "dashboard_snapshot_dashboard_snapshot_post": ("frontend_only", "project dashboard aggregation"),
+    "download_file_files_download__object_name__get": ("attachment_transport", "uploaded attachment download, distinct from workspace document files"),
+    "upload_file_files_upload_post": ("attachment_transport", "uploaded attachment storage, distinct from workspace document files"),
+    "get_download_url_files_url__object_name__get": ("attachment_transport", "presigned attachment URL for browser/agent tools"),
+    "import_from_url_import_from_url_post": ("agent_runtime", "hosted agent URL-ingestion helper"),
+    "cn_source_pdf_ingest_cn_source__source_id__pdf_get": ("frontend_only", "inline filing PDF viewer"),
+    "get_one_example_examples__name__get": ("published_reference", "published example envelope; CLI reads the index and individual layers"),
+    "render_plan_render_plan_post": ("frontend_only", "grid render-plan fetch"),
+    "edit_inline_edit_inline_post": ("deprecated_alias", "legacy frontend alias; CLI uses files:replace or batch-edit"),
+    "upload_workspace_file_workspaces__slug__files_upload_post": ("frontend_only", "browser attachment upload into a workspace"),
+
+    # Public preview is a cookie-free browser surface, not the authenticated CLI.
+    "preview_cell_meta_preview_cell_meta_post": ("public_preview", "public preview inspector"),
+    "preview_reasoning_enumerate_preview_reasoning_enumerate_post": ("public_preview", "public preview reasoning reader"),
+    "preview_reasoning_query_preview_reasoning_query_post": ("public_preview", "public preview reasoning reader"),
+    "preview_relationships_preview_relationships_post": ("public_preview", "public preview relationship graph"),
+    "preview_render_plan_preview_render_plan_post": ("public_preview", "public preview renderer"),
+    "preview_source_preview_source_post": ("public_preview", "public preview source reader"),
+    "preview_to_docx_preview_to_docx_post": ("public_preview", "public preview export"),
+    "preview_to_excel_preview_to_excel_post": ("public_preview", "public preview export"),
+    "preview_to_pptx_preview_to_pptx_post": ("public_preview", "public preview export"),
+
+    # Browser share capabilities are token-scoped mirrors of authenticated APIs.
+    "get_share_info_share__token__get": ("share_viewer", "browser share metadata"),
+    "create_share_agent_session_share__token__agent_session_post": ("share_viewer", "share-assistant bootstrap"),
+    "share_apply_defs_ops_share__token__apply_defs_ops_post": ("share_viewer", "token-scoped browser/assistant edit route"),
+    "share_batch_edit_share__token__batch_edit_post": ("share_viewer", "token-scoped browser/assistant edit route"),
+    "share_cell_meta_share__token__cell_meta_post": ("share_viewer", "token-scoped browser inspector"),
+    "get_share_content_share__token__content_get": ("share_viewer", "token-scoped browser document fetch"),
+    "edit_shared_file_share__token__edit_post": ("share_viewer", "token-scoped browser/assistant edit route"),
+    "share_edit_inline_share__token__edit_inline_post": ("deprecated_alias", "legacy token-scoped frontend edit alias"),
+    "get_share_membership_share__token__membership_get": ("share_viewer", "browser ownership banner"),
+    "share_document_meta_share__token__meta_get": ("share_viewer", "browser share metadata"),
+    "share_head_share__token__head_get": ("share_viewer", "browser revision poll"),
+    "share_latest_share__token__latest_get": ("share_viewer", "browser document refresh"),
+    "share_og_image_share__token__og_image_png_get": ("share_viewer", "social preview image"),
+    "share_query_share__token__query_post": ("share_viewer", "token-scoped browser query"),
+    "share_reasoning_edit_share__token__reasoning_edit_post": ("share_viewer", "token-scoped browser/assistant reasoning edit"),
+    "share_reasoning_enumerate_share__token__reasoning_enumerate_post": ("share_viewer", "token-scoped browser reasoning reader"),
+    "share_reasoning_query_share__token__reasoning_query_post": ("share_viewer", "token-scoped browser reasoning reader"),
+    "share_relationships_share__token__relationships_post": ("share_viewer", "token-scoped browser relationship graph"),
+    "share_render_plan_share__token__render_plan_post": ("share_viewer", "token-scoped browser renderer"),
+    "share_to_docx_share__token__to_docx_post": ("share_viewer", "token-scoped browser export"),
+    "share_to_excel_share__token__to_excel_post": ("share_viewer", "token-scoped browser export"),
+    "share_to_pptx_share__token__to_pptx_post": ("share_viewer", "token-scoped browser export"),
+    "verify_password_share__token__verify_password_post": ("share_viewer", "browser share-password session"),
+    "list_shared_file_versions_share__token__versions_get": ("share_viewer", "browser share history"),
+    "get_shared_file_at_version_share__token__versions_content_get": ("share_viewer", "browser share history"),
+    "shared_file_version_diff_share__token__versions_diff_get": ("share_viewer", "browser share history"),
+
+    # Reasoning routes used by the web viewer; the CLI has different or local readers.
+    "diff_reasoning_diff_post": ("frontend_only", "browser comparison; reasoning-diff is deliberately Git-local"),
+    "enumerate_reasoning_reasoning_enumerate_post": ("frontend_only", "browser reasoning panel enumeration"),
+
+    # Workspace collaboration and hosted-agent state have no CLI owner today.
+    "accept_invitation_invitations_accept_post": ("frontend_only", "browser invitation acceptance"),
+    "get_thread_workspace_threads__thread_id__workspace_get": ("agent_runtime", "hosted thread/workspace binding"),
+    "delete_workspace_workspaces__slug__delete": ("frontend_only", "project settings destructive action"),
+    "update_workspace_workspaces__slug__put": ("frontend_only", "project settings editor"),
+    "list_invitations_workspaces__slug__invitations_get": ("frontend_only", "project invitation settings"),
+    "create_invitation_workspaces__slug__invitations_post": ("frontend_only", "project invitation settings"),
+    "revoke_invitation_workspaces__slug__invitations__invitation_id__delete": ("frontend_only", "project invitation settings"),
+    "list_members_workspaces__slug__members_get": ("frontend_only", "project membership settings"),
+    "add_member_workspaces__slug__members_post": ("frontend_only", "project membership settings"),
+    "remove_member_workspaces__slug__members__user_id__delete": ("frontend_only", "project membership settings"),
+    "update_member_role_workspaces__slug__members__user_id__put": ("frontend_only", "project membership settings"),
+    "list_workspace_threads_workspaces__slug__threads_get": ("agent_runtime", "hosted workspace thread list"),
+    "move_thread_to_workspace_workspaces__slug__threads_post": ("agent_runtime", "hosted thread/workspace binding"),
+    "transfer_ownership_workspaces__slug__transfer_post": ("frontend_only", "project ownership settings"),
+    "workspace_pending_changes_workspaces__slug__versions_pending_get": ("frontend_only", "browser pending-change indicator"),
+}
+
+
+# Commands that intentionally do not own a Jingwei operation.  Everything else
+# in the Click tree must be reached by at least one ENDPOINT_COMMANDS pattern.
+COMMAND_ENDPOINT_EXCEPTIONS: dict[str, tuple[str, str]] = {
+    "help": ("cli_local", "reads the local Click tree and generated contract"),
+    "reasoning-diff": ("cli_local", "compares a local working-tree file with Git HEAD"),
+    "upgrade*": ("external_service", "checks and installs a CLI release from the package service"),
+    "viewer": ("cli_local", "constructs the signed-in frontend URL without a Jingwei request"),
+}
+
+
+# ---------------------------------------------------------------------------
+# Generated runtime contract
+# ---------------------------------------------------------------------------
+
+_ARTIFACT = Path(__file__).with_name("capability-contract.json")
+
+
+@lru_cache(maxsize=1)
+def load_capability_contract() -> dict:
+    """Return the generated contract shipped with the CLI package."""
+    return json.loads(_ARTIFACT.read_text(encoding="utf-8"))
+
+
+def get_command_capability(name: str) -> dict | None:
+    """Return one exact leaf command's generated capability record."""
+    wanted = " ".join((name or "").split())
+    if not wanted:
+        return None
+    return (load_capability_contract().get("commands") or {}).get(wanted)
+
+
+def blocked_mcp_commands() -> frozenset[str]:
+    """The top-level commands runtime MCP enforcement must reject."""
+    return frozenset(MCP_BLOCKED_COMMANDS)
+
+
+def mcp_blocked_summary() -> str:
+    """Stable comma-separated block list for generated/user-facing prose."""
+    return ", ".join(sorted(MCP_BLOCKED_COMMANDS))