deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/surface.py

@@ -0,0 +1,628 @@
+"""The CLI surface — the command tree as data, with exit semantics and examples.
+
+One module, two readers: ``deepcell help -f json`` serves it directly (no
+network — the Click tree is local, and so is everything here), and
+``scripts/gen_cli_surface.py`` imports it to emit ``docs/cli-surface.json``,
+which the published doc renders. So the human page and the agent's ``help``
+dump are not *kept in sync*; they are the same bytes rendered twice.
+See ``docs/cli-agent-surface.md`` §3 and §9.
+
+Three things this adds to what Click already knows:
+
+**Exit semantics per command.** ``ref exit`` documents centrally, which
+means an agent must know to go read a separate topic *before* it can interpret
+a failure it has already hit. Exit 1 means five different things and the
+difference is whether anything was written — so it belongs in the help of the
+command that can return it. Expressed as ordered patterns rather than 131
+entries: the taxonomy is genuinely per-*family*, and a per-command list would
+be 131 chances to disagree with itself.
+
+**One example per command.** Agents pattern-match on invocations far more
+reliably than they parse flag tables. Examples are *derived* from the Click
+signature by default and *authored* where a derived one would mislead; the
+manifest marks which, so a derived example is never mistaken for a tested one.
+
+**Typed ``see_also`` ids**, resolved by ``deepcell ref``.
+
+⚠ Nothing here may name a defs-op kind. ``cli/tests/test_op_reachability.py``
+scans this package for op-kind strings in real code positions and would read
+them as "the CLI can emit this op", silently disabling the reachability guard.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import inspect
+from typing import Any
+
+import click
+
+# ---------------------------------------------------------------------------
+# Exit semantics
+# ---------------------------------------------------------------------------
+
+#: ``(glob, sense-id)``, first match wins. Sense ids are defined once, in the
+#: backend's ``ref:exit`` namespace; ``test_cli_surface_codegen.py`` asserts
+#: every id used here exists there, so the two halves cannot drift apart.
+#:
+#: Order matters: the more specific pattern must come first — ``merge *``
+#: before a bare ``merge`` would swallow it, and so on.
+#:
+#: ⚠ These are command PATHS, so a sense that depends on a *flag* cannot be
+#: expressed here at all. That constraint is why ``replace`` is a command and
+#: not a mode: string replacement writes first and validates second
+#: (``written-but-invalid``) while ``edit`` applies a batch row by row
+#: (``partial``), and one command carrying two senses had nowhere to go in this
+#: table. Splitting it made the taxonomy expressible with no schema change —
+#: both are plain entries below. ``edit --replace`` survives as a deprecated
+#: alias, so a caller who uses it reads ``edit``'s sense; the alias warns and
+#: names the command whose exit codes actually describe it.
+EXIT_SENSE_RULES: list[tuple[str, str]] = [
+    # Read-only checks — nothing was ever going to change.
+    ("describe", "read-only-check"),
+    ("reasoning lint", "read-only-check"),
+    ("reasoning-diff", "read-only-check"),
+    # ⚠ Must precede `defs *`: the two defs READS (#1291) write nothing, so the
+    # write family's "nothing-changed, re-send the whole batch" sense would
+    # misdescribe them.
+    ("defs list", "read-only-check"),
+    ("defs show", "read-only-check"),
+    # Conflict — your state is preserved.
+    ("pull", "conflict"),
+    ("merge *", "conflict"),
+    ("variant merge", "conflict"),
+    # Written, then validated: a failure means it is already on disk.
+    ("write", "written-but-invalid"),
+    ("replace", "written-but-invalid"),
+    ("push", "written-but-invalid"),
+    ("commit", "written-but-invalid"),
+    # ⚠ Glob-matched, first match wins — `reasoning add-*` does NOT cover
+    # `set-conclusion`, so without its own entry it would exit 1 with no sense
+    # attached. That is a silent quality loss, not a test failure.
+    ("reasoning set-conclusion", "written-but-invalid"),
+    ("reasoning add-*", "written-but-invalid"),
+    ("reasoning update-*", "written-but-invalid"),
+    ("reasoning supersede-*", "written-but-invalid"),
+    ("reasoning delete-*", "written-but-invalid"),
+    # Whole-batch atomic: nothing was applied, re-send everything.
+    ("defs *", "nothing-changed"),
+    # Partially applied — read results and errors.
+    ("edit", "partial"),
+    ("import", "partial"),
+]
+
+#: Commands that exit 2 on an unparseable document, distinct from exit 1
+#: ("parsed fine, id not found"). Everything else's exit 2 is Click's own
+#: usage error, which needs no per-command note.
+EXIT_TWO_ON_UNPARSEABLE = frozenset({
+    "claim history",
+    "claim variant",
+    "claim falsified",
+    "assumption impact",
+    "reasoning-diff",
+})
+
+
+def exit_sense_for(command: str) -> str | None:
+    """The exit-1 sense id for *command*, or ``None`` when no rule matches."""
+    for pattern, sense in EXIT_SENSE_RULES:
+        if fnmatch.fnmatch(command, pattern):
+            return sense
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Examples and cross-references
+# ---------------------------------------------------------------------------
+
+#: Authored examples. ``docs/cli-agent-surface.md`` §3.2 asks for "one runnable
+#: example per command, using a workspace file — **not a placeholder**. Agents
+#: pattern-match on invocations far more reliably than they parse flag tables."
+#:
+#: A derived example satisfies the *shape* and not that requirement: an agent
+#: reading ``--sheet <sheet_id> --member <member>`` learns nothing it could not
+#: read off the flag table, so it falls back to `--help` anyway. The guide-eval
+#: run measured what that costs — 87 of 161 commands rendered as placeholders,
+#: and 108 of its 178 findings were some topic being blamed for not shipping
+#: the example that belongs here.
+#:
+#: So: author one wherever an agent has to *choose* a value — a status
+#: archetype, an axis, a rel, a target selector, a JSON payload. Leave it
+#: derived only where the signature already says everything (``ls``, ``logout``).
+#: Values are illustrative but must be **legal**: every flag exists on the
+#: command and every enum value is one it accepts, pinned by
+#: ``cli/tests/test_surface_examples.py`` against the live Click tree.
+COMMAND_EXAMPLES: dict[str, str] = {
+    "doctor": "deepcell doctor -f json",
+    "ls": "deepcell ls",
+    "cat": "deepcell cat model.deepcell",
+    "write": "deepcell write model.deepcell --file ./model.deepcell",
+    "describe": "deepcell describe model.deepcell --lint",
+    "query": "deepcell query model.deepcell Revenue FY2026E",
+    "defs list": "deepcell defs list model.deepcell",
+    "defs show": "deepcell defs show model.deepcell Revenue",
+    "cell-meta": "deepcell cell-meta model.deepcell Revenue FY2026E",
+    "edit": "deepcell edit model.deepcell Growth_Rate FY2026E 0.12",
+    "replace": 'deepcell replace model.deepcell "<Old>text</Old>" "<New>text</New>"',
+    "grep": "deepcell grep Revenue",
+    # `orient/start` is the front door. It was `quick-start` for a while, on
+    # the strength of a description that read "Start here" — that topic was a
+    # finance template index and has since been deleted (`doctor.py` reached
+    # the same conclusion independently).
+    "guide": "deepcell guide orient/start",
+    "rules": "deepcell rules R2",
+    "ref": "deepcell ref lint/hardcoded_literal_in_calc",
+    "relationships": "deepcell relationships model.deepcell --type business",
+    "to-excel": "deepcell to-excel model.deepcell -o model.xlsx",
+    "share create": "deepcell share create model.deepcell --permission view",
+    "viewer": "deepcell viewer model.deepcell",
+    "reasoning lint": "deepcell reasoning lint model.deepcell --strict",
+    "reasoning graph": "deepcell reasoning graph model.deepcell --syntax mermaid",
+    "project use": "deepcell project use my-project",
+
+    # ---- Structure -------------------------------------------------------
+    "defs add-item": (
+        "deepcell defs add-item model.deepcell --name Revenue --label Revenue "
+        "--data-type monetary --scale 6 --currency USD --order-mode append"
+    ),
+    "defs update-item": (
+        "deepcell defs update-item model.deepcell Revenue --scale 3 --currency USD"
+    ),
+    "defs rename-item": "deepcell defs rename-item model.deepcell Revenue Total_Revenue",
+    "defs delete-item": "deepcell defs delete-item model.deepcell Revenue --cascade",
+    "defs reorder-item": "deepcell defs reorder-item model.deepcell Revenue --to-index 0",
+    "defs add-calc": (
+        "deepcell defs add-calc model.deepcell --item Revenue --calc-id calc_revenue "
+        "--formula 'Units_Sold[CURRENT] * Unit_Price[CURRENT]' --status projected"
+    ),
+    "defs update-calc": (
+        "deepcell defs update-calc model.deepcell calc_revenue "
+        "--formula 'Units_Sold[CURRENT] * Unit_Price[CURRENT] * 1.02'"
+    ),
+    # --archetype is what the status MEANS; omitting it leaves the meaning to
+    # be guessed from the id's spelling (house rule R13).
+    "defs add-status": (
+        "deepcell defs add-status model.deepcell --name Budget --ref budget "
+        "--archetype budget --authority derived"
+    ),
+    "defs update-status": (
+        "deepcell defs update-status model.deepcell budget --archetype budget --label Budget"
+    ),
+    # --state is what says whether the period is over — the question a trailing
+    # A/E on the id used to answer by accident.
+    "defs add-context": (
+        "deepcell defs add-context model.deepcell --name FY2025 --context FY2025 "
+        "--kind period --state closed --status actual"
+    ),
+    "defs add-period": (
+        "deepcell defs add-period model.deepcell --name FY2026 --context FY2026 "
+        "--state future --status projected"
+    ),
+    "defs update-context": (
+        "deepcell defs update-context model.deepcell FY2025 --state closed --as-of 2025-12-31"
+    ),
+    # No --label here: `add-scenario` takes the id only, and the display label
+    # is set afterwards with `update-scenario --label`.
+    "defs add-scenario": "deepcell defs add-scenario model.deepcell --name downside",
+    # --name changes the id every scenarioRef points at; --label is display only.
+    "defs update-scenario": (
+        "deepcell defs update-scenario model.deepcell downside --label 'Bear case'"
+    ),
+    "defs rename-scenario": "deepcell defs rename-scenario model.deepcell downside bear",
+    "defs apply": "deepcell defs apply model.deepcell --ops-file ops.json --dry-run",
+
+    # ---- Layout ----------------------------------------------------------
+    "defs add-sheet": "deepcell defs add-sheet model.deepcell --label 'Variance review' --index 1",
+    "defs add-block": (
+        "deepcell defs add-block model.deepcell --sheet variance --block-type table "
+        "--name 'Revenue vs budget' --item-orders Revenue,COGS --context-refs FY2025,FY2026"
+    ),
+    # --member says what kind of id --ref is: 'item' with rows, 'context' with columns.
+    "defs add-axis-member": (
+        "deepcell defs add-axis-member model.deepcell --sheet variance --block revenue_table "
+        "--axis rows --member item --ref Gross_Profit"
+    ),
+    "defs delete-axis-member": (
+        "deepcell defs delete-axis-member model.deepcell --sheet variance "
+        "--block revenue_table --axis rows --ref Gross_Profit"
+    ),
+    "defs reorder-axis-member": (
+        "deepcell defs reorder-axis-member model.deepcell --sheet variance "
+        "--block revenue_table --axis rows --ref Gross_Profit --to-index 0"
+    ),
+    "defs reorder-block": (
+        "deepcell defs reorder-block model.deepcell --sheet variance --block revenue_table --to-index 0"
+    ),
+    "defs reorder-sheets": "deepcell defs reorder-sheets model.deepcell variance --to-index 0",
+    "defs set-block-attrs": (
+        "deepcell defs set-block-attrs model.deepcell --sheet variance --block revenue_table "
+        "--status-refs actual,budget --status-expansion columns"
+    ),
+    "defs add-sensitivity": (
+        "deepcell defs add-sensitivity model.deepcell --sheet summary --name 'IRR sensitivity' "
+        "--spec-file sensitivity.json"
+    ),
+    # --block-id scopes the format to one block; without it the rule is global
+    # to the sheet and every other block inherits it too.
+    "defs set-format": (
+        "deepcell defs set-format model.deepcell --sheet-id ic --block-id deal_summary "
+        "--item-ref Entry_Multiple --scope item --number-format '0.0x' --bold"
+    ),
+    "defs add-format": (
+        "deepcell defs add-format model.deepcell fmt_statement --rule 'default:fontName=Arial'"
+    ),
+    "defs add-rule": (
+        "deepcell defs add-rule model.deepcell fmt_statement --target 'level:0:item' "
+        "--font-weight bold --number-format '#,##0'"
+    ),
+
+    # ---- Prose -----------------------------------------------------------
+    "defs add-doc": (
+        "deepcell defs add-doc model.deepcell --doc-id variance_note "
+        "--name 'July variance note' --lang en --body-file variance-note.md"
+    ),
+    "doc set-body": (
+        "deepcell doc set-body model.deepcell --doc variance_note "
+        "--body-file variance-note.md -m 'Rewrite the July variance note'"
+    ),
+    # --anchor must be an explicit {#id}, never a heading slug.
+    "doc patch-body": (
+        "deepcell doc patch-body model.deepcell --doc variance_note --anchor outlook "
+        "--markdown '## Outlook {#outlook}\\n\\nQ4 pipeline covers the gap.'"
+    ),
+    "doc outline": "deepcell doc outline model.deepcell --doc variance_note",
+    "doc links": "deepcell doc links model.deepcell --doc variance_note --unresolved",
+    "doc show": "deepcell doc show model.deepcell --doc variance_note --as markdown",
+    "doc lint": "deepcell doc lint model.deepcell --doc variance_note --strict",
+    "to-docx": "deepcell to-docx model.deepcell --doc variance_note -o variance-note.docx",
+    "to-pptx": "deepcell to-pptx model.deepcell --deck board -o board.pptx",
+
+    # ---- Reasoning -------------------------------------------------------
+    "reasoning add-claim": (
+        "deepcell reasoning add-claim model.deepcell --id t_gm --kind thesis "
+        "--label 'Gross margin expands' --body 'Mix shift to subscription lifts GM 200bps.' "
+        "--item-refs Gross_Margin_Pct --confidence 0.62"
+    ),
+    "reasoning add-assumption": (
+        "deepcell reasoning add-assumption model.deepcell --id a_hiring --label 'Hiring lands on plan' "
+        "--body 'Sales headcount reaches 40 by Q3.' --item-refs Headcount"
+    ),
+    "reasoning add-evidence": (
+        "deepcell reasoning add-evidence model.deepcell --id e_10k --source-ref src_aapl_10k_fy25 "
+        "--excerpt 'Gross margin of 46.2%' --retrieved-at 2026-02-19T10:30:00Z"
+    ),
+    # weight is qualitative confidence in the EDGE — never a probability, and
+    # never copied from the risk claim's @probability.
+    "reasoning add-argument": (
+        "deepcell reasoning add-argument model.deepcell --from-id r_pricing --to-id t_gm "
+        "--rel refutes --weight 0.6"
+    ),
+    "reasoning set-conclusion": "deepcell reasoning set-conclusion model.deepcell t_gm",
+    "reasoning supersede-claim": (
+        "deepcell reasoning supersede-claim model.deepcell t_gm --id t_gm_v2 "
+        "--label 'Gross margin expands, slower' --body 'Mix shift lifts GM 120bps.' --confidence 0.55"
+    ),
+    "reasoning supersede-assumption": (
+        "deepcell reasoning supersede-assumption model.deepcell a_hiring --id a_hiring_v2 "
+        "--label 'Hiring lands one quarter late'"
+    ),
+    # A premise actuals disproved is marked broken in place, not rewritten —
+    # the wording is the record of what was believed.
+    "reasoning update-assumption": (
+        "deepcell reasoning update-assumption model.deepcell a_hiring --status broken --broken-at 2026-07-31"
+    ),
+    "reasoning update-claim": (
+        "deepcell reasoning update-claim model.deepcell t_gm --status falsified"
+    ),
+    "reasoning update-argument": (
+        "deepcell reasoning update-argument model.deepcell arg_pricing --weight 0.6"
+    ),
+    # The edge's address is its id OR its triple; a bare edge has no id to type.
+    "reasoning delete-argument": (
+        "deepcell reasoning delete-argument model.deepcell --from-id r_pricing --edge-rel refutes --to-id t_gm"
+    ),
+    # --cascade takes the edges with the node; --allow-dangling leaves them.
+    "reasoning delete-claim": "deepcell reasoning delete-claim model.deepcell t_gm --cascade",
+    "reasoning impact": "deepcell reasoning impact model.deepcell a_hiring",
+    "assumption impact": "deepcell assumption impact model.deepcell a_hiring",
+
+    # ---- Ingest ----------------------------------------------------------
+    # Items need id/name/level (+ row and sheet to auto-map cells); contexts
+    # need id/name/period_type (+ column). These are snake_case JSON keys, not
+    # the XML spellings (itemId / contextId / statusRef).
+    "import": (
+        "deepcell import variance.xlsx --name variance_import "
+        """--items '[{"id":"Revenue","name":"Revenue","level":0,"row":2,"sheet":"Variance"}]' """
+        """--contexts '[{"id":"FY25A","name":"FY25 actual","period_type":"annual","status":"actual","column":"B"}]'"""
+    ),
+    "ingest cn extract": (
+        "deepcell ingest cn extract https://static.cninfo.com.cn/finalpage/2026-03-28/1224567890.PDF "
+        "--statement income --persist"
+    ),
+    "ingest cn search": "deepcell ingest cn search 600519",
+    "ingest cn filings": "deepcell ingest cn filings 600519 --type annual --count 5",
+}
+
+#: Typed ids per command, resolved by ``deepcell ref``. Deliberately sparse:
+#: a pointer is worth printing only where it answers the question the command's
+#: own help cannot.
+COMMAND_SEE_ALSO: dict[str, list[str]] = {
+    "write": ["guide:generate/whole-doc", "rule:R1", "ref:exit/1"],
+    "describe": ["ref:lint/unrendered_value", "rule:R9"],
+    "edit": ["guide:generate/values", "ref:exit/1"],
+    "replace": ["guide:revise/values", "ref:exit/1"],
+    "query": ["guide:verify/query-back", "rule:R4"],
+    "defs apply": ["guide:generate/calcs", "ref:exit/1"],
+    "defs list": ["guide:revise/structure", "rule:R4"],
+    "defs show": ["guide:revise/structure", "rule:R4"],
+    "defs add-calc": ["guide:generate/calcs", "rule:R2", "ref:function/NPV"],
+    "defs add-item": ["guide:generate/structure", "rule:R7"],
+    "defs add-sensitivity": ["ref:op/add_sensitivity_block", "rule:R9"],
+    "reasoning lint": ["rule:R8", "ref:lint/unanchored_claim"],
+    "reasoning add-claim": ["guide:revise/reasoning", "ref:claim", "rule:R8"],
+    "reasoning set-conclusion": ["rule:R14", "ref:lint/dangling_conclusion_ref"],
+    "reasoning set-key-question": [
+        "rule:R19",
+        "ref:lint/dangling_key_question_ref",
+        "ref:lint/ambiguous_key_question",
+    ],
+    "to-excel": ["guide:present/layout", "rule:R9"],
+    "rules": ["guide:house-rules"],
+}
+
+
+def _derive_example(path: str, command: click.Command) -> str:
+    """Build a runnable-shaped invocation from the command's own signature.
+
+    Uses the real required parameter names, so the shape is right even though
+    the values are illustrative. Marked ``derived`` in the manifest — an
+    example nobody ran should never look like one that was tested.
+    """
+    parts = [f"deepcell {path}"]
+    for param in command.params:
+        if not isinstance(param, click.Argument) or not param.required:
+            continue
+        name = param.name or "arg"
+        if "file" in name or name in {"filename", "path"}:
+            parts.append("model.deepcell")
+        elif param.nargs == -1:
+            parts.append(f"<{name}...>")
+        else:
+            parts.append(f"<{name}>")
+    for param in command.params:
+        if isinstance(param, click.Option) and param.required:
+            flag = max(param.opts, key=len)
+            parts.append(f"{flag} <{param.name}>")
+    return " ".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Walking the Click tree
+# ---------------------------------------------------------------------------
+
+
+def _json_safe(value: Any) -> Any:
+    """Return *value* if it survives a JSON round trip, else ``None``.
+
+    Click represents "no default" with a sentinel object, and some defaults are
+    callables. The manifest is committed and byte-compared by a drift test, so
+    an unserialisable default must be dropped rather than stringified — a repr
+    would change between Python versions and show up as spurious drift.
+    """
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, (list, tuple)):
+        items = [_json_safe(item) for item in value]
+        return items if all(item is not None for item in items) else None
+    return None
+
+
+def _type_name(param: click.Parameter) -> str:
+    param_type = getattr(param, "type", None)
+    name = getattr(param_type, "name", None)
+    if name:
+        return str(name)
+    return type(param_type).__name__ if param_type else "text"
+
+
+def _describe_param(param: click.Parameter) -> dict[str, Any]:
+    """One argument or option as data.
+
+    For an **option**, ``name`` is the flag you would actually type
+    (``--order-mode``), not Click's Python identifier (``order_mode``). The
+    identifier is kept as ``param`` for anyone mapping back to the callback.
+    Reporting the identifier as ``name`` was a live trap: it looks like a flag,
+    so an agent reading the manifest would construct ``--order_mode`` and get a
+    usage error with no hint why.
+    """
+    is_option = isinstance(param, click.Option)
+    entry: dict[str, Any] = {
+        "name": (max(param.opts, key=len) if is_option and param.opts else param.name),
+        "type": _type_name(param),
+        "required": bool(param.required),
+    }
+    if is_option:
+        entry["param"] = param.name
+        # `--inherit/--no-inherit` is one Click option with the off-switch in
+        # `secondary_opts`. Listing only `opts` published half of every boolean
+        # pair: `deepcell ref` printed `--inherit` and nothing else, and the
+        # guide-eval flag check called a reference command that used
+        # `--no-inherit` a defect in the task. The flag is real; the manifest
+        # was the thing that did not know about it.
+        entry["flags"] = list(param.opts) + list(getattr(param, "secondary_opts", []))
+        entry["is_flag"] = bool(getattr(param, "is_flag", False))
+        default = _json_safe(param.default)
+        if default is not None and not entry["is_flag"]:
+            entry["default"] = default
+        if param.help:
+            entry["help"] = " ".join(str(param.help).split())
+        choices = getattr(param.type, "choices", None)
+        if choices:
+            entry["choices"] = list(choices)
+    else:
+        entry["variadic"] = param.nargs == -1
+    return entry
+
+
+def _summary(command: click.Command) -> str:
+    """The first line of the help text — what the index shows."""
+    text = command.get_short_help_str(limit=200) or ""
+    return " ".join(str(text).split())
+
+
+def _describe_command(path: str, command: click.Command) -> dict[str, Any]:
+    args = [p for p in command.params if isinstance(p, click.Argument)]
+    opts = [p for p in command.params if isinstance(p, click.Option)]
+
+    exit_codes: dict[str, str] = {"0": "completed"}
+    sense = exit_sense_for(path)
+    if sense:
+        exit_codes["1"] = sense
+    if path in EXIT_TWO_ON_UNPARSEABLE:
+        exit_codes["2"] = "unparseable-document"
+
+    authored = COMMAND_EXAMPLES.get(path)
+    # The stage is a property of the top-level command, not of each leaf:
+    # `defs add-calc` is generate because `defs` is. Carrying it per entry is
+    # what lets every other catalog — the MCP tool description, the published
+    # docs, `deepcell help` — group identically without restating the table.
+    from deepcell_cli.stages import tier_for
+
+    return {
+        "id": f"cmd:{path}",
+        "name": path,
+        "stage": tier_for(path.split(" ", 1)[0]),
+        "summary": _summary(command),
+        "args": [_describe_param(p) for p in args],
+        "flags": [_describe_param(p) for p in opts],
+        "exit_codes": exit_codes,
+        "example": authored or _derive_example(path, command),
+        "example_source": "authored" if authored else "derived",
+        "see_also": COMMAND_SEE_ALSO.get(path, []),
+    }
+
+
+def _walk(command: click.Command, path: str, out: dict[str, dict[str, Any]]) -> 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
+        # declared on the group, not on any leaf. Walking only the leaves left
+        # it out of the manifest entirely — so `deepcell help` never mentioned
+        # it, `cmd:example` resolved to nothing, and the flag existed in the
+        # CLI while every generated surface said it did not.
+        if command.invoke_without_command:
+            out[path] = _describe_command(path, command)
+        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)
+        return
+    out[path] = _describe_command(path, command)
+
+
+def build_commands() -> 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
+    add-calc`` is, and it is the leaf an agent actually invokes. A group that
+    is *itself* invocable appears too — see ``_walk``.
+
+    ⚠ A group that declares options but is **not** invocable has nowhere to put
+    them: its options must be typed before the subcommand, so attributing them
+    to each leaf would misdescribe where they go, and the group has no entry of
+    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.
+    """
+    from deepcell_cli.main import cli
+
+    out: 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)
+    return dict(sorted(out.items()))
+
+
+def build_stages() -> list[dict[str, str]]:
+    """The tiers a command's ``stage`` names, in the order the work happens.
+
+    The order is the one thing a consumer *cannot* recover from the per-command
+    ``stage`` field. ``commands`` is sorted by invocation path, so a renderer
+    grouping by first appearance would lead with ``cat``'s tier and print
+    ``present`` before ``generate`` — teaching the wrong shape of the work with
+    no way to tell it had.
+
+    That gap is not hypothetical. The web CLI reference reads this manifest and
+    was the one catalog still ignoring the stage vocabulary, because grouping
+    by it would have meant hardcoding this list in TypeScript — a sixth private
+    copy of exactly the table ``stages.py`` exists to be the only one of.
+    """
+    from deepcell_cli import stages
+
+    return [
+        {"name": tier, "summary": stages.TIER_SUMMARY[tier]}
+        for tier in stages.ALL_TIERS
+    ]
+
+
+def build_root() -> dict[str, str]:
+    """What ``deepcell --help`` prints around the command list.
+
+    The command *list* has always been derivable from ``build_commands()``, but
+    the prose either side of it was reachable only by running the CLI: the root
+    group's docstring above it, and ``_EPILOG`` — the getting-started,
+    file-handling, sync and learn-more recipes — below. Anything rendering a
+    root help pane therefore had to hand-copy them, which is the drift this
+    module exists to remove.
+
+    Both are static. The epilog is an f-string, but the only value it
+    interpolates is ``DEFAULT_API_URL``, a module constant — so the output is
+    deterministic and safe to bake into a byte-compared artifact. If a
+    *runtime* value is ever interpolated in here, this stops being generable
+    and the drift test will say so on the next unrelated commit.
+    """
+    from deepcell_cli.main import cli
+
+    return {
+        "help": _help_text(cli.help),
+        "epilog": _help_text(cli.epilog),
+    }
+
+
+def _help_text(raw: str | None) -> str:
+    """Dedent, and drop Click's ``\\b`` no-rewrap markers.
+
+    A lone ``\\b`` line tells Click's formatter not to re-wrap the paragraph
+    below it; Click consumes it and it never reaches the terminal. Carrying it
+    into the artifact would put a literal backspace control character in front
+    of five paragraphs of every consumer's output — so stripping it is what
+    keeps the artifact faithful, not a liberty taken with it.
+    """
+    text = inspect.cleandoc(raw or "")
+    lines = [line for line in text.split("\n") if line.strip("\b \t") or not line.strip()]
+    return "\n".join(line for line in lines if line.strip() != "\b").strip("\n")
+
+
+def build_globals() -> list[dict[str, Any]]:
+    """The root group's options — the ones that work on *every* command.
+
+    ``-f/--format``, ``-v/--verbose``, ``--workspace`` and ``--version`` are
+    declared once, on the root group, and ``FlexibleGroup`` deliberately
+    accepts them *after* the subcommand too (`deepcell describe x -f json`).
+    They were the same blind spot as `example --pack`, one level up: real,
+    usable on all 139 commands, and absent from every generated surface.
+
+    Emitted once rather than copied onto each command — a per-command copy
+    would be 139 places for one fact, and would also imply they are
+    command-specific, which is the opposite of what they are.
+    """
+    from deepcell_cli.main import cli
+
+    return [
+        _describe_param(param)
+        for param in cli.params
+        if isinstance(param, click.Option)
+    ]