deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/defs.py

@@ -0,0 +1,3890 @@
+"""Defs commands: structural edits (CalcDefs, ItemDefs, Periods, Scenarios, Statuses).
+
+These commands let the agent define **relationships** — items, calculations,
+periods, etc. — without supplying values. The backend recomputes every
+CalculationDefinition on the next read, so a single `add-calc` is usually
+all you need to forecast a derived metric.
+
+For literal-value writes (assumptions, historical actuals), use `deepcell edit`.
+For the paradigm overview, see `deepcell guide generate/calcs`.
+
+NOTE: this subgroup mirrors the `/apply-defs-ops` discriminated union in
+`backend/jingwei_api/routers/defs/`. When adding / renaming / removing op
+kinds, update BOTH this file and the backend models in the same PR —
+see the "Defs ops contract" section of CLAUDE.md.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+import click
+
+from deepcell_cli.commands._datatypes import warn_unrecognized_data_type
+from deepcell_cli.commands._write_opts import (
+    NegativeNumberWriteCommand,
+    WriteCommand,
+    write_message,
+)
+
+from deepcell_cli.commands._version_display import echo_version_history
+from deepcell_cli.commands.describe import (
+    _format_status_diagnostics_warning,
+    _format_unrendered_values_warning,
+)
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import (
+    echo_error,
+    echo_info,
+    echo_query_back_hint,
+    echo_success,
+    echo_warning,
+    output,
+    print_plain,
+)
+
+
+
+# Mirrors DefsOpRequest.ops max_length in
+# backend/jingwei_api/routers/defs/__init__.py — keep in sync.
+MAX_OPS_PER_BATCH = 100
+
+
+def _warn_data_type(ctx, param, value):
+    """Click callback: flag an unrecognized --data-type without rejecting it.
+
+    Nothing else in the stack validates it — the item ops str() whatever they
+    are given — so a typo is stored verbatim and every formatter silently
+    falls back to its default.
+    """
+    message = warn_unrecognized_data_type(value)
+    if message:
+        echo_warning(message)
+    return value
+_DRY_RUN_HELP = (
+    "Validate only: run the full server-side pipeline (per-op validation, "
+    "formula parse, post-apply cycle check + recompute) and report errors "
+    "without persisting anything — no commit, no revision bump."
+)
+
+#: Where ``_DefsCommand`` parks the parsed ``--dry-run`` so ``_apply`` can read
+#: it without every subcommand callback growing a parameter for it.
+_DRY_RUN_META_KEY = "deepcell.defs.dry_run"
+
+
+class _DefsCommand(WriteCommand):
+    """A ``defs`` subcommand — every one of which accepts ``--dry-run``.
+
+    ``dry_run`` is a property of ``/apply-defs-ops``, not of any one op kind:
+    the service runs the complete pipeline against an in-memory document and
+    discards the result. Declared per-command it was on 25 of 47 subcommands
+    and the gap tracked nothing but who remembered to add it (#1217) — so a
+    caller could pre-flight a ``delete-calc`` but not the ``rename-item`` that
+    cascades across the whole document.
+
+    Injecting it here makes the flag a property of the *group*, which is what
+    it is on the wire, and means a subcommand added tomorrow inherits it. The
+    value is parked in ``ctx.meta`` rather than passed to the callback so the
+    47 signatures stay unchanged; ``_apply`` reads it back.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        declared = {
+            opt
+            for param in self.params
+            if isinstance(param, click.Option)
+            for opt in param.opts
+        }
+        if "--dry-run" not in declared:
+            self.params.append(
+                click.Option(
+                    ["--dry-run", "dry_run"],
+                    is_flag=True,
+                    default=False,
+                    help=_DRY_RUN_HELP,
+                )
+            )
+        # ``-m`` / ``--title`` come from ``WriteCommand``, which is the same
+        # argument one layer along: every ``/apply-defs-ops`` call writes a
+        # commit and the endpoint has always accepted a message, so answering
+        # "No such option" read as "this edit does not make a commit" — the
+        # opposite of the truth. This family injected ``-m`` first and mapped
+        # it to the commit *subject*; it is the body everywhere else, so the
+        # shared class owns the mapping now and ``-m`` means the same thing
+        # whichever family you type it in.
+
+    def invoke(self, ctx: click.Context):
+        ctx.meta[_DRY_RUN_META_KEY] = bool(ctx.params.pop("dry_run", False))
+        return super().invoke(ctx)
+
+
+class _DefsNegativeNumberCommand(_DefsCommand, NegativeNumberWriteCommand):
+    """``defs header set`` — takes a negative literal AND ``--dry-run``."""
+
+
+class _DefsGroup(click.Group):
+    """The ``defs`` group and its subgroups, whose commands are all writes."""
+
+    command_class = _DefsCommand
+    #: Subgroups (``defs header``) are this class too, so their commands also
+    #: get the flag. `type` is Click's "same class as the parent" sentinel.
+    group_class = type
+
+
+def _dry_run_requested() -> bool:
+    """Read the ``--dry-run`` parked by :class:`_DefsCommand` for this call."""
+    ctx = click.get_current_context(silent=True)
+    return bool(ctx.meta.get(_DRY_RUN_META_KEY)) if ctx is not None else False
+
+
+# `blockType` is stored opaquely by `add_presentation_block` (deliberately
+# user-extensible), but the render pipeline dispatches on a closed set and
+# skips anything else with an UNSUPPORTED_BLOCK warning that never reaches the
+# CLI caller. Mirrors the branches in
+# backend/jingwei_api/utils/render_plan_builder.py::build_sheet_cells — keep in
+# step with it.
+_RENDERABLE_BLOCK_TYPES = frozenset(
+    {"table", "chart", "sensitivity", "key_value", "text"}
+)
+
+# Op kinds that change computed values (as opposed to structure or
+# presentation). A successful batch containing one earns the R4 query-back
+# hint — gated so presentation-only batches stay quiet and the hint keeps
+# its signal.
+_CALC_VALUE_OP_KINDS = frozenset({"add_calc", "update_calc", "delete_calc"})
+
+#: How many of the plan's `conversion_warnings` (#1036) `defs apply` prints
+#: before pointing at `describe` for the rest. See the call site for why.
+_MAX_CONVERSION_WARNINGS_SHOWN = 3
+
+
+def _echo_op_errors(errors: list[dict[str, Any]], *, total_ops: int) -> None:
+    """Print one line per failed op, addressed by its position in the batch.
+
+    The dispatcher has always returned ``index_in_request`` and the CLI has
+    always dropped it, so a 46-op batch reported `add_calc: <reason>` and left
+    the caller to find *which* ``add_calc`` — cheaper to re-send the batch
+    one op at a time than to read the error, which is exactly the round
+    economy this is meant to fix (eval job 01M1NFR73B5DMKW7ME9XGZ38HZ:
+    282 CLI calls, 198 turns, 200 of them single-entity writes).
+
+    The closing line states the atomicity guarantee as a *fact the caller can
+    act on* rather than a warning: a rejected batch persisted nothing, so
+    pre-flighting every batch with ``--dry-run`` buys nothing a failed apply
+    does not already tell you — and it doubles the round count.
+    """
+    indexed = []
+    for e in errors:
+        idx = e.get("index_in_request")
+        kind = e.get("kind", "?")
+        reason = e.get("error", "unknown error")
+        code = e.get("code")
+        code_part = f" [{code}]" if code else ""
+        where = f"op {idx} ({kind})" if isinstance(idx, int) else kind
+        echo_error(f"  {where}{code_part}: {reason}")
+        if isinstance(idx, int):
+            indexed.append(idx)
+
+    first = min(indexed) if indexed else None
+    if first is not None and total_ops > 1:
+        clean = (
+            f"ops 0-{first - 1} validated cleanly; " if first > 0 else ""
+        )
+        echo_error(
+            f"  → {clean}op {first} is the first failure of {total_ops}. "
+            "Nothing was written, so this is safe to fix and re-send whole — "
+            "a --dry-run pre-flight would have reported the same thing at the "
+            "cost of an extra round."
+        )
+
+
+def _apply(
+    ctx: Ctx,
+    slug: str,
+    filename: str,
+    ops: list[dict[str, Any]],
+    *,
+    revision: str | None = None,
+    dry_run: bool | None = None,
+    rationale: str | None = None,
+    title: str | None = None,
+) -> None:
+    """POST a batch of ops to /apply-defs-ops and emit the response.
+
+    Exits non-zero (via click.exceptions.Exit) when the API envelope
+    reports any op-level errors, so scripted callers can short-circuit
+    on `if deepcell defs ...; then ...`.
+
+    ``dry_run``, ``title`` and ``rationale`` default to whatever
+    ``--dry-run``, ``--title`` and ``-m/--message/--rationale`` the invoked
+    subcommand parsed (see :class:`_DefsCommand` and :class:`WriteCommand`);
+    pass any of them explicitly only to override. `doc` passes ``rationale``
+    that way, because its callbacks declare the option themselves.
+
+    This is the ONE place the `/apply-defs-ops` envelope is spelled. `deepcell
+    doc` built its own and drifted on every field that matters: `filename` as
+    `source_filename` (a 422 on every call) and `expected_revision` as
+    `revision` (pydantic ignores the extra, so the documented 409 never fired
+    and a concurrent write won silently). Route new callers through here.
+    """
+    if dry_run is None:
+        dry_run = _dry_run_requested()
+    parsed_title, parsed_rationale = write_message()
+    if title is None:
+        title = parsed_title
+    if rationale is None:
+        rationale = parsed_rationale
+    # Mirrors DefsOpRequest.ops max_length. Checked here so an over-cap batch
+    # says how to fix it instead of coming back as a raw pydantic 422 — the
+    # agent tool explicitly advises applying a wide grid "in ONE call", which
+    # walks straight into this limit.
+    if len(ops) > MAX_OPS_PER_BATCH:
+        raise click.ClickException(
+            f"{len(ops)} ops exceeds the server limit of {MAX_OPS_PER_BATCH} "
+            f"per request. Split them into batches of {MAX_OPS_PER_BATCH} and "
+            f"apply each in turn — each batch is applied atomically."
+        )
+
+    body: dict[str, Any] = {
+        "workspace_slug": slug,
+        "filename": filename,
+        "ops": ops,
+    }
+    if revision:
+        body["expected_revision"] = revision
+    if title:
+        body["title"] = title
+    if rationale:
+        body["rationale"] = rationale
+    if dry_run:
+        body["dry_run"] = True
+
+    from deepcell_cli.errors import APIError
+    from deepcell_cli.revision import raise_if_stale
+
+    try:
+        data = ctx.client.post("/apply-defs-ops", json=body) or {}
+    except APIError as exc:
+        # Same gap as `deepcell edit`: expected_revision is sent, the 409 was
+        # never rendered. See revision.raise_if_stale.
+        raise_if_stale(exc, filename=filename)
+        raise
+
+    if dry_run:
+        # Version-skew guard: a pre-Phase-4 Jingwei API silently drops the
+        # unknown ``dry_run`` field (pydantic ``extra='ignore'``) and performs
+        # a REAL apply — committing the batch. A genuine dry run guarantees a
+        # null ``revision``/``render_plan``/``version_history``; a non-null
+        # revision proves the server ignored the flag and persisted, so we must
+        # NOT print "nothing persisted". Fail loudly instead.
+        committed_rev = data.get("revision")
+        if committed_rev or data.get("render_plan") or data.get("version_history"):
+            echo_error(
+                "server ignored --dry-run (API too old?) — the batch WAS "
+                f"applied{f' at revision {committed_rev}' if committed_rev else ''}. "
+                "Upgrade the Jingwei API to a version that supports dry_run."
+            )
+            raise click.exceptions.Exit(1)
+
+    results = data.get("results") or []
+    errors = data.get("errors") or []
+    # `/apply-defs-ops` is whole-batch atomic: on any op error it returns
+    # success=False and returns BEFORE writing the file, so nothing persisted.
+    # `results` still carries the in-memory successes, and counting them
+    # reported "3 op(s) applied" for a batch that changed nothing — which reads
+    # as "retry only the failed one" when the whole batch has to be re-sent.
+    rolled_back = data.get("success") is False
+    n_ok = 0 if rolled_back else len(results)
+    n_err = len(errors)
+
+    if dry_run and ctx.fmt == "plain":
+        # The generic plain envelope formatter says "N edit(s) applied" —
+        # the wrong verb for a validation-only run where nothing persisted.
+        if n_err:
+            click.echo(f"dry run: {n_ok} op(s) validated, {n_err} error(s) — nothing persisted")
+        else:
+            click.echo(f"dry run: {n_ok} op(s) validated — nothing persisted")
+    else:
+        output(data, ctx.fmt)
+
+    verb = "validated" if dry_run else "applied"
+    if rolled_back:
+        echo_error(
+            f"batch rolled back — {n_err} error(s), nothing was applied "
+            f"(the whole batch must be re-sent, not just the failed op(s))"
+        )
+        _echo_op_errors(errors, total_ops=len(ops))
+    elif n_err:
+        echo_error(f"{n_ok} op(s) {verb}, {n_err} error(s)")
+        _echo_op_errors(errors, total_ops=len(ops))
+    elif ctx.fmt != "plain":
+        if dry_run:
+            echo_success(f"{n_ok} op(s) validated (dry run — nothing persisted)")
+        else:
+            echo_success(f"{n_ok} op(s) {verb}")
+
+    for w in data.get("warnings") or []:
+        echo_warning(w)
+
+    # The fill line for every deck slide this batch touched, measured by the
+    # export service on the write. Findings already printed above as
+    # warnings; this is the per-slide number, so a slide that fits says so.
+    for entry in data.get("fit") or []:
+        fill = entry.get("fill")
+        pct = f"{round(float(fill) * 100)}%" if isinstance(fill, (int, float)) else "?"
+        findings = entry.get("findings") or []
+        if findings:
+            n_error = sum(1 for f in findings if f.get("severity") == "error")
+            state = (
+                f"{n_error} error(s), {len(findings) - n_error} warning(s)"
+                if n_error else f"{len(findings)} warning(s)"
+            )
+        else:
+            state = "divider" if entry.get("divider") else "fits"
+        echo_info(f"Fit: {entry.get('deck_id')}/{entry.get('slide_id')} fill {pct} — {state}")
+
+    # Issue #1180 — literal-wins precedence means a calc does not fan out onto
+    # cells that already hold author literals. The backend reports them per
+    # add_calc op; without this warning the add looks like a clean success and
+    # the blocked cells never recompute.
+    for r in results:
+        details = r.get("details") if isinstance(r, dict) else None
+        shadowed = details.get("shadowed_cells") if isinstance(details, dict) else None
+        if shadowed:
+            item_ref = details.get("itemRef", "?")
+            first = shadowed[0]
+            shown = ", ".join(c.get("contextRef") or "?" for c in shadowed[:5])
+            more = f", … +{len(shadowed) - 5} more" if len(shadowed) > 5 else ""
+            # The --clear example must target the exact cell — a status- or
+            # scenario-tagged literal cleared without its flags removes the
+            # wrong (base) cell (#1185 review finding 4).
+            flags = ""
+            if first.get("statusRef"):
+                flags += f" --status {first['statusRef']}"
+            if first.get("scenarioRef"):
+                flags += f" --scenario {first['scenarioRef']}"
+            echo_warning(
+                f"{len(shadowed)} literal cell(s) shadow the new calc on "
+                f"'{item_ref}' ({shown}{more}) and will NOT recompute — clear "
+                f"them to let the formula govern, e.g. `deepcell edit "
+                f"{filename} {item_ref} {first.get('contextRef')} --clear{flags}`"
+            )
+
+    # A4 — `--status` is documented as strongly recommended but not required
+    # by Click, so an untagged forecast calc lands silently beside tagged
+    # actuals and answers reads meant for them. Warn where that has happened.
+    for r in results:
+        details = r.get("details") if isinstance(r, dict) else None
+        joined = (
+            details.get("untagged_calc_joins_statuses")
+            if isinstance(details, dict) else None
+        )
+        if joined:
+            item_ref = details.get("itemRef", "?")
+            echo_warning(
+                f"the new calc on '{item_ref}' is untagged, but that slot "
+                f"already holds {', '.join(joined)} — an untagged cell answers "
+                f"reads for every status, so the two will compete for one "
+                f"coordinate. Re-add with `--status <id>` to keep them apart."
+            )
+
+    # Destructive ops report what they took with them in `details`, but the
+    # plain envelope prints only "N op(s) applied" — a cascade that purged an
+    # item subtree and 84 value cells read exactly like a no-op rename.
+    # A rolled-back batch deleted nothing, so announcing "84 cells were
+    # deleted — restore them from history" would send the user to undo work
+    # that is still intact.
+    for r in ([] if rolled_back else results):
+        details = r.get("details") if isinstance(r, dict) else None
+        if not isinstance(details, dict):
+            continue
+        target = (
+            details.get("itemId")
+            or details.get("contextId")
+            or details.get("scenarioContextRef")
+            or "?"
+        )
+        removed_ids = details.get("removed") or []
+        if len(removed_ids) > 1:
+            echo_warning(
+                f"Removed {len(removed_ids)} item(s) with '{target}': "
+                + ", ".join(str(i) for i in removed_ids)
+            )
+        values_removed = details.get("values_removed") or 0
+        if values_removed:
+            echo_warning(
+                f"{values_removed} value cell(s) were deleted with '{target}' — "
+                f"restore them from history if this was not intended "
+                f"(`deepcell log` / `deepcell restore`)"
+            )
+        # An overwrite-shape calc reports `replaced_value` with no
+        # `shadowed_cells`: the authored literal is silently OVERWRITTEN by
+        # the recompute rather than shadowing the calc. Storage form does not
+        # enter into it — a flat <Value> literal used to survive and be
+        # reported as shadowed, but #1428 made a recompute address the
+        # coordinate rather than the container.
+        if details.get("replaced_value") is not None and not details.get("shadowed_cells"):
+            echo_warning(
+                f"Authored literal {details['replaced_value']!s} on "
+                f"'{details.get('itemRef', target)}' will be overwritten by the "
+                f"new formula's recompute"
+            )
+
+    # Issue #620 — structural ops are the most common source of orphans
+    # (an item added without being placed on a block, a context not in any
+    # block's contextRefs). `/apply-defs-ops` returns a fresh RenderPlan;
+    # surface its `unrendered_values` here so the user catches the
+    # regression without a follow-up `deepcell lint`.
+    plan = data.get("render_plan") if isinstance(data, dict) else None
+    orphans = plan.get("unrendered_values") if isinstance(plan, dict) else None
+    if orphans:
+        click.echo(_format_unrendered_values_warning(orphans), err=True)
+
+    # Issue #1371 — `status_diagnostics` is in that SAME dict, fetched by that
+    # same line, and used to be dropped. The #620 rationale applies verbatim:
+    # `defs apply` is exactly where a user creates a status clash
+    # (`defs add-calc --status`, `defs update-context --status`), so it is the
+    # moment the warning is due. Before this, the command that CAUSED the clash
+    # said nothing and the only surface that mentioned it was a follow-up
+    # `describe`, in prose, under a heading explicitly marked informational.
+    diagnostics = plan.get("status_diagnostics") if isinstance(plan, dict) else None
+    if diagnostics:
+        click.echo(_format_status_diagnostics_warning(diagnostics), err=True)
+
+    # Issue #1036 — what the builder had to coerce to render the post-edit
+    # document (an out-of-enum @chartType clamped to "bar"). Structural ops are
+    # how those attributes get written, so this
+    # is also where a typo in one first becomes visible; it previously reached
+    # the server log and nowhere else.
+    #
+    # Capped at three. The demo corpus has a document with 88 of these
+    # (`ichiban-ramen-advanced`), and 88 lines after every `defs` command is
+    # noise a user learns to scroll past — which costs the signal the whole
+    # change exists to deliver. `describe` prints the full list under "Export
+    # notes", so the tail has somewhere to be read.
+    coerced = [
+        w for w in (
+            plan.get("conversion_warnings") if isinstance(plan, dict) else None
+        ) or []
+        if isinstance(w, dict) and w.get("message")
+    ]
+    for warning in coerced[:_MAX_CONVERSION_WARNINGS_SHOWN]:
+        echo_warning(str(warning["message"]))
+    if len(coerced) > _MAX_CONVERSION_WARNINGS_SHOWN:
+        echo_warning(
+            f"…and {len(coerced) - _MAX_CONVERSION_WARNINGS_SHOWN} more "
+            f"conversion warning(s) — run `deepcell describe {filename}` "
+            "for the full list"
+        )
+
+    # Eval S1 / R4: a persisted batch that touched calcs changed computed
+    # values — surface the query-back at the moment it is due, with the
+    # calc's own coordinates when the ops carry them.
+    if not dry_run and not rolled_back and not n_err:
+        calc_ops = [o for o in ops if o.get("kind") in _CALC_VALUE_OP_KINDS]
+        if calc_ops:
+            item = context = None
+            for o in calc_ops:
+                defaults = o.get("defaults") or {}
+                item = item or defaults.get("itemId")
+                raw_ctx = defaults.get("contextRef")
+                if not context and isinstance(raw_ctx, str) and raw_ctx.strip():
+                    context = raw_ctx.split(",")[0].strip()
+            echo_query_back_hint(filename, item=item, context=context)
+
+    echo_version_history(data)
+
+    if n_err:
+        raise click.exceptions.Exit(1)
+
+
+# ── Group ───────────────────────────────────────────────────
+
+
+@click.group(cls=_DefsGroup)
+def defs() -> None:
+    """Structural edits: define items, calculations, periods, scenarios.
+
+    \b
+    BUILDING MORE THAN A FEW DEFS? Use `defs apply`. Every add-* below is one
+    round-trip that answers in a couple of hundred bytes; `defs apply` sends up
+    to 100 of them in a single call, atomically, and it accepts the reasoning
+    op kinds too — so structure and argument can land together:
+      deepcell defs apply model.deepcell --ops '[{"kind": "add_item", ...}, ...]'
+    The single add-* commands are for a one-off edit, and for finding out what
+    fields an op takes without writing JSON.
+
+    \b
+    For literal values:    deepcell edit FILE ITEM CTX VALUE
+    For paradigm:          deepcell guide generate/calcs
+    For presentations:     deepcell guide present/layout
+    For HTML decks:        deepcell guide present/decks
+
+    \b
+    Examples:
+      deepcell defs add-calc model.deepcell --item Revenue \\
+          --formula "Revenue[PREVIOUS] * (1 + Revenue_Growth[CURRENT])"
+      deepcell defs add-item model.deepcell --name Gross_Margin --level 2
+      deepcell defs add-context model.deepcell --name FY2027E --status projected --state future
+      deepcell defs apply model.deepcell --ops-file ops.json
+
+    \b
+    Reads:
+      deepcell defs list model.deepcell          # what is defined, by kind
+      deepcell defs show model.deepcell Revenue  # one item + its CalcDefs
+    """
+
+
+# ── Reads ───────────────────────────────────────────────────
+#
+# Every other subcommand here is a mutation, and the reads live under other
+# nouns (`describe` / `query` / `cat`) — so a fresh session reached for the
+# CRUD-symmetric `defs list` / `defs show` and got "No such command" (#1291).
+# `cls=click.Command` on purpose: these are the only defs subcommands that must
+# NOT inherit `--dry-run` from `_DefsCommand`, because they write nothing.
+
+
+def _plain_kv(rows: list[dict], id_field: str, *extra_fields: str) -> str:
+    """Render def rows as one line each: the id, then whatever else is set."""
+    lines = []
+    for row in rows:
+        extras = [
+            f"{key}={row[key]}"
+            for key in extra_fields
+            if row.get(key) not in (None, "", False)
+        ]
+        lines.append(
+            f"  {row.get(id_field) or '?'}"
+            + (f"  ({', '.join(extras)})" if extras else "")
+        )
+    return "\n".join(lines)
+
+
+@defs.command("list", cls=click.Command)
+@click.argument("filename")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def list_defs(ctx: Ctx, filename: str, workspace_slug: str | None) -> None:
+    """List what the document DEFINES: items, calcs, contexts, scenarios, statuses.
+
+    Definitions and ids only — no values. For values use `deepcell query`; for
+    the presentation shape (sheets, blocks) and lint findings use `deepcell
+    describe`; for the raw XML use `deepcell cat`.
+
+    This is the only surface that reports CalcDefs with their `calcId` — the id
+    `defs delete-calc` / `defs update-calc` and `reasoning add-claim
+    --calc-ref` must quote.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    data = ctx.client.post(
+        "/defs/list", json={"workspace_slug": slug, "filename": filename}
+    )
+    if ctx.fmt != "plain" or not isinstance(data, dict):
+        output(data, ctx.fmt)
+        return
+
+    counts = data.get("counts") or {}
+    lines = [
+        f"Defs in {data.get('filename') or filename}: "
+        + ", ".join(f"{n} {kind}" for kind, n in counts.items())
+    ]
+    sections = (
+        ("items", ("item_id", "label", "level", "parent_item", "data_type")),
+        ("calculations",
+         ("calc_id", "item_ref", "formula", "context_refs", "status_ref",
+          "scenario_ref")),
+        ("contexts", ("context_id", "label", "status_ref")),
+        ("scenarios", ("scenario_id", "label", "is_default")),
+        ("statuses", ("status_id", "label", "is_default")),
+    )
+    for kind, fields in sections:
+        rows = data.get(kind) or []
+        if not rows:
+            continue
+        lines += ["", f"{kind.capitalize()} ({counts.get(kind, len(rows))}):",
+                  _plain_kv(rows, *fields)]
+    if data.get("note"):
+        lines += ["", str(data["note"])]
+    print_plain("\n".join(lines))
+
+
+@defs.command("show", cls=click.Command)
+@click.argument("filename")
+@click.argument("item_id")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def show_def(
+    ctx: Ctx, filename: str, item_id: str, workspace_slug: str | None
+) -> None:
+    """Show one item's ItemDef and every CalcDef that governs it.
+
+    Exits non-zero on an unknown itemId — the error carries did-you-mean
+    suggestions rather than an empty-looking success.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    data = ctx.client.post(
+        "/defs/show",
+        json={"workspace_slug": slug, "filename": filename, "item_id": item_id},
+    )
+    if ctx.fmt != "plain" or not isinstance(data, dict):
+        output(data, ctx.fmt)
+        return
+
+    item = data.get("item") or {}
+    lines = [f"Item: {item.get('item_id')}"]
+    for key in ("label", "level", "order", "parent_item", "data_type",
+                "scale", "currency", "unit"):
+        if item.get(key) not in (None, ""):
+            lines.append(f"  {key}: {item[key]}")
+    children = data.get("children") or []
+    if children:
+        lines.append(f"  children: {', '.join(map(str, children))}")
+
+    calcs = data.get("calculations") or []
+    lines.append("")
+    if calcs:
+        # Source order is load-bearing: on a specificity tie the first calc
+        # wins (`deepcell ref op/add_calc` has the rule).
+        lines.append(f"CalcDefs governing it ({len(calcs)}, in source order):")
+        lines.append(_plain_kv(
+            calcs, "calc_id", "formula", "context_refs", "status_ref",
+            "scenario_ref",
+        ))
+    else:
+        lines.append(
+            "CalcDefs governing it: none — this item holds literal values only."
+        )
+    print_plain("\n".join(lines))
+
+
+# ── CalcDef ops ─────────────────────────────────────────────
+
+
+@defs.command("add-calc")
+@click.argument("filename")
+@click.option("--item", "item_id", required=True, help="Item the calc resolves into (itemId).")
+@click.option(
+    "--calc-id",
+    "calc_id",
+    default=None,
+    help=(
+        "Stable calcId for the new calc (e.g. 'calc_stress_low'). Errors if "
+        "the id is already taken. Omit to let the server assign one — but an "
+        "auto id is what `defs delete-calc` and `reasoning add-claim "
+        "--calc-ref` must then quote, so choose your own when the calc has to "
+        "be citable."
+    ),
+)
+@click.option("--formula", required=True, help="Jingwei formula, e.g. \"Revenue[PREVIOUS] * 1.1\".")
+@click.option(
+    "--context",
+    "context_ref",
+    default=None,
+    help=(
+        "Pin calc to one or more contextRefs. Pass a CSV (e.g. "
+        "'FY25,FY26,FY27') to pin a roll-forward chain to several periods in "
+        "one call — omit the seed period so its literal is kept. Omit entirely "
+        "to fan out across every period the item lacks a literal value."
+    ),
+)
+@click.option("--scenario", "scenario_ref", default=None, help="Limit calc to this scenarioRef.")
+@click.option(
+    "--status",
+    "status_ref",
+    default=None,
+    help=(
+        "Pin calc to a statusRef (e.g. 'projected'). Strongly recommended for "
+        "forecast formulas so they coexist with the historical actuals in the "
+        "same item/context slots — without it the projection stores one "
+        "untagged cell that answers every status, leaving the actuals nowhere "
+        "to sit. Not enforced: omitting it succeeds, and the cost shows up "
+        "later as an actual you cannot store."
+    ),
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_calc(
+    ctx: Ctx,
+    filename: str,
+    item_id: str,
+    calc_id: str | None,
+    formula: str,
+    context_ref: str | None,
+    scenario_ref: str | None,
+    status_ref: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a CalculationDefinition (formula). Backend computes the cell.
+
+    Pass --dry-run to pre-flight the formula (parse + cycle check) without
+    writing anything.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    defaults: dict[str, Any] = {"itemId": item_id, "formula": formula}
+    # Key matches CalcDefIntent.calcId (docs/backend-cli-contract.md). Omitted
+    # entirely when unset so the server keeps assigning the id.
+    if calc_id is not None:
+        defaults["calcId"] = calc_id
+    if context_ref is not None:
+        defaults["contextRef"] = context_ref
+    if scenario_ref is not None:
+        defaults["scenarioRef"] = scenario_ref
+    if status_ref is not None:
+        defaults["statusRef"] = status_ref
+    op = {"kind": "add_calc", "defaults": defaults}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("update-calc")
+@click.argument("filename")
+@click.argument("calc_id")
+@click.option("--formula", default=None, help="Replace the formula.")
+@click.option("--context", "context_ref", default=None, help="Change contextRef.")
+@click.option("--scenario", "scenario_ref", default=None, help="Change scenarioRef.")
+@click.option("--status", "status_ref", default=None, help="Change statusRef (e.g. 'projected'). Pass '' to clear.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def update_calc(
+    ctx: Ctx,
+    filename: str,
+    calc_id: str,
+    formula: str | None,
+    context_ref: str | None,
+    scenario_ref: str | None,
+    status_ref: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Patch a CalcDef; only the fields you pass are changed.
+
+    Pass --dry-run to pre-flight the patch (parse + cycle check) without
+    writing anything.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    patch: dict[str, Any] = {}
+    if formula is not None:
+        patch["formula"] = formula
+    if context_ref is not None:
+        patch["contextRef"] = context_ref
+    if scenario_ref is not None:
+        patch["scenarioRef"] = scenario_ref
+    if status_ref is not None:
+        patch["statusRef"] = status_ref
+    if not patch:
+        raise click.UsageError("Provide at least one of --formula / --context / --scenario / --status.")
+    op = {"kind": "update_calc", "calcId": calc_id, "patch": patch}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("delete-calc")
+@click.argument("filename")
+@click.argument("calc_id")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_calc(
+    ctx: Ctx,
+    filename: str,
+    calc_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a CalculationDefinition by calcId."""
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "delete_calc", "calcId": calc_id}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+# ── Item ops ────────────────────────────────────────────────
+
+
+@defs.command("add-item")
+@click.argument("filename")
+@click.option("--name", required=True, help="Item name (itemId basis).")
+@click.option(
+    "--label",
+    default=None,
+    help="Display label (e.g. 'Gross Margin %'); defaults to a humanized form "
+         "of --name. Written as one <Label lang=\"en\">: no typed op adds a "
+         "second locale, so a bilingual item (en + zh) is seeded in the "
+         "initial `deepcell write`.",
+)
+@click.option("--level", type=int, default=None, help="Hierarchy level (0-3).")
+@click.option("--parent", "parent_item_id", default=None, help="Parent itemId (omit for root).")
+@click.option("--index", type=int, default=None, help="Position among siblings (omit to append at end).")
+@click.option(
+    "--order",
+    type=int,
+    default=None,
+    help="Explicit @order (must be unique; presentation blocks address rows by order ranges). Overrides --index placement.",
+)
+@click.option(
+    "--order-mode",
+    "order_mode",
+    type=click.Choice(["append"]),
+    default=None,
+    help="'append' assigns max(existing orders) + 10 — no need to know which orders are taken. Mutually exclusive with --order; overrides --index.",
+)
+@click.option(
+    "--data-type",
+    "data_type",
+    default=None,
+    callback=_warn_data_type,
+    help="DataType element (e.g. 'monetary', 'percentage', 'number').",
+)
+@click.option("--unit", default=None, help="Unit element (e.g. '%', 'hours', 'tonnes').")
+@click.option("--scale", type=int, default=None, help="Scale element (units multiplier exponent).")
+@click.option("--currency", default=None, help="Currency element (ISO code, e.g. 'USD').")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_item(
+    ctx: Ctx,
+    filename: str,
+    name: str,
+    label: str | None,
+    level: int | None,
+    parent_item_id: str | None,
+    index: int | None,
+    order: int | None,
+    order_mode: str | None,
+    data_type: str | None,
+    unit: str | None,
+    scale: int | None,
+    currency: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add an ItemDefinition (no value)."""
+    slug = workspace_slug or ctx.require_workspace()
+    defaults: dict[str, Any] = {"name": name}
+    if label is not None:
+        defaults["label"] = label
+    if level is not None:
+        defaults["level"] = level
+    if parent_item_id is not None:
+        defaults["parentItemId"] = parent_item_id
+    if order is not None:
+        defaults["order"] = order
+    if order_mode is not None:
+        defaults["orderMode"] = order_mode
+    if data_type is not None:
+        defaults["dataType"] = data_type
+    if unit is not None:
+        defaults["unit"] = unit
+    if scale is not None:
+        defaults["scale"] = scale
+    if currency is not None:
+        defaults["currency"] = currency
+    # AddItemOp carries parentItemId in two places by design:
+    # - top-level → which parent's children list to insert into (insertion site)
+    # - defaults  → the new item's @parentItem attribute
+    # They're always the same in practice; the backend deduplicates.
+    op: dict[str, Any] = {"kind": "add_item", "defaults": defaults}
+    if index is not None:
+        op["index"] = index
+    if parent_item_id is not None:
+        op["parentItemId"] = parent_item_id
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("update-item")
+@click.argument("filename")
+@click.argument("item_id")
+@click.option(
+    "--name",
+    default=None,
+    help="Rename the itemId; references cascade. Equivalent to `defs rename-item`.",
+)
+@click.option(
+    "--label",
+    "new_label",
+    default=None,
+    help="Change the item's DISPLAY LABEL (emits set_item_label). The itemId is "
+         "untouched — use `defs rename-item` to change the identifier. Rewrites "
+         "the text of the item's first <Label> and keeps its lang; other "
+         "locales are left alone and cannot be added here.",
+)
+@click.option("--level", type=int, default=None, help="Change hierarchy level.")
+@click.option("--parent", "parent_item_id", default=None, help="Change parent itemId.")
+@click.option("--clear-parent", is_flag=True, help="Make item a root (explicit-null parentItemId).")
+@click.option(
+    "--data-type",
+    "data_type",
+    default=None,
+    callback=_warn_data_type,
+    help="Set DataType element (e.g. 'monetary', 'percentage', 'number').",
+)
+@click.option("--unit", default=None, help="Set Unit element (e.g. '%', 'hours', 'tonnes').")
+@click.option("--scale", type=int, default=None, help="Set Scale element.")
+@click.option("--currency", default=None, help="Set Currency element (ISO code).")
+@click.option(
+    "--clear-data-type",
+    is_flag=True,
+    help="Remove the DataType element (explicit-null).",
+)
+@click.option("--clear-unit", is_flag=True, help="Remove the Unit element (explicit-null).")
+@click.option(
+    "--clear-scale",
+    is_flag=True,
+    help="Remove the Scale element (explicit-null).",
+)
+@click.option(
+    "--clear-currency",
+    is_flag=True,
+    help="Remove the Currency element (explicit-null).",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def update_item(
+    ctx: Ctx,
+    filename: str,
+    item_id: str,
+    name: str | None,
+    new_label: str | None,
+    level: int | None,
+    parent_item_id: str | None,
+    clear_parent: bool,
+    data_type: str | None,
+    unit: str | None,
+    scale: int | None,
+    currency: str | None,
+    clear_data_type: bool,
+    clear_unit: bool,
+    clear_scale: bool,
+    clear_currency: bool,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Patch an item; only fields you pass are sent."""
+    slug = workspace_slug or ctx.require_workspace()
+    if parent_item_id is not None and clear_parent:
+        raise click.UsageError("--parent and --clear-parent are mutually exclusive.")
+    if data_type is not None and clear_data_type:
+        raise click.UsageError("--data-type and --clear-data-type are mutually exclusive.")
+    if unit is not None and clear_unit:
+        raise click.UsageError("--unit and --clear-unit are mutually exclusive.")
+    if scale is not None and clear_scale:
+        raise click.UsageError("--scale and --clear-scale are mutually exclusive.")
+    if currency is not None and clear_currency:
+        raise click.UsageError("--currency and --clear-currency are mutually exclusive.")
+    patch: dict[str, Any] = {}
+    if name is not None:
+        patch["name"] = name
+    if level is not None:
+        patch["level"] = level
+    if parent_item_id is not None:
+        patch["parentItemId"] = parent_item_id
+    elif clear_parent:
+        patch["parentItemId"] = None
+    if data_type is not None:
+        patch["dataType"] = data_type
+    elif clear_data_type:
+        patch["dataType"] = None
+    if unit is not None:
+        patch["unit"] = unit
+    elif clear_unit:
+        patch["unit"] = None
+    if scale is not None:
+        patch["scale"] = scale
+    elif clear_scale:
+        patch["scale"] = None
+    if currency is not None:
+        patch["currency"] = currency
+    elif clear_currency:
+        patch["currency"] = None
+    if not patch and new_label is None:
+        raise click.UsageError(
+            "Provide at least one of --label / --name / --level / --parent / "
+            "--clear-parent / --data-type / --unit / --scale / --currency / "
+            "--clear-data-type / --clear-unit / --clear-scale / --clear-currency."
+        )
+    # UpdateItemPatch has no `label` field, and `set_item_label` had no CLI
+    # command and no guide mention — so an item's display label was
+    # uneditable after creation by any documented path.
+    #
+    # Ordering rule for this batch: every op addresses the item by its
+    # CURRENT id, so ops that only read the id (set_item_label) must run
+    # before the op that can change it (`--name` renames inside the patch).
+    # The reverse order made the label op hit item_not_found after the
+    # rename, and atomicity rolled back the entire batch.
+    ops: list[dict[str, Any]] = []
+    if new_label is not None:
+        ops.append({
+            "kind": "set_item_label", "itemId": item_id, "newLabel": new_label,
+        })
+    if patch:
+        ops.append({"kind": "update_item", "itemId": item_id, "patch": patch})
+    _apply(ctx, slug, filename, ops, revision=revision)
+
+
+@defs.command("rename-item")
+@click.argument("filename")
+@click.argument("item_id")
+@click.argument("new_name")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def rename_item(
+    ctx: Ctx,
+    filename: str,
+    item_id: str,
+    new_name: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Rename an item's stable identifier; references cascade."""
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "rename_item", "itemId": item_id, "newName": new_name}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("delete-item")
+@click.argument("filename")
+@click.argument("item_id")
+@click.option("--cascade", is_flag=True, help="Also delete all descendants.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_item(
+    ctx: Ctx,
+    filename: str,
+    item_id: str,
+    cascade: bool,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete an item, and with --cascade its descendants too.
+
+    Value cells keyed to the deleted item are purged with it. Without
+    --cascade the item's direct children survive: they are re-parented to the
+    deleted item's parent and their levels recomputed.
+
+    Refused while a Calculation, formula, sensitivity block, or Reasoning
+    anchor still references the item — repoint those first. Pass --dry-run to
+    find out which references block the delete without changing anything.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    kind = "delete_item_with_descendants" if cascade else "delete_item"
+    op = {"kind": kind, "itemId": item_id}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("reorder-item")
+@click.argument("filename")
+@click.argument("item_id")
+@click.option(
+    "--to-index",
+    "to_index",
+    type=int,
+    required=True,
+    help=(
+        "Final 0-based position among the item's siblings. 0 = first. Lets you "
+        "place a referenced item before its referencer (avoids a forward "
+        "item-order reference)."
+    ),
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def reorder_item(
+    ctx: Ctx,
+    filename: str,
+    item_id: str,
+    to_index: int,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Move an item to a new position among its siblings (final-position index)."""
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "reorder_items", "itemId": item_id, "toIndex": to_index}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+# ── Period / Scenario / Status ops ─────────────────────────
+
+
+def _add_context_impl(
+    ctx: Ctx,
+    filename: str,
+    name: str | None,
+    status_ref: str | None,
+    context_ref: str | None,
+    kind: str | None,
+    state: str | None,
+    as_of: str | None,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+    op_kind: str = "add_context",
+) -> None:
+    """Shared implementation for `add-context` / `add-period` commands.
+
+    Defaults to the canonical `add_context` op kind (B13). Pass
+    `op_kind="add_period"` to send the legacy on-wire literal — preserved as a
+    one-release deprecation alias.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    defaults: dict[str, Any] = {}
+    if name is not None:
+        defaults["name"] = name
+    if status_ref is not None:
+        defaults["status"] = status_ref
+    if context_ref is not None:
+        defaults["contextRef"] = context_ref
+    if kind is not None:
+        defaults["kind"] = kind
+    if state is not None:
+        defaults["state"] = state
+    if as_of is not None:
+        defaults["asOf"] = as_of
+    op: dict[str, Any] = {"kind": op_kind, "defaults": defaults}
+    if index is not None:
+        op["index"] = index
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("add-period")
+@click.argument("filename")
+@click.option(
+    "--name",
+    help="The period IDENTIFIER (@contextId), e.g. FY2027E — not a display "
+         "label. Must satisfy the reference-id grammar. Set the readable name "
+         "afterwards with `defs update-context --label`.",
+)
+@click.option("--status", "status_ref", default=None, help="statusRef (e.g. 'projected').")
+@click.option("--context", "context_ref", default=None, help="Explicit contextRef (else server-assigned).")
+@click.option(
+    "--kind",
+    default=None,
+    help=(
+        "Context kind. Omit (or pass 'period' / a temporal alias like 'time' "
+        "/ 'year' / 'annual' / 'fy') for time columns; pass e.g. 'program', "
+        "'segment', 'fund', 'region', 'entity', 'product', 'other' (or any "
+        "snake_case label, ≤32 chars) for non-temporal axes. Always written "
+        "as @kind on the <Context> element."
+    ),
+)
+@click.option(
+    "--state",
+    default=None,
+    help=(
+        "Period state: closed | open | future. This is what says whether the "
+        "period is over — the question the A/E suffix on a context id used to "
+        "answer by accident. Only meaningful for --kind period."
+    ),
+)
+@click.option(
+    "--as-of",
+    "as_of",
+    default=None,
+    help=(
+        "ISO YYYY-MM-DD the period's numbers are stated as of. Documentation "
+        "and lint input only; never consulted when rendering."
+    ),
+)
+@click.option("--index", type=int, default=None, help="Position in contexts list (omit to append at end).")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_period(
+    ctx: Ctx,
+    filename: str,
+    name: str | None,
+    status_ref: str | None,
+    context_ref: str | None,
+    kind: str | None,
+    state: str | None,
+    as_of: str | None,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a ContextDefinition (period, or non-temporal axis member).
+
+    Deprecated alias for `defs add-context`, which does the same thing and is
+    the name to use. This one still works, but may be removed.
+    """
+    _add_context_impl(
+        ctx, filename, name, status_ref, context_ref, kind, state, as_of, index,
+        revision, workspace_slug,
+        op_kind="add_period",
+    )
+
+
+@defs.command("add-context")
+@click.argument("filename")
+@click.option(
+    "--name",
+    help="The context IDENTIFIER (@contextId), e.g. 'Low_Rent' — not a display "
+         "label. Must satisfy the reference-id grammar. Set the readable name "
+         "afterwards with `defs update-context --label`.",
+)
+@click.option("--status", "status_ref", default=None, help="statusRef (optional).")
+@click.option("--context", "context_ref", default=None, help="Explicit contextRef (else server-assigned).")
+@click.option(
+    "--kind",
+    default=None,
+    help=(
+        "Context kind. Omit (or 'period' / temporal alias) for time columns; "
+        "pass 'program', 'segment', 'fund', 'region', 'entity', 'product', "
+        "'other' (or any snake_case label, ≤32 chars) for non-temporal axes. "
+        "Always written as @kind on the <Context> element."
+    ),
+)
+@click.option(
+    "--state",
+    default=None,
+    help=(
+        "Period state: closed | open | future. This is what says whether the "
+        "period is over — the question the A/E suffix on a context id used to "
+        "answer by accident. Only meaningful for --kind period."
+    ),
+)
+@click.option(
+    "--as-of",
+    "as_of",
+    default=None,
+    help=(
+        "ISO YYYY-MM-DD the period's numbers are stated as of. Documentation "
+        "and lint input only; never consulted when rendering."
+    ),
+)
+@click.option("--index", type=int, default=None, help="Position in contexts list (omit to append at end).")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_context(
+    ctx: Ctx,
+    filename: str,
+    name: str | None,
+    status_ref: str | None,
+    context_ref: str | None,
+    kind: str | None,
+    state: str | None,
+    as_of: str | None,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a ContextDefinition — a period, or a non-temporal axis member.
+
+    Contexts are the columns a value can land in. Use this for both temporal
+    axes (`--kind period`, the default) and non-temporal ones
+    (`--kind program|segment|fund|other`). `defs add-period` is a deprecated
+    alias for this command.
+    """
+    _add_context_impl(
+        ctx, filename, name, status_ref, context_ref, kind, state, as_of, index,
+        revision, workspace_slug,
+        op_kind="add_context",
+    )
+
+
+@defs.command("delete-context")
+@click.argument("filename")
+@click.argument("context_ref")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_context(
+    ctx: Ctx,
+    filename: str,
+    context_ref: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a Context (period or non-temporal axis member).
+
+    Refused while a Calculation, Presentation Block, or Reasoning anchor still
+    references the context — reassign those first. Values in the deleted
+    context go with it. Pass --dry-run to see what would happen first.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "delete_context", "contextRef": context_ref}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("rename-context")
+@click.argument("filename")
+@click.argument("context_ref")
+@click.argument("new_name")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def rename_context(
+    ctx: Ctx,
+    filename: str,
+    context_ref: str,
+    new_name: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Rename a Context's @contextId; references cascade.
+
+    Values, Calculations, Presentation Blocks, and Reasoning anchors are all
+    repointed, so nothing is left dangling.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "rename_context", "contextRef": context_ref, "newName": new_name}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("rename-dimension")
+@click.argument("filename")
+@click.argument("dimension_id")
+@click.argument("new_name")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def rename_dimension(
+    ctx: Ctx,
+    filename: str,
+    dimension_id: str,
+    new_name: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Rename a custom Dimension's @dimensionId. Cascades through every
+    @customDimensions carrier (Values, ItemGroups, Calculations) and formula
+    interiors.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "rename_dimension", "dimensionId": dimension_id, "newName": new_name}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("rename-member")
+@click.argument("filename")
+@click.argument("dimension_id")
+@click.argument("member_id")
+@click.argument("new_name")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def rename_member(
+    ctx: Ctx,
+    filename: str,
+    dimension_id: str,
+    member_id: str,
+    new_name: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Rename one Member's @memberId within a custom Dimension. The dimension
+    id disambiguates (member ids are not globally unique). Cascades through
+    every @customDimensions carrier and formula interiors.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "rename_member",
+        "dimensionId": dimension_id,
+        "memberId": member_id,
+        "newName": new_name,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("reorder-contexts")
+@click.argument("filename")
+@click.argument("context_ref")
+@click.argument("to_index", type=int)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def reorder_contexts(
+    ctx: Ctx,
+    filename: str,
+    context_ref: str,
+    to_index: int,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Move a Context to a new position in the contexts list."""
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "reorder_contexts", "contextRef": context_ref, "toIndex": to_index}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("update-context")
+@click.argument("filename")
+@click.argument("context_ref")
+@click.option(
+    "--name",
+    default=None,
+    help="Rename the contextId; references cascade. NOT the display name — "
+         "see --label.",
+)
+@click.option(
+    "--label",
+    "new_label",
+    default=None,
+    help="Change the context's DISPLAY LABEL (emits set_context_label). The "
+         "contextId is untouched — use --name to change the identifier.",
+)
+@click.option("--status", "status_ref", default=None, help="Set statusRef.")
+@click.option("--clear-status", is_flag=True, help="Clear statusRef (explicit-null).")
+@click.option(
+    "--kind",
+    default=None,
+    help=(
+        "Context kind. Omit / null / 'period' / temporal alias collapses to "
+        "canonical 'period'; any other snake_case label marks a non-temporal "
+        "context. Always written to @kind."
+    ),
+)
+@click.option(
+    "--state",
+    default=None,
+    help=(
+        "Period state: closed | open | future. This is what says whether the "
+        "period is over — the question the A/E suffix on a context id used to "
+        "answer by accident. Only meaningful for --kind period."
+    ),
+)
+@click.option(
+    "--as-of",
+    "as_of",
+    default=None,
+    help=(
+        "ISO YYYY-MM-DD the period's numbers are stated as of. Documentation "
+        "and lint input only; never consulted when rendering."
+    ),
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def update_context(
+    ctx: Ctx,
+    filename: str,
+    context_ref: str,
+    name: str | None,
+    new_label: str | None,
+    status_ref: str | None,
+    clear_status: bool,
+    kind: str | None,
+    state: str | None,
+    as_of: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Patch a Context's name / status / kind; only fields you pass are sent."""
+    slug = workspace_slug or ctx.require_workspace()
+    if status_ref is not None and clear_status:
+        raise click.UsageError("--status and --clear-status are mutually exclusive.")
+    patch: dict[str, Any] = {}
+    if name is not None:
+        patch["name"] = name
+    if status_ref is not None:
+        patch["status"] = status_ref
+    elif clear_status:
+        patch["status"] = None
+    if kind is not None:
+        patch["kind"] = kind
+    # An empty string is an explicit clear, so these test `is not None` rather
+    # than truthiness — `--state ''` must reach the server as a null.
+    if state is not None:
+        patch["state"] = state or None
+    if as_of is not None:
+        patch["asOf"] = as_of or None
+    if not patch and new_label is None:
+        raise click.UsageError(
+            "Provide at least one of --label / --name / --status / "
+            "--clear-status / --kind / --state / --as-of."
+        )
+    # Label op first: both address the context by its CURRENT id, and --name
+    # inside the patch can change it. See `defs update-item` for the same rule.
+    ops: list[dict[str, Any]] = []
+    if new_label is not None:
+        ops.append({
+            "kind": "set_context_label", "contextRef": context_ref,
+            "newLabel": new_label,
+        })
+    if patch:
+        ops.append({"kind": "update_context", "contextRef": context_ref, "patch": patch})
+    _apply(ctx, slug, filename, ops, revision=revision)
+
+
+@defs.command("add-scenario")
+@click.argument("filename")
+@click.option(
+    "--name",
+    help="The scenario IDENTIFIER (@scenarioId), e.g. 'Bull' — not a display "
+         "label. Must satisfy the reference-id grammar. Set the readable name "
+         "afterwards with `defs update-scenario --label`.",
+)
+@click.option(
+    "--base",
+    "base_scenario_ref",
+    default=None,
+    hidden=True,
+    help="(removed) @baseScenarioRef no longer exists — see `deepcell guide revise/scenarios`.",
+)
+@click.option(
+    "--context",
+    "context_ref",
+    default=None,
+    help="The scenario IDENTIFIER (@scenarioId) under the op's wire name, "
+         "contextRef — the same thing as --name, not a period. Legacy "
+         "spelling; if both are given, --context wins.",
+)
+@click.option(
+    "--is-default",
+    "is_default",
+    is_flag=True,
+    default=False,
+    help="Mark as the document's default scenario — clears @isDefault from every other scenario.",
+)
+@click.option("--index", type=int, default=None, help="Position (omit to append at end).")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_scenario(
+    ctx: Ctx,
+    filename: str,
+    name: str | None,
+    base_scenario_ref: str | None,
+    context_ref: str | None,
+    is_default: bool,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a ScenarioDefinition."""
+    if base_scenario_ref is not None:
+        raise click.UsageError(
+            "--base was removed: @baseScenarioRef was dead data the calc engine "
+            "never read, dropped alongside issue #505 (the backend silently "
+            "ignored this flag). Every scenario implicitly shares the base "
+            "model's values; make it diverge with VariableOverride elements — "
+            "see `deepcell guide revise/scenarios`."
+        )
+    slug = workspace_slug or ctx.require_workspace()
+    defaults: dict[str, Any] = {}
+    if name is not None:
+        defaults["name"] = name
+    if context_ref is not None:
+        defaults["contextRef"] = context_ref
+    if is_default:
+        defaults["is_default"] = True
+    op: dict[str, Any] = {"kind": "add_scenario", "defaults": defaults}
+    if index is not None:
+        op["index"] = index
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("add-status")
+@click.argument("filename")
+@click.option(
+    "--name",
+    help="The status IDENTIFIER (@statusId), e.g. 'Forecast' — not a display "
+         "label. Must satisfy the reference-id grammar. Set the readable name "
+         "afterwards with `defs update-status --label`.",
+)
+@click.option(
+    "--ref",
+    "status_ref",
+    default=None,
+    help="The status IDENTIFIER (@statusId) under the op's wire name, "
+         "statusRef — the same thing as --name. If both are given, --ref "
+         "wins.",
+)
+@click.option(
+    "--color",
+    default=None,
+    hidden=True,
+    help="(removed) color is a FormatDefinitions concern — see `deepcell defs add-format`.",
+)
+@click.option(
+    "--is-default",
+    "is_default",
+    is_flag=True,
+    default=False,
+    help="Mark as the document's default status — clears @isDefault from every other status.",
+)
+@click.option(
+    "--archetype",
+    default=None,
+    help=(
+        "What this status MEANS: actual | preliminary | restated | estimate | "
+        "guidance | consensus | forecast | budget | plan | target. Its "
+        "realized/expected nature is derived from it. Omitting it leaves the "
+        "meaning to be guessed from the id's spelling — see `deepcell ref status`."
+    ),
+)
+@click.option(
+    "--assurance",
+    default=None,
+    help="Optional refinement: audited | reviewed | unaudited.",
+)
+@click.option(
+    "--authority",
+    default=None,
+    help="Optional refinement — who asserted the number: reported | derived | "
+         "guidance | consensus | third_party.",
+)
+@click.option("--index", type=int, default=None, help="Position (omit to append at end).")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_status(
+    ctx: Ctx,
+    filename: str,
+    name: str | None,
+    status_ref: str | None,
+    color: str | None,
+    is_default: bool,
+    archetype: str | None,
+    assurance: str | None,
+    authority: str | None,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a StatusDefinition."""
+    if color is not None:
+        raise click.UsageError(
+            "--color was removed: @color on <Status> was dropped alongside "
+            "issue #506 (the backend silently ignored this flag). Visual color "
+            "is a FormatDefinitions concern — add a rule with font_color / "
+            "background_color via `deepcell defs add-format` or `deepcell defs "
+            "set-format`; see `deepcell ref format`."
+        )
+    slug = workspace_slug or ctx.require_workspace()
+    defaults: dict[str, Any] = {}
+    if name is not None:
+        defaults["name"] = name
+    if status_ref is not None:
+        defaults["statusRef"] = status_ref
+    if is_default:
+        defaults["is_default"] = True
+    for field, value in (
+        ("archetype", archetype),
+        ("assurance", assurance),
+        ("authority", authority),
+    ):
+        if value is not None:
+            defaults[field] = value
+    op: dict[str, Any] = {"kind": "add_status", "defaults": defaults}
+    if index is not None:
+        op["index"] = index
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+# ── Header / Metadata ops ──────────────────────────────────
+
+
+@defs.group("header")
+def header() -> None:
+    """Edit <Metadata><Property> entries (title, author, precision, ...).
+
+    \b
+    Examples:
+      deepcell defs header set model.deepcell title "Acme DCF Q3"
+      deepcell defs header set model.deepcell decimal_places 12 --type number
+      deepcell defs header unset model.deepcell author
+    """
+
+
+@header.command("set", cls=_DefsNegativeNumberCommand)
+@click.argument("filename")
+@click.argument("key")
+@click.argument("value")
+@click.option(
+    "--type",
+    "prop_type",
+    type=click.Choice(["string", "number", "boolean", "datetime"]),
+    default="string",
+    help="Property type tag written into <Property @type>.",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def header_set(
+    ctx: Ctx,
+    filename: str,
+    key: str,
+    value: str,
+    prop_type: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Set or replace a Header property."""
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "set_header_property",
+        "key": key,
+        "value": value,
+        "type": prop_type,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@header.command("unset")
+@click.argument("filename")
+@click.argument("key")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def header_unset(
+    ctx: Ctx,
+    filename: str,
+    key: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a Header property."""
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "delete_header_property", "key": key}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+# ── Format ops (B15) ───────────────────────────────────────
+
+
+def _parse_rule_kvs(rule_strs: tuple[str, ...]) -> list[dict[str, Any]]:
+    """Parse repeated --rule "target=...,bg_color=...,font_color=..." into
+    a list of rule dicts. Returns raw dicts ready for the wire (snake_case
+    keys match the backend Pydantic model).
+
+    The kv separator is ``;``. Within a value, commas are allowed (so an
+    Excel-style ``number_format=#,##0`` round-trips intact). For
+    back-compat with the previous comma-separated form, a string that
+    contains no ``;`` is parsed by splitting on ``,`` *only if* doing so
+    yields valid ``key=value`` pairs that don't accidentally split a
+    numberFormat — namely, no pair starts with a non-letter (Excel
+    patterns like ``#,##0`` start with ``#``). If the comma-split would
+    produce an invalid pair, we treat the whole string as a single value.
+    """
+    rules: list[dict[str, Any]] = []
+    for raw in rule_strs:
+        rule: dict[str, Any] = {}
+        pairs: list[str]
+        if ";" in raw:
+            pairs = [p.strip() for p in raw.split(";") if p.strip()]
+        else:
+            # Comma-split, but coalesce fragments that don't look like
+            # 'key=value' (they belong to a value containing commas, e.g.
+            # the trailing '##0' of '#,##0').
+            raw_parts = [p.strip() for p in raw.split(",") if p.strip()]
+            coalesced: list[str] = []
+            for part in raw_parts:
+                if "=" in part and re.match(r"^[A-Za-z_][A-Za-z0-9_]*\s*=", part):
+                    coalesced.append(part)
+                elif coalesced:
+                    coalesced[-1] = coalesced[-1] + "," + part
+                else:
+                    coalesced.append(part)
+            pairs = coalesced
+        for p in pairs:
+            if "=" not in p:
+                raise click.UsageError(
+                    f"--rule entry {p!r} must be 'key=value'"
+                )
+            k, v = p.split("=", 1)
+            rule[k.strip()] = v.strip()
+        if "target" not in rule:
+            raise click.UsageError(
+                f"--rule entry {raw!r} is missing the required 'target' key"
+            )
+        rules.append(rule)
+    return rules
+
+
+# ── Scenario / status lifecycle ────────────────────────────
+#
+# `add-scenario` and `add-status` shipped alone: every other definition
+# family (items, contexts, calcs, formats) has delete / rename / update, so
+# a scenario or status could be created from the CLI and then never fixed.
+
+
+@defs.command("delete-scenario")
+@click.argument("filename")
+@click.argument("scenario_ref")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_scenario(
+    ctx: Ctx,
+    filename: str,
+    scenario_ref: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a ScenarioDefinition by its contextRef.
+
+    Values carrying this scenario go with it. Pass --dry-run first to see
+    what the delete would take with it.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "delete_scenario", "scenarioContextRef": scenario_ref}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("rename-scenario")
+@click.argument("filename")
+@click.argument("scenario_ref")
+@click.argument("new_name")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def rename_scenario(
+    ctx: Ctx,
+    filename: str,
+    scenario_ref: str,
+    new_name: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Rename a scenario's IDENTIFIER (@scenarioId); references cascade.
+
+    NOT the display name — this rewrites `@scenarioRef` on Values and every
+    sensitivity block's `@scenarioRefs` CSV, and NEW_NAME must satisfy the
+    reference-id grammar (letters, digits, `_`, `.`). For the human-readable
+    name use `deepcell defs update-scenario --label`.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "rename_scenario",
+        "scenarioContextRef": scenario_ref,
+        "newName": new_name,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("update-scenario")
+@click.argument("filename")
+@click.argument("scenario_ref")
+@click.option(
+    "--name",
+    default=None,
+    help="Rename the scenarioId; references cascade. Equivalent to "
+         "`defs rename-scenario`. NOT the display name — see --label.",
+)
+@click.option(
+    "--label",
+    "new_label",
+    default=None,
+    help="Change the scenario's DISPLAY LABEL (emits set_scenario_label). The "
+         "scenarioId is untouched — use --name to change the identifier.",
+)
+@click.option(
+    "--is-default/--no-is-default",
+    "is_default",
+    default=None,
+    help=(
+        "Make this the document's default scenario (clears @isDefault from "
+        "every other scenario), or strip the flag from this one."
+    ),
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def update_scenario(
+    ctx: Ctx,
+    filename: str,
+    scenario_ref: str,
+    name: str | None,
+    new_label: str | None,
+    is_default: bool | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Patch a scenario; only the fields you pass are sent."""
+    slug = workspace_slug or ctx.require_workspace()
+    patch: dict[str, Any] = {}
+    if name is not None:
+        patch["name"] = name
+    if is_default is not None:
+        patch["is_default"] = is_default
+    if not patch and new_label is None:
+        raise click.UsageError(
+            "Provide at least one of --label / --name / --is-default / "
+            "--no-is-default."
+        )
+    # Label op first — same ordering rule as `defs update-item`.
+    ops: list[dict[str, Any]] = []
+    if new_label is not None:
+        ops.append({
+            "kind": "set_scenario_label", "scenarioContextRef": scenario_ref,
+            "newLabel": new_label,
+        })
+    if patch:
+        ops.append({
+            "kind": "update_scenario",
+            "scenarioContextRef": scenario_ref,
+            "patch": patch,
+        })
+    _apply(ctx, slug, filename, ops, revision=revision)
+
+
+@defs.command("reorder-scenarios")
+@click.argument("filename")
+@click.argument("scenario_ref")
+@click.option(
+    "--to-index",
+    "to_index",
+    type=click.IntRange(min=0),
+    required=True,
+    help="Final 0-based position among the scenarios. 0 = first.",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def reorder_scenarios(
+    ctx: Ctx,
+    filename: str,
+    scenario_ref: str,
+    to_index: int,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Move a scenario to a new position in the scenario list."""
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "reorder_scenarios",
+        "scenarioContextRef": scenario_ref,
+        "toIndex": to_index,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("delete-status")
+@click.argument("filename")
+@click.argument("status_ref")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_status(
+    ctx: Ctx,
+    filename: str,
+    status_ref: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a StatusDefinition by its statusRef.
+
+    Statuses partition Values (actual vs budget vs forecast), so deleting
+    one affects every cell filed under it — run --dry-run first.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "delete_status", "statusRef": status_ref}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("rename-status")
+@click.argument("filename")
+@click.argument("status_ref")
+@click.argument("new_name")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def rename_status(
+    ctx: Ctx,
+    filename: str,
+    status_ref: str,
+    new_name: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Change a status's IDENTIFIER (@statusId); references cascade.
+
+    NEW_NAME must be a valid reference id (letters, digits, '_' or '.'), and
+    every @statusRef in the document is rewritten to match — contexts, values,
+    item groups, calcs, block statusRefs, reasoning anchors, and #status tokens
+    inside formulas. To change the human-readable name shown in the UI, use
+    `defs update-status --label` instead; it touches one element's text.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "rename_status",
+        "statusRef": status_ref,
+        "newName": new_name,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("update-status")
+@click.argument("filename")
+@click.argument("status_ref")
+@click.option(
+    "--name",
+    default=None,
+    help="Rename the statusId; references cascade. Equivalent to "
+         "`defs rename-status`. NOT the display name — see --label.",
+)
+@click.option(
+    "--label",
+    "new_label",
+    default=None,
+    help="Change the status's DISPLAY LABEL (emits set_status_label). The "
+         "statusId is untouched — use --name to change the identifier.",
+)
+@click.option(
+    "--is-default/--no-is-default",
+    "is_default",
+    default=None,
+    help=(
+        "Make this the document's default status (clears @isDefault from "
+        "every other status), or strip the flag from this one."
+    ),
+)
+@click.option(
+    "--archetype",
+    default=None,
+    help=(
+        "What this status MEANS: actual | preliminary | restated | estimate | "
+        "guidance | consensus | forecast | budget | plan | target. "
+        "Pass an empty string to clear it (and fall back to inference)."
+    ),
+)
+@click.option("--assurance", default=None, help="audited | reviewed | unaudited.")
+@click.option(
+    "--authority",
+    default=None,
+    help="reported | derived | guidance | consensus | third_party.",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def update_status(
+    ctx: Ctx,
+    filename: str,
+    status_ref: str,
+    name: str | None,
+    new_label: str | None,
+    is_default: bool | None,
+    archetype: str | None,
+    assurance: str | None,
+    authority: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Patch a status; only the fields you pass are sent."""
+    slug = workspace_slug or ctx.require_workspace()
+    patch: dict[str, Any] = {}
+    if name is not None:
+        patch["name"] = name
+    if is_default is not None:
+        patch["is_default"] = is_default
+    # An empty string is an explicit clear, which is why these test `is not
+    # None` rather than truthiness — `--archetype ''` must reach the server as
+    # a null so the attribute is stripped.
+    for field, value in (
+        ("archetype", archetype),
+        ("assurance", assurance),
+        ("authority", authority),
+    ):
+        if value is not None:
+            patch[field] = value or None
+    if not patch and new_label is None:
+        raise click.UsageError(
+            "Provide at least one of --label / --name / --is-default / "
+            "--no-is-default / --archetype / --assurance / --authority."
+        )
+    # `UpdateStatusPatch` has no `label` field and `patch.name` renames the ID,
+    # so a status's display label was uneditable by any path until
+    # `set_status_label` — see that op's docstring.
+    #
+    # Same ordering rule as `defs update-item`: both ops address the status by
+    # its CURRENT id, so the label op (which only reads the id) must run before
+    # the op that can change it. Reversed, the label op hits status_not_found
+    # after the rename and atomicity rolls back the whole batch.
+    ops: list[dict[str, Any]] = []
+    if new_label is not None:
+        ops.append({
+            "kind": "set_status_label", "statusRef": status_ref,
+            "newLabel": new_label,
+        })
+    if patch:
+        ops.append({"kind": "update_status", "statusRef": status_ref, "patch": patch})
+    _apply(ctx, slug, filename, ops, revision=revision)
+
+
+@defs.command("add-format")
+@click.argument("filename")
+@click.argument("format_id")
+@click.option(
+    "--rule",
+    "rule_strs",
+    multiple=True,
+    help=(
+        "One rule as semicolon-separated key=value pairs, e.g. "
+        "'target=default; font_color=#000000; number_format=#,##0'. "
+        "Commas inside a value (such as Excel number formats) are preserved. "
+        "Repeat the flag for multiple rules. Keys: target, font_color, "
+        "background_color, font_weight, font_style, font_name, font_size, "
+        "text_align, indent, number_format, border_top/bottom/left/right."
+    ),
+)
+@click.option(
+    "--inherit/--no-inherit",
+    "inherit",
+    default=None,
+    help=(
+        "--no-inherit opts the Format out of the IB default base (a total "
+        'custom theme; writes @inherit="false"). Default inherits the base '
+        "(add-on model). See `deepcell ref format`."
+    ),
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_format(
+    ctx: Ctx,
+    filename: str,
+    format_id: str,
+    rule_strs: tuple[str, ...],
+    inherit: bool | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a <Format formatId="..."> to FormatDefinitions."""
+    slug = workspace_slug or ctx.require_workspace()
+    rules = _parse_rule_kvs(rule_strs)
+    op: dict[str, Any] = {"kind": "add_format", "formatId": format_id, "rules": rules}
+    if inherit is not None:
+        op["inherit"] = inherit
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("delete-format")
+@click.argument("filename")
+@click.argument("format_id")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_format(
+    ctx: Ctx,
+    filename: str,
+    format_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a <Format> by formatId.
+
+    Refused while any <Block @formatRef> points at it; the error names the
+    referencing blocks. No flag repoints a block's @formatRef, so in practice
+    a referenced format is deleted by first renaming the format the blocks
+    should use onto this id (`deepcell defs update-format --new-id`, which
+    cascades through every @formatRef). Pass --dry-run to learn which blocks
+    reference it without changing anything.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "delete_format", "formatId": format_id}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("update-format")
+@click.argument("filename")
+@click.argument("format_id")
+@click.option(
+    "--new-id",
+    "new_id",
+    default=None,
+    help="New formatId; cascades through every <Block @formatRef>.",
+)
+@click.option(
+    "--inherit/--no-inherit",
+    "inherit",
+    default=None,
+    help=(
+        "Toggle the IB default base. --no-inherit makes this a total custom "
+        'theme (@inherit="false"); --inherit returns to the add-on default. '
+        "See `deepcell ref format`."
+    ),
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def update_format(
+    ctx: Ctx,
+    filename: str,
+    format_id: str,
+    new_id: str | None,
+    inherit: bool | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Rename a <Format> and/or toggle its IB-default inheritance.
+
+    <Block @formatRef> references cascade on rename. Provide at least one of
+    --new-id / --inherit/--no-inherit.
+    """
+    if new_id is None and inherit is None:
+        raise click.UsageError(
+            "provide at least one of --new-id or --inherit/--no-inherit."
+        )
+    slug = workspace_slug or ctx.require_workspace()
+    patch: dict[str, Any] = {"newId": new_id}
+    if inherit is not None:
+        patch["inherit"] = inherit
+    op = {
+        "kind": "update_format",
+        "formatId": format_id,
+        "patch": patch,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("add-rule")
+@click.argument("filename")
+@click.argument("format_id")
+@click.option("--target", required=True, help="Rule @target selector (see `deepcell ref format`).")
+@click.option("--bg-color", "background_color", default=None, help="Hex color '#RRGGBB' for backgroundColor.")
+@click.option("--font-color", "font_color", default=None, help="Hex color '#RRGGBB' for fontColor.")
+@click.option("--font-weight", "font_weight", default=None, help="e.g. 'bold' / 'normal'.")
+@click.option("--font-style", "font_style", default=None, help="e.g. 'italic' / 'normal'.")
+@click.option("--font-name", "font_name", default=None, help="Font family name.")
+@click.option("--font-size", "font_size", type=float, default=None, help="Font size in points.")
+@click.option("--text-align", "text_align", default=None, help="'left' | 'center' | 'right'.")
+@click.option("--indent", type=int, default=None, help="Indent character count.")
+@click.option("--number-format", "number_format", default=None, help="Excel-style pattern, e.g. '#,##0'.")
+@click.option("--border-top", default=None, help="e.g. 'thin #000000' (style + optional hex color).")
+@click.option("--border-bottom", default=None, help="Bottom border, e.g. 'thin #000000' (style + optional hex color).")
+@click.option("--border-left", default=None, help="Left border, e.g. 'thin #000000' (style + optional hex color).")
+@click.option("--border-right", default=None, help="Right border, e.g. 'thin #000000' (style + optional hex color).")
+@click.option("--index", type=int, default=None, help="Insert position (omit to append).")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_rule(
+    ctx: Ctx,
+    filename: str,
+    format_id: str,
+    target: str,
+    background_color: str | None,
+    font_color: str | None,
+    font_weight: str | None,
+    font_style: str | None,
+    font_name: str | None,
+    font_size: float | None,
+    text_align: str | None,
+    indent: int | None,
+    number_format: str | None,
+    border_top: str | None,
+    border_bottom: str | None,
+    border_left: str | None,
+    border_right: str | None,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a <Rule> to an existing <Format>."""
+    slug = workspace_slug or ctx.require_workspace()
+    rule: dict[str, Any] = {"target": target}
+    for key, val in (
+        ("background_color", background_color),
+        ("font_color", font_color),
+        ("font_weight", font_weight),
+        ("font_style", font_style),
+        ("font_name", font_name),
+        ("font_size", font_size),
+        ("text_align", text_align),
+        ("indent", indent),
+        ("number_format", number_format),
+    ):
+        if val is not None:
+            rule[key] = val
+    border = {}
+    if border_top is not None:
+        border["top"] = border_top
+    if border_bottom is not None:
+        border["bottom"] = border_bottom
+    if border_left is not None:
+        border["left"] = border_left
+    if border_right is not None:
+        border["right"] = border_right
+    if border:
+        rule["border"] = border
+    op: dict[str, Any] = {"kind": "add_rule", "formatId": format_id, "rule": rule}
+    if index is not None:
+        op["index"] = index
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("set-format")
+@click.argument("filename")
+@click.option("--sheet-id", "sheet_id", required=True, help="Sheet id of the cell.")
+@click.option("--block-id", "block_id", default=None, help="Governing block id (resolves @formatRef).")
+@click.option("--item-ref", "item_ref", required=True, help="Item ref of the cell.")
+@click.option("--context-ref", "context_ref", default=None, help="Context ref (required for cell/column scope).")
+@click.option("--scope", type=click.Choice(["cell", "item", "context"]), required=True,
+              help="cell:ITEM:CONTEXT | item:ITEM | context:CONTEXT")
+@click.option("--number-format", "number_format", default=None, help="Excel pattern, e.g. '#,##0'.")
+@click.option("--font-name", "font_name", default=None, help="Font family name.")
+@click.option(
+    "--font-size", "font_size", type=float, default=None, help="Font size in points."
+)
+@click.option("--bold/--no-bold", "bold", default=None, help="Set/clear bold.")
+@click.option("--italic/--no-italic", "italic", default=None, help="Set/clear italic.")
+@click.option("--fg-color", "fg_color", default=None, help="Text hex '#RRGGBB'.")
+@click.option("--bg-color", "bg_color", default=None, help="Fill hex '#RRGGBB'.")
+@click.option("--text-align", "text_align", default=None, help="'left'|'center'|'right'.")
+@click.option("--indent", type=int, default=None, help="Indent character count.")
+@click.option("--border-top", default=None, help="e.g. 'thin #000000'.")
+@click.option("--border-bottom", default=None, help="Bottom border, e.g. 'thin #000000' (style + optional hex color).")
+@click.option("--border-left", default=None, help="Left border, e.g. 'thin #000000' (style + optional hex color).")
+@click.option("--border-right", default=None, help="Right border, e.g. 'thin #000000' (style + optional hex color).")
+@click.option("--clear", multiple=True, help="Token name to revert to inherit (repeatable).")
+@click.option("--clear-all", "clear_all", is_flag=True, help="Delete the target's rule entirely.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def set_format(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    block_id: str | None,
+    item_ref: str,
+    context_ref: str | None,
+    scope: str,
+    number_format: str | None,
+    font_name: str | None,
+    font_size: float | None,
+    bold: bool | None,
+    italic: bool | None,
+    fg_color: str | None,
+    bg_color: str | None,
+    text_align: str | None,
+    indent: int | None,
+    border_top: str | None,
+    border_bottom: str | None,
+    border_left: str | None,
+    border_right: str | None,
+    clear: tuple[str, ...],
+    clear_all: bool,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Set cell/row/column formatting (resolves the governing <Format>)."""
+    slug = workspace_slug or ctx.require_workspace()
+    tokens: dict[str, Any] = {}
+    for key, val in (
+        ("number_format", number_format),
+        ("font_name", font_name),
+        ("font_size", font_size),
+        ("bold", bold),
+        ("italic", italic),
+        ("fg_color", fg_color),
+        ("bg_color", bg_color),
+        ("text_align", text_align),
+        ("indent", indent),
+    ):
+        if val is not None:
+            tokens[key] = val
+    border = {}
+    for side, val in (("top", border_top), ("bottom", border_bottom),
+                      ("left", border_left), ("right", border_right)):
+        if val is not None:
+            border[side] = val
+    if border:
+        tokens["border"] = border
+    op: dict[str, Any] = {
+        "kind": "set_format",
+        "sheetId": sheet_id,
+        "blockId": block_id,
+        "itemRef": item_ref,
+        "contextRef": context_ref,
+        "scope": scope,
+        "tokens": tokens,
+    }
+    if clear:
+        op["clear"] = list(clear)
+    if clear_all:
+        op["clearAll"] = True
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("delete-rule")
+@click.argument("filename")
+@click.argument("format_id")
+@click.option("--index", type=int, default=None, help="Delete the rule at this position.")
+@click.option("--target", default=None, help="Delete the first rule with this @target.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_rule(
+    ctx: Ctx,
+    filename: str,
+    format_id: str,
+    index: int | None,
+    target: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a <Rule> by index or by @target.
+
+    Rules are positional, so deleting by --index shifts every later rule up
+    one — read the current order out of `deepcell cat FILENAME` before
+    deleting by index. Pass --dry-run to validate without persisting.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    if index is None and target is None:
+        raise click.UsageError("Provide --index or --target.")
+    op: dict[str, Any] = {"kind": "delete_rule", "formatId": format_id}
+    if index is not None:
+        op["index"] = index
+    if target is not None:
+        op["target"] = target
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+# ── Sensitivity block ops ──────────────────────────────────
+
+
+def _load_spec(spec_file: Any) -> dict[str, Any]:
+    """Load and validate a sensitivity spec JSON file ({"axes": [...], "outputs": [...]})."""
+    try:
+        spec = json.load(spec_file)
+    except json.JSONDecodeError as exc:
+        raise click.UsageError(f"Spec file is not valid JSON: {exc}") from exc
+    if not isinstance(spec, dict) or "axes" not in spec or "outputs" not in spec:
+        raise click.UsageError('Spec file must be a JSON object with "axes" and "outputs".')
+    return spec
+
+
+@defs.command("add-sensitivity")
+@click.argument("filename")
+@click.option("--sheet", "sheet_id", required=True, help="Sheet to add the block to.")
+@click.option("--name", required=True, help="Display name of the sensitivity block.")
+@click.option(
+    "--index",
+    type=int,
+    default=None,
+    help="Position among sheet blocks (omit to append at end).",
+)
+@click.option("--format-ref", "format_ref", default=None, help="FormatDefinitions id.")
+@click.option(
+    "--spec-file",
+    "spec_file",
+    required=True,
+    type=click.File("r"),
+    help='JSON with {"axes": [...], "outputs": [...]} (use "-" for stdin).',
+)
+@click.option(
+    "--revision", default=None, help="Expected revision SHA for optimistic locking."
+)
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_sensitivity(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    name: str,
+    index: int | None,
+    format_ref: str | None,
+    spec_file: Any,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a sensitivity block (data table / scenario comparison).
+
+    The --spec-file JSON holds the axes and the outputs they drive, e.g.:
+
+    \b
+      {"axes": [{"axis": "col", "axisType": "input", "itemRef": "wacc",
+                 "contextRef": "FY24", "points": ["0.08", "0.10"]}],
+       "outputs": [{"itemRef": "npv", "contextRef": "FY24"}]}
+
+    An axis and an output each name ONE cell, and a cell is five dimensions.
+    Add "dimFilter": "geo:na" to either when the item it names is
+    dimension-sliced — the same spelling <Block dimFilter> uses. Without it the
+    coordinate resolves to no cell: the grid renders blank and the block earns
+    a sensitivity_unpinned_dims warning naming the member to pin.
+
+    See `deepcell ref op/add_sensitivity_block` for the spec semantics.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    spec = _load_spec(spec_file)
+    op: dict[str, Any] = {
+        "kind": "add_sensitivity_block",
+        "sheetId": sheet_id,
+        "name": name,
+        "axes": spec["axes"],
+        "outputs": spec["outputs"],
+    }
+    if index is not None:
+        op["index"] = index
+    if format_ref is not None:
+        op["formatRef"] = format_ref
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("update-sensitivity")
+@click.argument("filename")
+@click.option("--sheet", "sheet_id", required=True, help="Sheet containing the block.")
+@click.option("--block", "block_id", required=True, help="blockId of the block to edit.")
+@click.option("--name", default=None, help="New display name.")
+@click.option("--format-ref", "format_ref", default=None, help="New FormatDefinitions id.")
+@click.option(
+    "--spec-file",
+    "spec_file",
+    default=None,
+    type=click.File("r"),
+    help='JSON with {"axes": [...], "outputs": [...]} to replace both.',
+)
+@click.option(
+    "--revision", default=None, help="Expected revision SHA for optimistic locking."
+)
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def update_sensitivity(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    block_id: str,
+    name: str | None,
+    format_ref: str | None,
+    spec_file: Any,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Edit a sensitivity block's name, format, or axes/outputs.
+
+    Pass --spec-file to replace both axes and outputs together. Omitting
+    --spec-file patches only name/formatRef without touching axes or outputs.
+    Provide at least one of --name / --format-ref / --spec-file.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op: dict[str, Any] = {
+        "kind": "update_sensitivity_block",
+        "sheetId": sheet_id,
+        "blockId": block_id,
+    }
+    if name is not None:
+        op["name"] = name
+    if format_ref is not None:
+        op["formatRef"] = format_ref
+    if spec_file is not None:
+        spec = _load_spec(spec_file)
+        op["axes"] = spec["axes"]
+        op["outputs"] = spec["outputs"]
+    if not any(k in op for k in ("name", "formatRef", "axes")):
+        raise click.UsageError("Provide at least one of --name / --format-ref / --spec-file.")
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+# ── Presentation block attributes ──────────────────────────
+
+
+@defs.command("set-block-attrs")
+@click.argument("filename")
+@click.option("--sheet", "sheet_id", required=True, help="Sheet containing the block.")
+@click.option("--block", "block_id", required=True, help="blockId of the block to edit.")
+@click.option(
+    "--format-ref",
+    "format_ref",
+    default=None,
+    help=(
+        "FormatDefinitions id this block resolves against. Pass an empty "
+        "string to clear it back to the document default (the Format named "
+        "default_format, else the first one defined). See "
+        "`deepcell ref format`."
+    ),
+)
+@click.option(
+    "--status-expansion",
+    "status_expansion",
+    type=click.Choice(["none", "columns", "series"]),
+    default=None,
+    help=(
+        "Side-by-side status-column layout. 'columns' lays each status in "
+        "--status-refs out as its own run of context columns; 'series' is the "
+        "chart form, one series per status; 'none' (default) keeps the "
+        "single-column-per-context layout."
+    ),
+)
+@click.option(
+    "--status-refs",
+    "status_refs",
+    default=None,
+    help=(
+        "Whitespace/comma-separated status ids to expand into columns "
+        '(e.g. "actual budget"). Required for --status-expansion=columns.'
+    ),
+)
+@click.option(
+    "--dim-expansion",
+    "dim_expansion",
+    type=click.Choice(["none", "rows", "series"]),
+    default=None,
+    help=(
+        "Custom-dimension member sub-rows. 'rows' lays each member of "
+        "--dim-ref out as a contiguous sub-row under its item; 'series' is "
+        "the chart form, one series per member; 'none' (default) keeps the "
+        "one-row-per-item layout."
+    ),
+)
+@click.option(
+    "--dim-ref",
+    "dim_ref",
+    default=None,
+    help=(
+        "Dimension id whose members are expanded into sub-rows "
+        '(e.g. "geography"). Required for --dim-expansion=rows.'
+    ),
+)
+@click.option(
+    "--dim-expansion-cap",
+    "dim_expansion_cap",
+    type=click.IntRange(min=1),
+    default=None,
+    help=(
+        "Max members to expand into sub-rows before falling back to a single "
+        "row (positive int; default 24). Used with --dim-expansion=rows."
+    ),
+)
+@click.option(
+    "--dim-member-refs",
+    "dim_member_refs",
+    default=None,
+    help=(
+        "Whitespace/comma-separated member ids of --dim-ref, order preserved. "
+        "With --dim-expansion it selects which members expand; without one, a "
+        "single id pins that member for every cell the block reads — how a "
+        "chart plots one slice of a dimension-sliced item."
+    ),
+)
+@click.option(
+    "--dim-filter",
+    "dim_filter",
+    default=None,
+    help=(
+        "Pin the dimensions the block does NOT expand, one member each: "
+        "'region:na;cohort:c1'. Same dim:member spelling and ';' separator as "
+        "customDimensions on a Value, so a stored coordinate can be copied "
+        "across. A block expands one dimension (--dim-ref), so this is what "
+        "makes a cell keyed on two or more custom dimensions addressable."
+    ),
+)
+@click.option(
+    "--scenario-expansion",
+    "scenario_expansion",
+    type=click.Choice(["none", "columns", "series"]),
+    default=None,
+    help=(
+        "Side-by-side scenario-column layout. 'columns' lays each scenario in "
+        "--scenario-refs out as its own run of context columns; 'series' is "
+        "the chart form, one series per scenario; 'none' (default) keeps the "
+        "single-column-per-context layout."
+    ),
+)
+@click.option(
+    "--scenario-refs",
+    "scenario_refs",
+    default=None,
+    help=(
+        "Whitespace/comma-separated scenario ids to expand into columns "
+        '(e.g. "Base Bull"). Required for --scenario-expansion=columns.'
+    ),
+)
+@click.option(
+    "--chart-type",
+    "chart_type",
+    type=click.Choice(
+        [
+            "bar", "bar_stacked", "bar_horizontal", "line", "area", "pie",
+            "donut", "waterfall", "range_bar", "scatter",
+        ]
+    ),
+    default=None,
+    help=(
+        "Chart type (chart blocks only). 'waterfall' bridges deltas between "
+        "declared totals; 'range_bar' draws a low..high band per category "
+        "(the football field)."
+    ),
+)
+@click.option(
+    "--category-axis",
+    "category_axis",
+    type=click.Choice(["context", "item"]),
+    default=None,
+    help="Which dimension is the category axis (chart blocks only).",
+)
+@click.option(
+    "--total-item-refs",
+    "total_item_refs",
+    default=None,
+    help=(
+        "Whitespace/comma-separated refs naming the plotted categories that "
+        "rest on the baseline instead of floating on the running sum "
+        "(--chart-type=waterfall only). Declared, never inferred: omit it and "
+        "every step is a delta."
+    ),
+)
+@click.option(
+    "--revision", default=None, help="Expected revision SHA for optimistic locking."
+)
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def set_block_attrs(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    block_id: str,
+    format_ref: str | None,
+    status_expansion: str | None,
+    status_refs: str | None,
+    dim_expansion: str | None,
+    dim_ref: str | None,
+    dim_expansion_cap: int | None,
+    dim_member_refs: str | None,
+    dim_filter: str | None,
+    scenario_expansion: str | None,
+    scenario_refs: str | None,
+    chart_type: str | None,
+    category_axis: str | None,
+    total_item_refs: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Set presentation-layout attributes on an existing block.
+
+    Statuses as side-by-side column runs — --status-expansion with
+    --status-refs:
+
+    \b
+      deepcell defs set-block-attrs model.deepcell --sheet income_statement \\
+          --block b_main --status-expansion columns --status-refs "actual budget"
+
+    Each member of a custom dimension as a contiguous sub-row under its item —
+    --dim-expansion with --dim-ref:
+
+    \b
+      deepcell defs set-block-attrs model.deepcell --sheet income_statement \\
+          --block b_main --dim-expansion rows --dim-ref geography \\
+          --dim-expansion-cap 12
+
+    Each scenario as its own side-by-side column run — --scenario-expansion
+    with --scenario-refs:
+
+    \b
+      deepcell defs set-block-attrs model.deepcell --sheet income_statement \\
+          --block b_main --scenario-expansion columns --scenario-refs "Base Bull"
+
+    Chart blocks: --chart-type / --category-axis, e.g. --chart-type line
+    --category-axis context. A waterfall also takes --total-item-refs
+    naming the steps that rest on the baseline, and a scatter reads its two
+    series as x then y.
+
+    On a chart the expansions take 'series' instead of 'columns' / 'rows',
+    laying that axis out as one series per member — measured against expected
+    on one plot:
+
+    \b
+      deepcell defs set-block-attrs model.deepcell --sheet readout \\
+          --block counts_chart --status-expansion series \\
+          --status-refs "predicted counted" --dim-ref phenotype \\
+          --dim-member-refs dominant
+
+    --dim-member-refs on its own pins one member of --dim-ref, which is how a
+    chart reads a single slice of a dimension-sliced item while some other
+    axis supplies the series.
+
+    --format-ref names which <Format> the block resolves against, for any block
+    type. Without one the block takes the document default — the Format named
+    `default_format`, else the first one defined — so this is the flag that
+    puts a specific Format on a specific block when a document holds several.
+
+    Only the flags you provide are written (key-presence patch): passing
+    --status-refs on its own leaves an existing statusExpansion untouched, and
+    vice versa. Provide at least one of --format-ref / --status-expansion /
+    --status-refs /
+    --dim-expansion / --dim-ref / --dim-expansion-cap / --dim-member-refs /
+    --scenario-expansion / --scenario-refs / --chart-type / --category-axis.
+
+    See `deepcell ref op/set_presentation_block_attrs` for the expansion
+    and pin semantics.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op: dict[str, Any] = {
+        "kind": "set_presentation_block_attrs",
+        "sheetId": sheet_id,
+        "blockId": block_id,
+    }
+    if format_ref is not None:
+        op["formatRef"] = format_ref
+    if status_expansion is not None:
+        op["statusExpansion"] = status_expansion
+    if status_refs is not None:
+        op["statusRefs"] = status_refs
+    if dim_expansion is not None:
+        op["dimExpansion"] = dim_expansion
+    if dim_ref is not None:
+        op["dimRef"] = dim_ref
+    if dim_expansion_cap is not None:
+        op["dimExpansionCap"] = dim_expansion_cap
+    if dim_member_refs is not None:
+        op["dimMemberRefs"] = dim_member_refs
+    if dim_filter is not None:
+        op["dimFilter"] = dim_filter
+    if scenario_expansion is not None:
+        op["scenarioExpansion"] = scenario_expansion
+    if scenario_refs is not None:
+        op["scenarioRefs"] = scenario_refs
+    if chart_type is not None:
+        op["chartType"] = chart_type
+    if category_axis is not None:
+        op["categoryAxis"] = category_axis
+    if total_item_refs is not None:
+        op["totalItemRefs"] = total_item_refs
+    if not any(
+        k in op
+        for k in (
+            "formatRef",
+            "statusExpansion",
+            "statusRefs",
+            "dimExpansion",
+            "dimRef",
+            "dimExpansionCap",
+            "dimMemberRefs",
+            "dimFilter",
+            "scenarioExpansion",
+            "scenarioRefs",
+            "chartType",
+            "categoryAxis",
+            "totalItemRefs",
+        )
+    ):
+        raise click.UsageError(
+            "Provide at least one of --format-ref / --status-expansion / "
+            "--status-refs / "
+            "--dim-expansion / --dim-ref / --dim-expansion-cap / "
+            "--dim-member-refs / --dim-filter / --scenario-expansion / "
+            "--scenario-refs / "
+            "--chart-type / --category-axis / --total-item-refs."
+        )
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("add-block")
+@click.argument("filename")
+@click.option("--sheet", "sheet_id", required=True, help="Sheet to add the block to.")
+@click.option(
+    "--block-type",
+    "block_type",
+    required=True,
+    help=(
+        "One of: table, chart, sensitivity, key_value, text. The server "
+        "stores any string, but the renderer skips a block whose type it "
+        "does not know, so anything else is written and never drawn."
+    ),
+)
+@click.option("--name", required=True, help="Display name / section heading.")
+@click.option(
+    "--item-orders",
+    "item_orders",
+    default=None,
+    help=(
+        "Comma-separated rows, in order: item ids, @order values, or order "
+        "ranges (e.g. 'revenue,cogs,gross_profit' or '4000-4099'). Stored "
+        "verbatim as @itemOrders; the reader resolves each token — a number "
+        "or a range matches @order, anything else matches an itemId. Omit "
+        "and the block renders empty — see the note above."
+    ),
+)
+@click.option(
+    "--context-refs",
+    "context_refs",
+    default=None,
+    help=(
+        "Comma-separated context ids forming the block's columns, in order "
+        "(e.g. 'FY2024,FY2025'). Omit to show every context."
+    ),
+)
+@click.option(
+    "--index", type=int, default=None,
+    help="Insertion index within the sheet (default: append at the end).",
+)
+@click.option(
+    "--format-ref",
+    "format_ref",
+    default=None,
+    help=(
+        "FormatDefinitions id this block resolves against. Omit and the block "
+        "takes the document default (the Format named default_format, else the "
+        "first one defined). See `deepcell ref format`."
+    ),
+)
+@click.option(
+    "--chart-type",
+    "chart_type",
+    type=click.Choice(
+        [
+            "bar", "bar_stacked", "bar_horizontal", "line", "area", "pie",
+            "donut", "waterfall", "range_bar", "scatter",
+        ]
+    ),
+    default=None,
+    help=(
+        "Chart type (chart blocks only). 'waterfall' bridges deltas between "
+        "declared totals; 'range_bar' draws a low..high band per category "
+        "(the football field)."
+    ),
+)
+@click.option(
+    "--category-axis",
+    "category_axis",
+    type=click.Choice(["context", "item"]),
+    default=None,
+    help="Which dimension is the category axis (chart blocks only).",
+)
+@click.option(
+    "--total-item-refs",
+    "total_item_refs",
+    default=None,
+    help=(
+        "Whitespace/comma-separated refs naming the plotted categories that "
+        "rest on the baseline instead of floating on the running sum "
+        "(--chart-type=waterfall only). Declared, never inferred: omit it and "
+        "every step is a delta."
+    ),
+)
+@click.option(
+    "--revision", default=None, help="Expected revision SHA for optimistic locking."
+)
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_block(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    block_type: str,
+    name: str,
+    item_orders: str | None,
+    context_refs: str | None,
+    index: int,
+    format_ref: str | None,
+    chart_type: str | None,
+    category_axis: str | None,
+    total_item_refs: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a presentation Block (table or chart) to a sheet.
+
+    Pass --item-orders. A table, chart, or key_value block that declares no
+    item membership renders EMPTY, so a block added without it exists in the
+    XML and is drawn nowhere. Rows and columns can also be changed afterwards
+    with `deepcell defs add-axis-member` / `delete-axis-member`.
+
+    \b
+      deepcell defs add-block model.deepcell --sheet s_main \\
+          --block-type table --name "Income Statement" \\
+          --item-orders revenue,cogs,gross_profit
+
+    \b
+      deepcell defs add-block model.deepcell --sheet s_dash \\
+          --block-type chart --name "Revenue Trend" --chart-type line \\
+          --item-orders revenue --category-axis context
+
+    --format-ref names which <Format> the block resolves against. Omit it and
+    the block takes the document default, which is the right answer for a file
+    with one Format; name it when the file has several and this block needs a
+    particular one. Changeable afterwards with `defs set-block-attrs`.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    if block_type.strip() not in _RENDERABLE_BLOCK_TYPES:
+        # The server accepts blockType opaquely, so a typo is not an error —
+        # it lands a block the render pipeline silently skips. Say so at the
+        # point of use rather than leaving the block invisible.
+        echo_warning(
+            f"block type {block_type!r} is not one of "
+            f"{', '.join(sorted(_RENDERABLE_BLOCK_TYPES))} — the block will be "
+            "stored but skipped when the document is rendered or exported."
+        )
+    op: dict[str, Any] = {
+        "kind": "add_presentation_block",
+        "sheetId": sheet_id,
+        "blockType": block_type,
+        "name": name,
+    }
+    # Omitted entirely when not given: the handler appends on a missing index.
+    if index is not None:
+        op["index"] = index
+    if item_orders is not None:
+        op["itemOrders"] = item_orders
+    if context_refs is not None:
+        op["contextRefs"] = context_refs
+    if format_ref is not None:
+        op["formatRef"] = format_ref
+    if chart_type is not None:
+        op["chartType"] = chart_type
+    if category_axis is not None:
+        op["categoryAxis"] = category_axis
+    if total_item_refs is not None:
+        op["totalItemRefs"] = total_item_refs
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+# ── Presentation sheets ────────────────────────────────────
+#
+# The sheet / block / axis-member ops were built for the web Configure form
+# and the viewer's "+ Add sheet" button, so none of them had a CLI command:
+# an agent could add a block but not the sheet to put it on, and could not
+# rename, reorder, or remove anything it created.
+
+
+@defs.command("add-sheet")
+@click.argument("filename")
+@click.option("--label", required=True, help="Sheet tab label, e.g. 'Dashboard'.")
+@click.option(
+    "--index",
+    type=click.IntRange(min=0),
+    default=None,
+    help="0-based position among the sheets (default: append at the end).",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_sheet(
+    ctx: Ctx,
+    filename: str,
+    label: str,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a presentation Sheet — a tab in the rendered document.
+
+    A sheet holds Blocks; add one with `deepcell defs add-block --sheet`.
+    The generated sheetId comes back in this command's output.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op: dict[str, Any] = {"kind": "add_presentation_sheet", "sheetLabel": label}
+    # Omitted when not given: the handler appends on a missing index.
+    if index is not None:
+        op["index"] = index
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("delete-sheet")
+@click.argument("filename")
+@click.argument("sheet_id")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_sheet(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a presentation Sheet and every Block on it.
+
+    Presentation-only: the ItemDefs and ContextDefs the blocks referenced
+    stay, and so do their Values. Nothing else in the document is touched.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "delete_presentation_sheet", "sheetId": sheet_id}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("rename-sheet")
+@click.argument("filename")
+@click.argument("sheet_id")
+@click.argument("new_label")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def rename_sheet(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    new_label: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Change a Sheet's displayed tab label.
+
+    The sheetId is the stable identifier and does not change, so nothing
+    that references the sheet needs repointing.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "rename_presentation_sheet",
+        "sheetId": sheet_id,
+        "newLabel": new_label,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("reorder-sheets")
+@click.argument("filename")
+@click.argument("sheet_id")
+@click.option(
+    "--to-index",
+    "to_index",
+    type=click.IntRange(min=0),
+    required=True,
+    help="Final 0-based position among the sheets. 0 = leftmost tab.",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def reorder_sheets(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    to_index: int,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Move a Sheet to a new position in the tab order."""
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "reorder_presentation_sheets",
+        "sheetId": sheet_id,
+        "toIndex": to_index,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+# ── Presentation blocks ────────────────────────────────────
+
+
+@defs.command("delete-block")
+@click.argument("filename")
+@click.option("--sheet", "sheet_id", required=True, help="Sheet containing the block.")
+@click.option("--block", "block_id", required=True, help="blockId to delete.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_block(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    block_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a Block from a Sheet.
+
+    Refused while the block still has axis members — clear them first with
+    `deepcell defs delete-axis-member`. Presentation-only: the items and
+    contexts the block laid out keep their definitions and their Values.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "delete_presentation_block",
+        "sheetId": sheet_id,
+        "blockId": block_id,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("rename-block")
+@click.argument("filename")
+@click.argument("new_name")
+@click.option("--sheet", "sheet_id", required=True, help="Sheet containing the block.")
+@click.option("--block", "block_id", required=True, help="blockId to rename.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def rename_block(
+    ctx: Ctx,
+    filename: str,
+    new_name: str,
+    sheet_id: str,
+    block_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Change a Block's display name — its section heading in the render.
+
+    \b
+      deepcell defs rename-block model.deepcell "Income Statement" \\
+          --sheet s_main --block block_ab12
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "rename_presentation_block",
+        "sheetId": sheet_id,
+        "blockId": block_id,
+        "newName": new_name,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("reorder-block")
+@click.argument("filename")
+@click.option("--sheet", "sheet_id", required=True, help="Sheet containing the block.")
+@click.option("--block", "block_id", required=True, help="blockId to move.")
+@click.option(
+    "--to-index",
+    "to_index",
+    type=click.IntRange(min=0),
+    required=True,
+    help="Final 0-based position among the sheet's blocks. 0 = topmost.",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def reorder_block(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    block_id: str,
+    to_index: int,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Move a Block to a new position within its Sheet.
+
+    Blocks render top to bottom in this order; every sibling's @order is
+    renumbered to its new 1-based position.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "reorder_presentation_block",
+        "sheetId": sheet_id,
+        "blockId": block_id,
+        "toIndex": to_index,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+# ── Block axis members (the rows and columns of a block) ────
+
+
+_AXIS_HELP = (
+    "Which axis to edit: 'rows' (the block's @itemOrders) or 'columns' "
+    "(its @contextRefs)."
+)
+
+
+@defs.command("add-axis-member")
+@click.argument("filename")
+@click.option("--sheet", "sheet_id", required=True, help="Sheet containing the block.")
+@click.option("--block", "block_id", required=True, help="blockId to edit.")
+@click.option(
+    "--axis", type=click.Choice(["rows", "columns"]), required=True, help=_AXIS_HELP
+)
+@click.option(
+    "--member",
+    type=click.Choice(["item", "context"]),
+    required=True,
+    help="What kind of id --ref is. Pair 'item' with rows, 'context' with columns.",
+)
+@click.option("--ref", required=True, help="The item id or context id to add.")
+@click.option(
+    "--index",
+    type=click.IntRange(min=0),
+    default=None,
+    help="0-based position on the axis (default: append at the end).",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_axis_member(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    block_id: str,
+    axis: str,
+    member: str,
+    ref: str,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a row or a column to a Block.
+
+    This is what makes a Block show anything: a block with no rows renders
+    empty. `deepcell defs add-block --item-orders` sets the initial rows in
+    one call; use this to add to them afterwards.
+
+    \b
+      deepcell defs add-axis-member model.deepcell --sheet s_main \\
+          --block block_ab12 --axis rows --member item --ref gross_profit
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op: dict[str, Any] = {
+        "kind": "add_axis_member",
+        "sheetId": sheet_id,
+        "blockId": block_id,
+        "axis": axis,
+        "member": member,
+        "ref": ref,
+    }
+    # Omitted when not given: the handler appends on a missing index.
+    if index is not None:
+        op["index"] = index
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("delete-axis-member")
+@click.argument("filename")
+@click.option("--sheet", "sheet_id", required=True, help="Sheet containing the block.")
+@click.option("--block", "block_id", required=True, help="blockId to edit.")
+@click.option(
+    "--axis", type=click.Choice(["rows", "columns"]), required=True, help=_AXIS_HELP
+)
+@click.option("--ref", required=True, help="The item id or context id to remove.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_axis_member(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    block_id: str,
+    axis: str,
+    ref: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Remove a row or a column from a Block.
+
+    Unwires presentation only — the ItemDef or ContextDef stays defined and
+    its Values stay in the document; the block just stops laying it out. To
+    delete the definition itself use `defs delete-item` / `delete-context`.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "delete_axis_member",
+        "sheetId": sheet_id,
+        "blockId": block_id,
+        "axis": axis,
+        "ref": ref,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("reorder-axis-member")
+@click.argument("filename")
+@click.option("--sheet", "sheet_id", required=True, help="Sheet containing the block.")
+@click.option("--block", "block_id", required=True, help="blockId to edit.")
+@click.option(
+    "--axis", type=click.Choice(["rows", "columns"]), required=True, help=_AXIS_HELP
+)
+@click.option("--ref", required=True, help="The item id or context id to move.")
+@click.option(
+    "--to-index",
+    "to_index",
+    type=click.IntRange(min=0),
+    required=True,
+    help="Final 0-based position on the axis. 0 = first row / leftmost column.",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def reorder_axis_member(
+    ctx: Ctx,
+    filename: str,
+    sheet_id: str,
+    block_id: str,
+    axis: str,
+    ref: str,
+    to_index: int,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Move a row or a column to a new position within a Block.
+
+    Changes presentation order only. `defs reorder-item` moves the item in
+    ItemDefinitions, which is a different thing — a block lays out only the
+    members on its own axis, in its own order.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    op = {
+        "kind": "reorder_axis_member",
+        "sheetId": sheet_id,
+        "blockId": block_id,
+        "axis": axis,
+        "ref": ref,
+        "toIndex": to_index,
+    }
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+# ── Batch escape hatch ─────────────────────────────────────
+
+
+@defs.command("apply")
+@click.argument("filename")
+@click.option(
+    "--ops-file",
+    "ops_file",
+    default=None,
+    type=click.File("r"),
+    help="JSON file with an `ops` array (use '-' for stdin).",
+)
+@click.option(
+    "--ops",
+    "ops_inline",
+    default=None,
+    help="Inline ops JSON (same shapes as --ops-file); mirrors the agent "
+    "tool's `defs apply --ops '<json>'` form.",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def apply(
+    ctx: Ctx,
+    filename: str,
+    ops_file: Any,
+    ops_inline: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Apply a batch of ops atomically.
+
+    \b
+    The ops payload (--ops-file FILE, or inline via --ops '<json>') is a
+    JSON document of either form:
+      [{"kind": "add_calc", "defaults": {...}}, ...]            # bare array
+      {"ops": [{"kind": "add_item", "index": 0, ...}, ...]}    # wrapped
+
+    \b
+    See `deepcell guide generate/calcs` for calculation op shapes and
+    `deepcell guide present/decks` for HTML Deck op shapes and a complete
+    authoring example.
+
+    \b
+    Pass --dry-run to pre-flight the batch: the server runs the complete
+    pipeline (per-op validation, formula parse, post-apply cycle check +
+    recompute) and reports success/errors without persisting anything —
+    no commit, no revision bump.
+
+    \b
+    Presentation axis-member ops (`add_axis_member` / `delete_axis_member` /
+    `reorder_axis_member`) require an explicit `blockId` field — there is no
+    implicit primary block. See `deepcell ref op/add_axis_member`.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    if (ops_file is None) == (ops_inline is None):
+        raise click.UsageError("Provide exactly one of --ops-file or --ops.")
+    try:
+        parsed = json.load(ops_file) if ops_file is not None else json.loads(ops_inline)
+    except json.JSONDecodeError as exc:
+        raise click.UsageError(f"Ops JSON does not parse — {exc}") from exc
+    if isinstance(parsed, list):
+        ops = parsed
+    elif isinstance(parsed, dict) and isinstance(parsed.get("ops"), list):
+        ops = parsed["ops"]
+    else:
+        raise click.UsageError(
+            'Ops must be a JSON array or {"ops": [...]} object.'
+        )
+    if not ops:
+        raise click.UsageError("No ops to apply.")
+    _apply(ctx, slug, filename, ops, revision=revision)
+
+
+# --- <Document> prose sections ----------------------------------------------
+#
+# The BODY is edited by `deepcell doc set-body` / `doc patch-body`, not here:
+# a whole markdown document is the wrong shape for a flag. These three manage
+# the section's existence and its attributes.
+
+
+@defs.command("add-doc")
+@click.argument("filename")
+@click.option("--doc-id", "doc_id", default=None,
+              help="Document identifier (@docId). Must match [A-Za-z0-9_.-]+ so a "
+                   "deepcell:doc/<id> reference to it parses back.")
+@click.option("--name", default=None, help="Display title.")
+@click.option("--lang", default=None, help="BCP-47 language tag, e.g. 'en' or 'zh'.")
+@click.option("--body-file", type=click.Path(exists=True, dir_okay=False), default=None,
+              help="File holding the initial body (else empty).")
+@click.option("--notation", type=click.Choice(["markdown", "text"]), default=None,
+              help="What the body IS. A new document is markdown unless you "
+                   "say 'text', which also stops anchors being stamped into it.")
+@click.option("--index", type=int, default=None, help="Position among documents.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_doc(
+    ctx: Ctx,
+    filename: str,
+    doc_id: str | None,
+    name: str | None,
+    lang: str | None,
+    body_file: str | None,
+    notation: str | None,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Add a <Document> — the prose that ships with the model.
+
+    Every number in that prose should be a link, not a typed figure: a linked
+    value re-renders from the model and cannot go stale (`deepcell rules R15`).
+    See `deepcell guide present/prose`.
+
+    A new document is `markdown` unless `--notation text` says otherwise, and
+    is stamped with `{#id}` anchors at birth so every block is addressable.
+    `--notation text` stores the bytes as they are and stamps nothing.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    body = ""
+    if body_file:
+        with open(body_file, "r", encoding="utf-8") as handle:
+            body = handle.read()
+    op: dict = {"kind": "add_presentation_document", "body": body}
+    if doc_id:
+        op["docId"] = doc_id
+    if name:
+        op["name"] = name
+    if lang:
+        op["lang"] = lang
+    if notation:
+        op["notation"] = notation
+    if index is not None:
+        op["index"] = index
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("update-doc")
+@click.argument("filename")
+@click.argument("doc_id")
+@click.option("--name", default=None, help="New display title.")
+@click.option("--lang", default=None, help="New BCP-47 language tag.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def update_doc(
+    ctx: Ctx,
+    filename: str,
+    doc_id: str,
+    name: str | None,
+    lang: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Update a Document's attributes. Use `doc set-body` for its text."""
+    slug = workspace_slug or ctx.require_workspace()
+    op: dict = {"kind": "update_presentation_document", "docId": doc_id}
+    if name:
+        op["name"] = name
+    if lang:
+        op["lang"] = lang
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("delete-doc")
+@click.argument("filename")
+@click.argument("doc_id")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_doc(
+    ctx: Ctx,
+    filename: str,
+    doc_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Delete a Document and its body.
+
+    Nothing else in the file depends on a document — it is a presentation
+    surface — but references TO it from other documents or deck bindings become
+    dangling, which `deepcell doc links --unresolved` reports.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    _apply(
+        ctx, slug, filename,
+        [{"kind": "delete_presentation_document", "docId": doc_id}],
+        revision=revision,
+    )
+
+
+# ── Source ops (docs/source-and-links-design.md §8) ──────────────────────────
+#
+# `<DataSource>` never had a defs op and `edit --batch` writes values only, so
+# a cell an agent populated through the normal path was source-less by
+# construction. These close that.
+
+
+def _cites_row(
+    item_refs: str | None,
+    context_refs: str | None,
+    status_ref: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    at: str | None,
+) -> dict[str, Any] | None:
+    """One `<Cites>` row from the flag set, or None when nothing was named."""
+    row: dict[str, Any] = {}
+    if item_refs:
+        row["item_refs"] = [s.strip() for s in item_refs.split(",") if s.strip()]
+    if context_refs:
+        row["context_refs"] = [s.strip() for s in context_refs.split(",") if s.strip()]
+    for field, value in (
+        ("status_ref", status_ref),
+        ("scenario_ref", scenario_ref),
+        ("custom_dimensions", custom_dimensions),
+        ("at", at),
+    ):
+        if value is not None:
+            row[field] = value
+    return row or None
+
+
+_CITES_OPTIONS = [
+    click.option("--items", "item_refs", default=None,
+                 help="CSV of itemRefs this source backs."),
+    click.option("--contexts", "context_refs", default=None,
+                 help="CSV of contextRefs. Omit to cover every context the statusRef allows."),
+    click.option("--status", "status_ref", default=None, help="statusRef for the coverage row."),
+    click.option("--scenario", "scenario_ref", default=None, help="scenarioRef for the coverage row."),
+    click.option("--custom-dimensions", "custom_dimensions", default=None,
+                 help="'dim:member;dim:member' for the coverage row."),
+]
+
+
+def _with_cites_options(fn):
+    for option in reversed(_CITES_OPTIONS):
+        fn = option(fn)
+    return fn
+
+
+@defs.command("add-source")
+@click.argument("filename")
+@click.option("--id", "source_id", required=True, help="Stable sourceId, e.g. 'src_aapl_10k_fy25'.")
+@click.option(
+    "--kind",
+    default=None,
+    help=(
+        "What the source physically IS - closed set: filing, webpage, pdf, "
+        "workbook, dataset, query, transcript, media, message, document, "
+        "person, derived, other. What it is USED AS goes in --role."
+    ),
+)
+@click.option(
+    "--role",
+    default=None,
+    help=(
+        "What the source is being used AS - free text: historical_actual, "
+        "assumption, analyst_estimate, management_guidance, industry_benchmark, "
+        "market_data, manual, ..."
+    ),
+)
+@click.option(
+    "--reach",
+    default=None,
+    help=(
+        "Can a recipient open it? public | account | private | offline. "
+        "'private' withholds the locator on share and export; 'offline' means "
+        "no locator exists, which is a complete record, not a broken one."
+    ),
+)
+@click.option("--title", default=None, help="Human-readable title - what renders when the locator is withheld.")
+@click.option("--locator", default=None, help="The one outward address (URL, path, DSN).")
+@click.option("--description", default=None, help="Longer note about the source.")
+@click.option(
+    "--at",
+    "at",
+    default=None,
+    help=(
+        "Default position inside the source: text:HEADING[,SUFFIX] | page:47 | "
+        "sheet:Name!A1:B9 | row:1042 | col:arr | t:00:14:32 | anchor:id."
+    ),
+)
+@click.option("--effective-date", default=None, help="ISO date the source describes.")
+@click.option("--retrieved-at", default=None, help="ISO timestamp it was fetched.")
+@click.option("--issuer", default=None, help="Who published it.")
+@click.option("--ticker", "issuer_ticker", default=None, help="Issuer ticker symbol.")
+@click.option(
+    "--identity",
+    "identities",
+    multiple=True,
+    help="Declared identity as 'scheme:value' (e.g. 'sec.accession:0000320193-25-000079'). Repeatable.",
+)
+@_with_cites_options
+@click.option("--index", type=int, default=None, help="Position (omit to append at end).")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def add_source(
+    ctx: Ctx,
+    filename: str,
+    source_id: str,
+    kind: str | None,
+    role: str | None,
+    reach: str | None,
+    title: str | None,
+    locator: str | None,
+    description: str | None,
+    at: str | None,
+    effective_date: str | None,
+    retrieved_at: str | None,
+    issuer: str | None,
+    issuer_ticker: str | None,
+    identities: tuple[str, ...],
+    item_refs: str | None,
+    context_refs: str | None,
+    status_ref: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    index: int | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Declare a <Source> - the one place an outward address may live."""
+    slug = workspace_slug or ctx.require_workspace()
+    defaults: dict[str, Any] = {"name": source_id}
+    for field, value in (
+        ("kind", kind),
+        ("role", role),
+        ("reach", reach),
+        ("title", title),
+        ("locator", locator),
+        ("description", description),
+        ("at", at),
+        ("effective_date", effective_date),
+        ("retrieved_at", retrieved_at),
+        ("issuer", issuer),
+        ("issuer_ticker", issuer_ticker),
+    ):
+        if value is not None:
+            defaults[field] = value
+
+    parsed_identities: list[dict[str, str]] = []
+    for raw in identities:
+        scheme, sep, value = raw.partition(":")
+        if not sep or not scheme.strip() or not value.strip():
+            raise click.UsageError(
+                f"--identity must be 'scheme:value', got {raw!r} "
+                "(e.g. 'sec.accession:0000320193-25-000079')"
+            )
+        parsed_identities.append({"scheme": scheme.strip(), "value": value.strip()})
+    if parsed_identities:
+        defaults["identities"] = parsed_identities
+
+    row = _cites_row(item_refs, context_refs, status_ref, scenario_ref, custom_dimensions, at)
+    if row and row.get("item_refs"):
+        defaults["cites"] = [row]
+
+    op: dict[str, Any] = {"kind": "add_source", "defaults": defaults}
+    if index is not None:
+        op["index"] = index
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("update-source")
+@click.argument("filename")
+@click.option("--id", "source_id", required=True, help="sourceId to update.")
+@click.option("--kind", default=None, help="New @kind (closed set).")
+@click.option("--role", default=None, help="New @role (free text).")
+@click.option("--reach", default=None, help="public | account | private | offline.")
+@click.option("--title", default=None, help="New title. Pass '' to clear.")
+@click.option("--locator", default=None, help="New locator. Pass '' to clear.")
+@click.option("--description", default=None, help="New description. Pass '' to clear.")
+@click.option("--at", "at", default=None, help="New default position.")
+@click.option("--effective-date", default=None, help="New effective date.")
+@click.option("--retrieved-at", default=None, help="New retrieval timestamp.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def update_source(
+    ctx: Ctx,
+    filename: str,
+    source_id: str,
+    kind: str | None,
+    role: str | None,
+    reach: str | None,
+    title: str | None,
+    locator: str | None,
+    description: str | None,
+    at: str | None,
+    effective_date: str | None,
+    retrieved_at: str | None,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Change fields on a <Source>. Omitted flags are left alone; '' clears."""
+    slug = workspace_slug or ctx.require_workspace()
+    defaults: dict[str, Any] = {}
+    for field, value in (
+        ("kind", kind),
+        ("role", role),
+        ("reach", reach),
+        ("title", title),
+        ("locator", locator),
+        ("description", description),
+        ("at", at),
+        ("effective_date", effective_date),
+        ("retrieved_at", retrieved_at),
+    ):
+        if value is not None:
+            defaults[field] = value
+    if not defaults:
+        raise click.UsageError("Nothing to update - pass at least one field.")
+    op = {"kind": "update_source", "sourceRef": source_id, "defaults": defaults}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("delete-source")
+@click.argument("filename")
+@click.option("--id", "source_id", required=True, help="sourceId to delete.")
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def delete_source(
+    ctx: Ctx,
+    filename: str,
+    source_id: str,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Remove a <Source>. Refused while any <Evidence> still cites it."""
+    slug = workspace_slug or ctx.require_workspace()
+    op = {"kind": "delete_source", "sourceRef": source_id}
+    _apply(ctx, slug, filename, [op], revision=revision)
+
+
+@defs.command("set-source-cites")
+@click.argument("filename")
+@click.option("--id", "source_id", required=True, help="sourceId whose coverage to replace.")
+@_with_cites_options
+@click.option("--at", "at", default=None, help="Position override for this coverage row.")
+@click.option(
+    "--clear",
+    is_flag=True,
+    default=False,
+    help="Remove every coverage row instead of setting one.",
+)
+@click.option("--revision", default=None, help="Expected revision SHA for optimistic locking.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def set_source_cites(
+    ctx: Ctx,
+    filename: str,
+    source_id: str,
+    item_refs: str | None,
+    context_refs: str | None,
+    status_ref: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    at: str | None,
+    clear: bool,
+    revision: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Replace which cells a <Source> backs.
+
+    Coverage is the field revised most often - after values land - so it has
+    its own command: doing it through `update-source` would risk blanking a
+    title by leaving it out of a partial payload.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    if clear:
+        rows: list[dict[str, Any]] = []
+    else:
+        row = _cites_row(item_refs, context_refs, status_ref, scenario_ref, custom_dimensions, at)
+        if not row or not row.get("item_refs"):
+            raise click.UsageError("Pass --items (or --clear to remove all coverage).")
+        rows = [row]
+    op = {"kind": "set_source_cites", "sourceRef": source_id, "cites": rows}
+    _apply(ctx, slug, filename, [op], revision=revision)