deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/describe.py

@@ -0,0 +1,902 @@
+"""``deepcell describe`` — canonical server-side schema discovery."""
+
+from __future__ import annotations
+
+import click
+
+from deepcell_cli.commands._version_display import echo_version_history
+from deepcell_cli._findings import cited_rules_footer, rule_citation
+
+
+def _is_warning(finding: dict) -> bool:
+    """True for advisory findings that must not gate the exit code.
+
+    Severity is optional on describe findings and its absence means error —
+    that is the behaviour every code had before any of them declared one, and
+    defaulting the other way would silently un-gate a real check whose author
+    simply did not know the field existed.
+    """
+    return str(finding.get("severity") or "").strip().lower() == "warn"
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_info, output, print_plain
+
+
+_MAX_ORPHAN_SAMPLES = 3
+
+# Issue #1371 — one line per kind, then up to this many coordinates under it.
+# A model that trips this trips it in bulk — a status left undeclared on a
+# period reports once per cell on it — and 32 sentences read as 32 separate
+# problems rather than one repeated.
+_MAX_STATUS_DIAGNOSTIC_SAMPLES = 3
+
+# Human labels for the `kind` values in `RenderPlan.status_diagnostics`. An
+# unknown kind falls back to its id: `kind` is a bare string on the wire so a
+# server that learns a fourth kind stays additive, and printing the id beats
+# dropping the group.
+_STATUS_DIAGNOSTIC_LABELS = {
+    "ambiguous_status": "several statuses on one cell; one is shown",
+    "ambiguous_write_status": "a recompute had to pick which status to write",
+    # Retired by #1586: a period's statusRef no longer narrows a calc off a
+    # period it explicitly lists, so nothing emits this any more. The label
+    # stays because a RenderPlan cached before that change can still carry one,
+    # and printing "narrowed" beats printing a bare kind id.
+    "incompatible_status_context": "calc narrowed off a period by a status clash "
+                                   "(retired — no longer emitted)",
+    "unresolved_status": "status unresolved; the cell renders BLANK while "
+                         "holding real values",
+}
+
+# Optional item attributes appended after the type tag when present. Mirrors
+# backend jingwei_api/utils/render_plan_schema.py:_OPTIONAL_ITEM_ATTRS.
+_OPTIONAL_ITEM_ATTRS = ("scale", "currency", "order", "parentItem")
+
+# The five dimensions, always in the order a cell's identity is spelled.
+# Mirrors backend `render_plan_schema.py:_DIMENSION_ORDER`.
+_DIMENSION_ORDER = (
+    ("items", "items"),
+    ("contexts", "contexts"),
+    ("statuses", "statuses"),
+    ("scenarios", "scenarios"),
+    ("customDimensions", "custom dims"),
+)
+
+
+def _quoted_name(name: object, fallback: object) -> str:
+    """Return ``"name"`` when it adds info over the id, else an empty string."""
+    if name and name != fallback:
+        return f' "{name}"'
+    return ""
+
+
+def _format_block(block: dict) -> str:
+    """Render one block entry as ``id ("name") [kind]``.
+
+    Mirrors backend ``render_plan_schema.py:_format_block``. The kind is
+    suffixed only for non-table blocks: charts and text blocks emit no grid
+    rows, so `query --sheet` cannot render them back and this listing is where
+    the author confirms they landed.
+    """
+    if not isinstance(block, dict):
+        return str(block)
+    text = f"{block.get('id')}" + _quoted_name(block.get("name"), block.get("id"))
+    kind = block.get("kind")
+    if kind and kind != "table":
+        text += f" [{kind}]"
+    return text
+
+
+def _summarize_meta_value(value: object) -> str:
+    """Render one metadata value inline: scalars pass through, def lists
+    flatten to ``id ("label") [N members]``."""
+    if isinstance(value, list):
+        parts: list[str] = []
+        for el in value:
+            if isinstance(el, dict):
+                part = str(el.get("id"))
+                label = el.get("label")
+                if label:
+                    part += f' ("{label}")'
+                members = el.get("members")
+                if members:
+                    part += f" [{len(members)} members]"
+                parts.append(part)
+            else:
+                parts.append(str(el))
+        return ", ".join(parts)
+    return str(value)
+
+
+#: Members named on one per-sheet dimension line before it folds. Mirrors the
+#: backend constant; every id also appears in full under `definitions`, and the
+#: reader who wants all of them wants `query --sheet`.
+_MAX_SHEET_DIMENSION_MEMBERS = 20
+
+
+def _fold(parts: list) -> str:
+    if len(parts) <= _MAX_SHEET_DIMENSION_MEMBERS:
+        return ", ".join(parts)
+    shown = parts[:_MAX_SHEET_DIMENSION_MEMBERS]
+    return ", ".join(shown) + f", …(+{len(parts) - len(shown)} more)"
+
+
+def _dimension_line(key: str, value: object) -> str:
+    """One dimension's members, inline and folded. Custom dims carry members."""
+    if key == "customDimensions":
+        return _fold([
+            f"{d.get('id')} ({', '.join(str(m) for m in d.get('members') or [])})"
+            if d.get("members")
+            else str(d.get("id"))
+            for d in value  # type: ignore[union-attr]
+            if isinstance(d, dict)
+        ])
+    return _fold([str(v) for v in value])  # type: ignore[union-attr]
+
+
+def _sheet_lines(sheets: list) -> list[str]:
+    """Sheets, each followed by the five dimensions it actually renders."""
+    lines: list[str] = ["Sheets:"]
+    for s in sheets:
+        head = f"  - {s.get('id')}" + _quoted_name(s.get("name"), s.get("id"))
+        blocks = s.get("blocks") or []
+        if blocks:
+            head += " — blocks: " + ", ".join(_format_block(b) for b in blocks)
+        lines.append(head)
+        dims = s.get("dimensions") or {}
+        # `counts` carries the true size of any list the server shortened, so the
+        # header still reports what the sheet renders.
+        counts = dims.get("counts") or {}
+        for key, label in _DIMENSION_ORDER:
+            value = dims.get(key)
+            if not value:
+                continue
+            total = counts.get(key, len(value))
+            lines.append(f"      {label} ({total}): {_dimension_line(key, value)}")
+    return lines
+
+
+def _definitions_lines(definitions: dict) -> list[str]:
+    """The declared five dimensions, with the labels the ids stand for."""
+    lines: list[str] = [
+        "Definitions — the five dimensions that key a cell "
+        "(Item × Context × Status × Scenario × CustomDimensions):"
+    ]
+
+    items = definitions.get("items") or []
+    if items:
+        lines.append(f"  Items ({len(items)}):")
+        for it in items:
+            level = it.get("level") or 0
+            indent = "    " + "  " * (level if isinstance(level, int) and level >= 0 else 0)
+            line = f"{indent}{it.get('id')}" + _quoted_name(it.get("label"), it.get("id"))
+            line += f" [{it.get('type', 'number')}]"
+            extras = [
+                f"{attr}={it[attr]}"
+                for attr in _OPTIONAL_ITEM_ATTRS
+                if it.get(attr) is not None
+            ]
+            if extras:
+                line += " (" + ", ".join(extras) + ")"
+            lines.append(line)
+
+    contexts = definitions.get("contexts") or []
+    if contexts:
+        lines.append(
+            f"  Contexts ({len(contexts)}): " + ", ".join(str(c) for c in contexts)
+        )
+
+    statuses = definitions.get("statuses") or []
+    if statuses:
+        lines.append(
+            f"  Statuses ({len(statuses)}): "
+            + ", ".join(
+                f"{s.get('id')}" + _quoted_name(s.get("label"), s.get("id"))
+                for s in statuses
+            )
+        )
+
+    scenarios = definitions.get("scenarios") or []
+    if scenarios:
+        lines.append(
+            f"  Scenarios ({len(scenarios)}): "
+            + ", ".join(
+                f"{s.get('id')}"
+                + _quoted_name(s.get("label"), s.get("id"))
+                + (" (default)" if s.get("isDefault") else "")
+                for s in scenarios
+            )
+        )
+
+    dims = definitions.get("customDimensions") or []
+    if dims:
+        lines.append(f"  Custom dimensions ({len(dims)}):")
+        for d in dims:
+            members = d.get("members") or []
+            lines.append(
+                f"    {d.get('id')}"
+                + _quoted_name(d.get("label"), d.get("id"))
+                + f" — {len(members)} members: "
+                + ", ".join(
+                    f"{m.get('id')}" + _quoted_name(m.get("label"), m.get("id"))
+                    for m in members
+                )
+            )
+    return lines
+
+
+def _sources_lines(sources: list) -> list[str]:
+    """The `<Source>` registry — one line each, id first."""
+    lines: list[str] = [f"Sources ({len(sources)}):"]
+    for source in sources:
+        line = f"  {source.get('id')}"
+        if source.get("title"):
+            line += f' "{source["title"]}"'
+        tags = [source.get(key) for key in ("kind", "role") if source.get(key)]
+        if tags:
+            line += " [" + ", ".join(str(t) for t in tags) + "]"
+        if source.get("url"):
+            line += f" — {source['url']}"
+        lines.append(line)
+    return lines
+
+
+def _documents_lines(documents: list) -> list[str]:
+    """Each memo's title and heading structure — the shape, not the prose."""
+    lines: list[str] = [f"Documents ({len(documents)}):"]
+    for doc in documents:
+        head = f"  - {doc.get('id')}" + _quoted_name(doc.get("name"), doc.get("id"))
+        if doc.get("lang"):
+            head += f" [{doc['lang']}]"
+        head += f" — {doc.get('block_count', 0)} blocks, {doc.get('link_count', 0)} links"
+        if doc.get("unresolved_link_count"):
+            head += f", {doc['unresolved_link_count']} UNRESOLVED"
+        lines.append(head)
+        for section in doc.get("sections") or []:
+            level = section.get("level") or 1
+            indent = "      " + "  " * max(0, int(level) - 1)
+            line = f"{indent}{'#' * int(level)} {section.get('title')}"
+            anchor = section.get("anchor")
+            if anchor:
+                line += (
+                    f"  {{#{anchor}}}" if section.get("addressable") else f"  (slug: {anchor})"
+                )
+            lines.append(line)
+        for warning in doc.get("warnings") or []:
+            lines.append(f"      ! {warning}")
+    return lines
+
+
+def _decks_lines(decks: list) -> list[str]:
+    """Each deck and its slides in order."""
+    lines: list[str] = [f"Decks ({len(decks)}):"]
+    for deck in decks:
+        head = f"  - {deck.get('id')}" + _quoted_name(deck.get("name"), deck.get("id"))
+        if deck.get("aspect_ratio"):
+            head += f" [{deck['aspect_ratio']}]"
+        slides = deck.get("slides") or []
+        head += f" — {len(slides)} slides, {deck.get('binding_count', 0)} bindings"
+        lines.append(head)
+        for index, slide in enumerate(slides, start=1):
+            lines.append(
+                f"      {index}. {slide.get('id')}"
+                + _quoted_name(slide.get("name"), slide.get("id"))
+            )
+        unresolved = deck.get("unresolved_bindings") or []
+        if unresolved:
+            lines.append(
+                "      ! unresolved bindings: "
+                + ", ".join(str(b) for b in unresolved)
+                + " — these render their fallback text and look intentional."
+            )
+        for warning in deck.get("warnings") or []:
+            lines.append(f"      ! {warning}")
+    return lines
+
+
+#: Rows per reading-path section, and how deep a row's subtree is followed.
+#: Mirrors the backend constants; `-f json` keeps the whole outline, and
+#: `deepcell reasoning graph` renders the full graph.
+_MAX_SECTION_ROWS = 12
+_MAX_ROW_DEPTH = 3
+
+
+def _outline_descendants(nodes: list) -> int:
+    """How many rows a set of subtrees would have printed."""
+    return sum(1 + _outline_descendants(node.get("children") or []) for node in nodes)
+
+
+def _outline_row(
+    node: dict,
+    indent: str,
+    *,
+    show_via: bool = False,
+    depth: int = _MAX_ROW_DEPTH,
+) -> list[str]:
+    """One reading-path row and its subtree, to ``_MAX_ROW_DEPTH``. The id leads:
+    a reader who wants to *act* on a row needs it, and a label is a sentence."""
+    tag = node.get("kind") or node.get("status") or ""
+    parts = [f"{indent}{node.get('id')}"]
+    if tag:
+        parts.append(f"[{tag}]")
+    parts.append(str(node.get("label") or ""))
+    line = " ".join(part for part in parts if part)
+    if show_via and node.get("via"):
+        line += f" — on \"{node['via'].get('label')}\""
+    lines = [line]
+    children = node.get("children") or []
+    if not children:
+        return lines
+    if depth <= 0:
+        # Say how much was folded. A silently shortened chain reads as a chain
+        # that ends there, which is the one thing a reading path must not say.
+        lines.append(f"{indent}  …({_outline_descendants(children)} deeper)")
+        return lines
+    for child in children:
+        lines.extend(
+            _outline_row(child, indent + "  ", show_via=show_via, depth=depth - 1)
+        )
+    return lines
+
+
+#: Subtree depth for the three sections that sit *beside* the argument rather
+#: than in it — "How this was built", "Also cited", "Other threads". Mirrors the
+#: backend constant.
+_APPENDIX_ROW_DEPTH = 1
+
+
+def _outline_section(
+    nodes: list,
+    indent: str,
+    *,
+    show_via: bool = False,
+    depth: int = _MAX_ROW_DEPTH,
+) -> list[str]:
+    """A capped run of sibling rows, with what was cut named."""
+    lines: list[str] = []
+    for node in nodes[:_MAX_SECTION_ROWS]:
+        lines.extend(_outline_row(node, indent, show_via=show_via, depth=depth))
+    remaining = len(nodes) - _MAX_SECTION_ROWS
+    if remaining > 0:
+        lines.append(f"{indent}…(+{remaining} more)")
+    return lines
+
+
+def _outline_to_plain(outline: dict, indent: str = "  ") -> list[str]:
+    """The reading path as lines.
+
+    Mirrors ``jingwei_api/utils/reasoning_outline.py:outline_to_text`` — the
+    same six questions, in the same order, as the Reasoning workspace.
+    """
+    if not isinstance(outline, dict):
+        return []
+    lines: list[str] = []
+    step = indent + "  "
+
+    question = outline.get("keyQuestion")
+    if question:
+        heading = "Key question"
+        source = outline.get("keyQuestionSource")
+        if source:
+            heading += f" ({source})"
+        if outline.get("keyQuestionNeedsReview"):
+            heading += " — needs review"
+        lines.append(f"{indent}{heading}")
+        lines.append(f"{step}{question.get('id')} {question.get('label')}")
+
+    conclusions = outline.get("conclusions") or []
+    if conclusions:
+        heading = (
+            "Main conclusion"
+            if len(conclusions) == 1
+            else f"Conclusions ({len(conclusions)})"
+        )
+        source = conclusions[0].get("source")
+        if source:
+            heading += f" ({source})"
+        lines.append(f"{indent}{heading}")
+        # The conclusion is the one thing this output exists to say, so it is
+        # never folded away — only its subtree is depth-capped like any other.
+        for node in conclusions:
+            lines.extend(_outline_row(node, step))
+    for node in outline.get("comparedWith") or []:
+        lines.extend(_outline_row(node, f"{step}compared with: "))
+
+    for key, label in (
+        ("reasons", "Reasons"),
+        ("conditions", "Conditions"),
+        ("challenges", "Challenges"),
+    ):
+        nodes = outline.get(key) or []
+        if not nodes:
+            continue
+        lines.append(f"{indent}{label} ({len(nodes)})")
+        lines.extend(_outline_section(nodes, step, show_via=key == "challenges"))
+
+    evidence = outline.get("evidence") or []
+    if evidence:
+        lines.append(f"{indent}Evidence ({len(evidence)})")
+        for item in evidence[:_MAX_SECTION_ROWS]:
+            line = f"{step}{item.get('id')} {item.get('label')}"
+            used_by = [ref.get("id") for ref in item.get("usedBy") or []]
+            if used_by:
+                line += f" — cited by {', '.join(str(u) for u in used_by)}"
+            lines.append(line)
+        if len(evidence) > _MAX_SECTION_ROWS:
+            lines.append(f"{step}…(+{len(evidence) - _MAX_SECTION_ROWS} more)")
+
+    for key, label in (
+        ("methodNotes", "How this was built"),
+        ("alsoCited", "Also cited"),
+        ("otherThreads", "Other threads"),
+    ):
+        nodes = outline.get(key) or []
+        if not nodes:
+            continue
+        lines.append(f"{indent}{label} ({len(nodes)})")
+        lines.extend(_outline_section(nodes, step, depth=_APPENDIX_ROW_DEPTH))
+
+    loose = outline.get("looseEnds") or []
+    if loose:
+        lines.append(
+            f"{indent}Loose ends ({len(loose)}) — reachable from nothing the "
+            "conclusion argues"
+        )
+        for finding in loose[:_MAX_SECTION_ROWS]:
+            if finding.get("cause") == "circular":
+                members = " → ".join(
+                    str(node.get("id")) for node in finding.get("nodes") or []
+                )
+                lines.append(f"{step}circular: {members}")
+            else:
+                node = finding.get("node") or {}
+                suffix = (
+                    f" — parent {finding['ref']} is missing"
+                    if finding.get("cause") == "broken_parent"
+                    else " — nothing cites or depends on it"
+                )
+                lines.append(f"{step}{node.get('id')} {node.get('label')}{suffix}")
+        if len(loose) > _MAX_SECTION_ROWS:
+            lines.append(f"{step}…(+{len(loose) - _MAX_SECTION_ROWS} more)")
+
+    for diagnostic in outline.get("diagnostics") or []:
+        lines.append(f"{indent}! {diagnostic.get('message')}")
+
+    return lines
+
+
+def _schema_to_plain(schema: dict) -> str:
+    """Render the describe schema as compact plain text.
+
+    Layout mirrors the backend's ``schema_to_text`` (the agent-tool rendering
+    of the same schema), extended with the ``--lint`` findings section — pre-fix,
+    plain mode printed only counts, so ``--lint`` exited 1 without ever saying
+    why.
+    """
+    lines: list[str] = [f"Model: {schema.get('filename') or '(unnamed)'}"]
+
+    stats = schema.get("stats") or {}
+    # `item_count` counts table rows, so a chart-only document reported
+    # "0 items" — corroborating the unplaced-item report it also emitted, and
+    # both were wrong. Say how many are drawn somewhere other than a grid.
+    off_grid_count = stats.get("off_grid_item_count") or 0
+    item_count = f"{stats.get('item_count', 0)} items"
+    if off_grid_count:
+        item_count += f" (+{off_grid_count} off-grid)"
+    counts = [
+        f"{stats.get('sheet_count', 0)} sheets",
+        f"{stats.get('block_count', 0)} blocks",
+        item_count,
+        f"{stats.get('context_count', 0)} contexts",
+    ]
+    for key, noun in (
+        ("status_count", "statuses"),
+        ("scenario_count", "scenarios"),
+        ("custom_dimension_count", "custom dims"),
+        ("document_count", "documents"),
+        ("deck_count", "decks"),
+        ("source_count", "sources"),
+    ):
+        if stats.get(key):
+            counts.append(f"{stats[key]} {noun}")
+    lines.append("Stats: " + ", ".join(counts))
+
+    sheets = schema.get("sheets") or []
+    if sheets:
+        lines.append("")
+        lines.extend(_sheet_lines(sheets))
+
+    definitions = schema.get("definitions") or {}
+    if any(definitions.get(key) for key, _ in _DIMENSION_ORDER):
+        lines.append("")
+        lines.extend(_definitions_lines(definitions))
+
+    unplaced = schema.get("unplaced_items") or []
+    if unplaced:
+        lines.append("")
+        lines.append(f"Defined but not placed ({len(unplaced)}):")
+        for it in unplaced:
+            lines.append(
+                f"  {it.get('id')}" + _quoted_name(it.get("name"), it.get("id"))
+            )
+        lines.append(
+            "  These items exist in <ItemDefinitions> but sit on no sheet, so "
+            "they are absent from the item list above, the viewer and every "
+            "export. `query` still answers for them. Place one with "
+            "`deepcell defs add-axis-member`."
+        )
+
+    off_grid = schema.get("off_grid_items") or []
+    if off_grid:
+        lines.append("")
+        lines.append(f"Placed, but off the grid ({len(off_grid)}):")
+        for it in off_grid:
+            lines.append(
+                f"  {it.get('id')}" + _quoted_name(it.get("name"), it.get("id"))
+            )
+        lines.append(
+            "  A block claims these — a chart, a sensitivity table or a text "
+            "block — and they render there. They are absent from the item "
+            "list above only because that list is read off table rows. "
+            "Nothing to fix."
+        )
+
+    documents = schema.get("documents") or []
+    if documents:
+        lines.append("")
+        lines.extend(_documents_lines(documents))
+
+    decks = schema.get("decks") or []
+    if decks:
+        lines.append("")
+        lines.extend(_decks_lines(decks))
+
+    sources = schema.get("sources") or []
+    if sources:
+        lines.append("")
+        lines.extend(_sources_lines(sources))
+
+    metadata = schema.get("metadata") or {}
+    if metadata:
+        lines.append("")
+        lines.append("Metadata:")
+        for k, v in metadata.items():
+            lines.append(f"  {k}: {_summarize_meta_value(v)}")
+
+    reasoning = schema.get("reasoning")
+    if isinstance(reasoning, dict):
+        lines.append("")
+        counts_r = reasoning.get("counts") or {}
+        by_kind = reasoning.get("claim_count_by_kind") or {}
+        kind_str = (
+            " (" + ", ".join(f"{k} {v}" for k, v in by_kind.items()) + ")"
+            if by_kind
+            else ""
+        )
+        lines.append(
+            "Reasoning: "
+            f"{counts_r.get('claims', 0)} claims{kind_str}, "
+            f"{counts_r.get('assumptions', 0)} assumptions, "
+            f"{counts_r.get('evidence', 0)} evidence, "
+            f"{counts_r.get('arguments', 0)} arguments"
+        )
+        lines.extend(_outline_to_plain(reasoning.get("outline") or {}))
+        orphans = reasoning.get("orphans") or []
+        if orphans:
+            lines.append(
+                f"  unreferenced nodes ({len(orphans)}): " + ", ".join(map(str, orphans))
+            )
+
+    findings = schema.get("findings")
+    if findings:
+        def _render(f: dict) -> str:
+            # Warnings are prefixed so a reader can tell at a glance which
+            # findings gate the exit code and which are advisory.
+            marker = "warn " if _is_warning(f) else ""
+            return (f"  - {marker}{f.get('rule')}{rule_citation(f)}: "
+                    f"{f.get('message')}")
+
+        lines.append("")
+        # `--since` splits the list in two; without it every finding is
+        # unstamped and this renders exactly as it always did.
+        pre_existing = [f for f in findings if f.get("pre_existing") is True]
+        if pre_existing:
+            introduced = [f for f in findings if f.get("pre_existing") is not True]
+            lines.append(
+                f"Findings ({len(findings)}) — {len(introduced)} new, "
+                f"{len(pre_existing)} pre-existing:"
+            )
+            lines += [_render(f) for f in introduced]
+            if not introduced:
+                lines.append("  (none new — every finding below predates the "
+                             "baseline you named)")
+            lines.append("")
+            lines.append(f"  Pre-existing ({len(pre_existing)}) — already there "
+                         "before the baseline, not introduced by this change:")
+            lines += [_render(f) for f in pre_existing]
+        else:
+            lines.append(f"Findings ({len(findings)}):")
+            lines += [_render(f) for f in findings]
+        footer = cited_rules_footer(findings)
+        if footer:
+            lines.append(footer)
+
+    if schema.get("items_truncated"):
+        lines.append("")
+        lines.append(schema.get("note") or "Item list truncated.")
+
+    # Eval S1: the docstring said "use `deepcell query` for values" but the
+    # output never did — and describe is the orient-stage command, so agents
+    # verified numbers by hand-parsing `cat` XML. End with a copy-pasteable
+    # query built from this file's own refs (R4: verify by query-back).
+    def_items = definitions.get("items") or []
+    def_contexts = definitions.get("contexts") or []
+    example_item = str(def_items[0].get("id")) if def_items else "<item>"
+    example_ctx = str(def_contexts[0]) if def_contexts else "<context>"
+    lines.append("")
+    lines.append(
+        "Values: the definitions above are not the numbers — read cells back "
+        f"with `deepcell query {schema.get('filename') or '<file>'} "
+        f"{example_item} {example_ctx}` (rules R4)."
+    )
+
+    return "\n".join(lines)
+
+
+def _format_unrendered_values_warning(orphans: list[dict]) -> str:
+    """Build the human warning shared with structural write commands.
+
+    One line per uncovered COORDINATE, matching the record the builder emits
+    (#1906): a cell stored under two statuses is one gap that one `<Block>`
+    closes, so both statuses go on the one line rather than printing it twice.
+    The repair is `defs add-axis-member`, which is what edits a live block's
+    axes — `--item-orders` / `--context-refs` are `add-block` flags.
+    """
+    count = len(orphans)
+    plural = "" if count == 1 else "s"
+    lines = [
+        f"warning: {count} coordinate{plural} not shown on any sheet — they exist",
+        "         in <Values> and feed the calc engine but render nowhere.",
+        "         Examples:",
+    ]
+    for orphan in orphans[:_MAX_ORPHAN_SAMPLES]:
+        statuses = orphan.get("status_refs") or (
+            [orphan["status_ref"]] if orphan.get("status_ref") else []
+        )
+        dims = "".join(
+            f" × {kv[0]}={kv[1]}" for kv in (orphan.get("custom_dimensions") or ())
+        )
+        lines.append(
+            "           "
+            f"{orphan.get('item_ref', '?')} × {orphan.get('context_ref', '?')} × "
+            f"{', '.join(str(s) for s in statuses) or '-'}{dims}"
+            f"  =  {orphan.get('value', '')}"
+        )
+    remaining = count - _MAX_ORPHAN_SAMPLES
+    if remaining > 0:
+        lines.append(f"           …({remaining} more)")
+    lines.extend([
+        "         Widen a block's rows or columns to cover these item × context",
+        "         pairs (`deepcell defs add-axis-member`), add a <Block>, or",
+        "         remove the values, to silence this warning.",
+    ])
+    return "\n".join(lines)
+
+
+def _format_status_diagnostics_warning(diagnostics: list[dict]) -> str:
+    """Build the human warning for `RenderPlan.status_diagnostics` (#1371).
+
+    Reads the STRUCTURED record, not the prose `message`: grouping by `kind`
+    and naming coordinates is exactly what the message channel cannot do, and
+    the message is already printed verbatim under `describe`'s "Export notes".
+    Shared with `defs apply`, which is where a user *creates* a status clash
+    (`defs add-calc --status`, `defs update-context --status`) and so the
+    moment the warning is due — not a follow-up command they must know to run.
+
+    Deliberately a warning and not an exit code, per
+    `docs/status-resolution.md` §2.4a: these describe a document that opens and
+    renders, and failing hard would stop a working-if-malformed model from
+    being read.
+    """
+    by_kind: dict[str, list[dict]] = {}
+    for diag in diagnostics:
+        by_kind.setdefault(str(diag.get("kind") or "unknown"), []).append(diag)
+
+    count = len(diagnostics)
+    plural = "" if count == 1 else "s"
+    lines = [
+        f"warning: {count} status diagnostic{plural} — the document renders, "
+        "but it",
+        "         leaves a status question open. Not a lint finding; it does "
+        "not affect",
+        "         --lint's exit code. See `deepcell guide verify/query-back`.",
+    ]
+    for kind, group in by_kind.items():
+        label = _STATUS_DIAGNOSTIC_LABELS.get(kind, kind)
+        lines.append(f"         {kind} ({len(group)}) — {label}")
+        for diag in group[:_MAX_STATUS_DIAGNOSTIC_SAMPLES]:
+            chosen = diag.get("chosen") or "-"
+            available = diag.get("available_statuses") or []
+            lines.append(
+                "           "
+                f"{diag.get('item_ref', '?')} × {diag.get('context_ref', '?')}"
+                f"  shows {chosen}"
+                + (f"; also holds {', '.join(str(s) for s in available)}"
+                   if available else "")
+            )
+        remaining = len(group) - _MAX_STATUS_DIAGNOSTIC_SAMPLES
+        if remaining > 0:
+            lines.append(f"           …({remaining} more)")
+    return "\n".join(lines)
+
+
+@click.command()
+@click.argument("filename")
+@click.option(
+    "--include-reasoning",
+    is_flag=True,
+    default=False,
+    help="Append a compact summary of the document reasoning graph.",
+)
+@click.option(
+    "--scenario",
+    "scenario_id",
+    default=None,
+    help="Scenario ID whose value overrides to apply.",
+)
+@click.option(
+    "--lint",
+    "lint_mode",
+    is_flag=True,
+    default=False,
+    help="Include canonical structural findings; exit 1 on error-level ones. "
+    "Warn-level findings print and exit 0 — read them.",
+)
+@click.option(
+    "--since",
+    "since_revision",
+    default=None,
+    metavar="REVISION",
+    help="With --lint: mark each finding pre-existing or new against this "
+    "revision. Use `HEAD~1` for the commit before yours, or a SHA from "
+    "`deepcell log`.",
+)
+@click.option(
+    "--measure",
+    "measure",
+    is_flag=True,
+    default=False,
+    help="With --lint: measure every deck slide that has no fit measurement "
+    "yet (one browser pass per slide in the export service) before "
+    "reporting. Slides are measured on the write that changes them; use "
+    "this for a deck that arrived by sync or upload, or was restyled.",
+)
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def describe(
+    ctx: Ctx,
+    filename: str,
+    include_reasoning: bool,
+    scenario_id: str | None,
+    lint_mode: bool,
+    since_revision: str | None,
+    measure: bool,
+    workspace_slug: str | None,
+) -> None:
+    """Show a document's shape: sheets, the five dimensions, documents, decks.
+
+    The cheapest way to orient in a file you did not write — read this before
+    querying or editing, so refs are copied rather than guessed. It returns
+    the definitions and counts, not the values: use `deepcell query` for
+    values, `deepcell cat` for the raw XML.
+
+    Each sheet lists the five dimensions IT renders; "Definitions" then lists
+    every declared one (Item × Context × Status × Scenario × CustomDimensions),
+    which is what keys a cell. Documents report their heading structure and
+    decks their slides — the shape of each deliverable, not its prose — and
+    "Sources" lists the <Source> registry the evidence cites.
+
+    Add --lint for structural findings and --include-reasoning for the reading
+    path: the key question, the conclusion, and what argues for and against it
+    — the same walk, in the same order, as the Reasoning panel in the viewer.
+
+    --lint exits 1 only on error-level findings (unrendered_value,
+    empty_rendered_block, monetary_units, hardcoded_literal_in_calc,
+    deck_overflow, deck_underfilled, deck_slide_empty,
+    deck_bind_undeclared). Warn-level findings —
+    undeclared_status_archetype, undeclared_context_state,
+    percentage_not_a_fraction, deck_hero_figure_repeated and the other deck_*
+    codes — print with a `warn`
+    prefix and exit 0, so a clean exit is not "no findings". `deepcell guide
+    verify/lint` lists every code with its severity.
+
+    --lint reports the WHOLE model, not the part you just changed, so on a
+    scoped edit most findings are usually someone else's. Add `--since HEAD~1`
+    and each one is marked (pre-existing) or (new) — the exit code is
+    unchanged, so a model that was already failing still fails.
+
+    Deck slides are measured for fit on the write that changes them (the
+    `defs apply` / `deck` response carries the fill line), and --lint reports
+    the remembered result: `deck_overflow`, `deck_underfilled` and
+    `deck_slide_empty` all gate, and each underfill finding names the remedy
+    for that slide. A slide with no measurement — synced or uploaded —
+    reports `deck_slide_unmeasured`; add --measure to measure those first
+    (one browser pass per slide in the export service).
+
+    "Export notes" is where status problems surface — `status_unresolved` (a
+    cell holding several statuses that renders blank because nothing says
+    which) and `status_ambiguity` (it renders one of several). These are NOT
+    lint findings and do NOT affect the --lint exit code, so read them even
+    when --lint exits clean. See `deepcell guide verify/query-back`.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    if since_revision and not lint_mode:
+        raise click.UsageError(
+            "--since only applies to --lint findings. Add --lint, or drop "
+            "--since."
+        )
+    if measure and not lint_mode:
+        raise click.UsageError(
+            "--measure only applies to --lint findings. Add --lint, or drop "
+            "--measure."
+        )
+    body: dict = {
+        "workspace_slug": slug,
+        "source_filename": filename,
+        "include_reasoning": include_reasoning,
+        "lint": lint_mode,
+    }
+    if measure:
+        body["measure"] = True
+    if since_revision:
+        body["since_revision"] = since_revision
+    if scenario_id:
+        body["scenario_id"] = scenario_id
+
+    response = ctx.client.post("/describe", json=body)
+    schema = response.get("schema", {}) if isinstance(response, dict) else {}
+    orphans = (
+        response.get("unrendered_values") or []
+        if isinstance(response, dict)
+        else []
+    )
+
+    if ctx.fmt == "plain" and isinstance(schema, dict):
+        print_plain(_schema_to_plain(schema))
+    else:
+        output(schema, ctx.fmt)
+    if isinstance(response, dict):
+        echo_version_history(response)
+        # Structural problems the render-plan build hit (unsupported block,
+        # dimension-expansion cap, a scenario that did not apply). Without
+        # these, `describe` reports a model as fully rendered while `to-excel`
+        # warns about the same document. Grouped under their own heading and
+        # kept out of the ⚠ shape (eval U6): printed bare next to the lint
+        # output, the flat-sheet note read as a finding and sent a worker
+        # chasing a lint code that did not exist.
+        conv_warnings = response.get("warnings") or []
+        if conv_warnings:
+            echo_info("Export notes (informational — not lint findings):")
+            for warning in conv_warnings:
+                echo_info(f"  {warning}")
+    if orphans:
+        click.echo(_format_unrendered_values_warning(orphans), err=True)
+    # Issue #1371 — the same diagnostics printed as prose above, re-read from
+    # the STRUCTURED record and grouped by kind with their coordinates. The
+    # prose reads as one flat informational line per cell; a model that ships
+    # 32 `status_unresolved` cells needs to see "32 of one thing", which only
+    # the record supports. On stderr, next to the orphan warning, so it is not
+    # mistaken for part of the JSON/plain schema on stdout.
+    diagnostics = (
+        response.get("status_diagnostics") or []
+        if isinstance(response, dict)
+        else []
+    )
+    if diagnostics:
+        click.echo(_format_status_diagnostics_warning(diagnostics), err=True)
+    # Gate on errors only. A finding may declare `severity: "warn"` — the
+    # undeclared-semantics codes do, because every document written before
+    # `@archetype` existed omits it and gating would fail the whole corpus on
+    # day one. An absent severity still means error, so the original describe
+    # codes gate exactly as before. `deepcell guide verify/lint` carries the
+    # generated table of which codes are which.
+    if lint_mode and any(not _is_warning(f) for f in schema.get("findings") or []):
+        click.get_current_context().exit(1)