auroraomics 0.1.0.dev1__tar.gz → 0.1.0.dev2__tar.gz

{auroraomics-0.1.0.dev1/src/auroraomics.egg-info → auroraomics-0.1.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auroraomics
-Version: 0.1.0.dev1
+Version: 0.1.0.dev2
 Summary: Virtual spatial transcriptomics from H&E histology: patch QC, tile packing and the .h5ad result contract.
 Author: Kalin Nonchev
 License-Expression: PolyForm-Noncommercial-1.0.0
@@ -205,10 +205,11 @@ its weights never leave it. What crosses between us is a vector from a model
 neither side owns.
 
 ```python
-from auroraomics.runtimes.deepspotm import available_models, check_archive
+from auroraomics.runtimes.deepspotm import check_archive, describe_models
 
-available_models()                      # what the service will run
-check_archive("sample.zip", model=...)  # are my tiles the right physical size?
+cards = client.models()                                 # the catalogue is the service's
+describe_models(cards)                                  # what it will run, and on what
+check_archive("sample.zip", model=MODEL, cards=cards)   # are my tiles the right size?
 ```
 
 Then submit with the API client and read the result back — the same `.h5ad`

{auroraomics-0.1.0.dev1 → auroraomics-0.1.0.dev2}/README.md

@@ -162,10 +162,11 @@ its weights never leave it. What crosses between us is a vector from a model
 neither side owns.
 
 ```python
-from auroraomics.runtimes.deepspotm import available_models, check_archive
+from auroraomics.runtimes.deepspotm import check_archive, describe_models
 
-available_models()                      # what the service will run
-check_archive("sample.zip", model=...)  # are my tiles the right physical size?
+cards = client.models()                                 # the catalogue is the service's
+describe_models(cards)                                  # what it will run, and on what
+check_archive("sample.zip", model=MODEL, cards=cards)   # are my tiles the right size?
 ```
 
 Then submit with the API client and read the result back — the same `.h5ad`

{auroraomics-0.1.0.dev1 → auroraomics-0.1.0.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "auroraomics"
-version = "0.1.0.dev1"
+version = "0.1.0.dev2"
 description = "Virtual spatial transcriptomics from H&E histology: patch QC, tile packing and the .h5ad result contract."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -31,7 +31,7 @@ classifiers = [
 # install line the quickstart prints is an install line that can do what the
 # quickstart says.
 #
-# It was four names until #691, with the API client and the slide reader behind
+# It was four names once, with the API client and the slide reader behind
 # extras of their own. The comment on the extras below has always ended "the
 # line is at the ENCODER, not at the size of an install"; these lists did not
 # say it. They put a half-megabyte HTTP client behind the same ceremony as a
@@ -39,7 +39,7 @@ classifiers = [
 # auroraomics` could not then perform a single documented step. They say it now.
 #
 # WHAT IT COSTS, measured rather than estimated (importlib.metadata over the
-# transitive closure, on the interpreter this package targets, 2026-09-11): four
+# transitive closure, on the interpreter this package targets): four
 # distributions and 179 MB became twenty-eight and 537 MB. Neither of the two
 # that dominate is named here — `imagecodecs` (142 MB) is what lets `tifffile`
 # decode a real slide, and `pandas` plus `scipy` (198 MB between them) arrive
@@ -79,7 +79,7 @@ dependencies = [
 # resolves the model, or the adapter and checkpoint stack that would carry one,
 # and `predict_local` refuses with a message that says so. What runs on a user's
 # own machine is cutting, filtering and EMBEDDING tiles — their pixels stay put,
-# and a vector from an open-weight encoder is what crosses. So the line is at the
+# and a vector from the encoder is what crosses. So the line is at the
 # ENCODER, not at the size of an install: `embed` below does resolve a tensor
 # runtime, on purpose, and everything on the CLIENT side of the encoder — the
 # HTTP client, the slide reader — sits in the core above, where nobody has to
@@ -88,7 +88,7 @@ dependencies = [
 # encoder's four stay named, no shipped module imports either, and the release
 # guard refuses a wheel carrying a module that is not on its published list.
 #
-# `client` and `slide` were extras until #691 and are GONE rather than kept as
+# `client` and `slide` were extras once and are GONE rather than kept as
 # empty aliases. The published wheel declares both, so `pip install
 # "auroraomics[client]"` exists in the wild and in our own older prose; pip
 # WARNS on an extra a distribution does not provide and installs anyway —
@@ -121,7 +121,7 @@ mcp = ["mcp>=2,<3"]
 #
 # anndata used to be listed here as a test-only dependency, with a note saying
 # that depending on it at run time would put pandas and its stack into every
-# install. That is now exactly what happens, knowingly (#691) — the note above
+# install. That is now exactly what happens, knowingly — the note above
 # the core list records the price — so this extra no longer names anndata, nor
 # `tifffile` or `imagecodecs`, because the core already does. A second bound
 # here would be a test environment resolving what no user resolves. anndata is
@@ -141,7 +141,7 @@ dev = [
   # Coverage is measured on every run, with a floor, because this package is
   # the one that SHIPS: a user installs it and calls it, so a branch nothing
   # here exercises is a branch discovered in the field. The floor sat at
-  # nothing until 2026-09-06, when the suite measured 94%.
+  # nothing until the suite first measured 94%.
   "pytest-cov>=5",
   # setuptools and wheel are TEST dependencies as well as build ones: the
   # release guard builds with --no-isolation so that it needs no network, and
@@ -223,8 +223,8 @@ source = ["src/auroraomics"]
 # when a real gap closes; never lower it to make a change pass.
 #
 # 92 rather than the 94.18 measured hours earlier, and the difference is not a
-# regression in anything tested here. #519 turned `predict_local` into a refusal
-# and moved the forward pass to the unpublished distribution — but left
+# regression in anything tested here. Turning `predict_local` into a refusal
+# moved the forward pass to the unpublished distribution — but left
 # `runtimes/deepspotm.py`'s `_panel_rows` and `_selection` behind, and their
 # ONLY callers are now in the unpublished inference distribution's runner. So
 # that file went from 271 statements at 99% to 169 at 73%: 46 statements this
@@ -233,8 +233,8 @@ source = ["src/auroraomics"]
 #
 # Moving those two helpers to the package that uses them takes the floor back
 # above 94 without writing a single test. Recorded as an issue rather than done
-# here, because it is a change to the boundary #519 drew and belongs with that
-# work, not with a coverage floor.
+# here, because it is a change to the boundary that refusal drew and belongs
+# with that work, not with a coverage floor.
 fail_under = 92
 # Two decimals, because `fail_under` is compared at this precision and rounding
 # 93.6 to 94 would pass a suite that had slipped.

{auroraomics-0.1.0.dev1 → auroraomics-0.1.0.dev2}/src/auroraomics/__init__.py

@@ -1,7 +1,7 @@
 """Virtual spatial transcriptomics from H&E histology.
 
 **One journey, and one word chooses which.** Send the tiles, or send only the
-vectors computed from them; everything either side of that word is the same:
+embeddings computed from them; everything either side of that word is the same:
 
     import auroraomics as ao
 
@@ -105,10 +105,10 @@ _EXPORTS: dict[str, str] = {
 
 Two properties, and the table buys both.
 
-``resolve_encoder`` is here because since #694 it is on the journey rather than
-beside it: ``embed_tiles`` takes a resolved encoder and the registry is the
-service's, so ``resolve_encoder(client.encoders(), name)`` is a line every
-caller who embeds tiles writes by hand.
+``resolve_encoder`` is here because it is on the journey rather than beside it:
+``embed_tiles`` takes a resolved encoder and the registry is the service's, so
+``resolve_encoder(client.encoders(), name)`` is a line every caller who embeds
+tiles writes by hand.
 
 **It is short.** Thirty-three names stood here while the two journeys through
 this package used two of them between them, because a module's whole public

{auroraomics-0.1.0.dev1 → auroraomics-0.1.0.dev2}/src/auroraomics/_contracts/MANIFEST.json

@@ -3,6 +3,6 @@
   "files": {
     "public-api-counters.tokens.json": "4f5dd14ce76f7001d36940dfc1d1f49feac9ec1be2e7646d47b29ab21c124a8f",
     "public-api-input-kinds.tokens.json": "1c80e2637d27f2491ea178e2fa87e2a435640e5445791b2fd20adc53a574e54d",
-    "public-api.tokens.json": "43ecf0f47c2d480464e7a936c0522041a74803c47a364432ba62f356a4a699d5"
+    "public-api.tokens.json": "a8d3253978aba375c1933aef3f3069bcb4b5e47c2edbf6062a08c95c0f255f4d"
   }
 }

{auroraomics-0.1.0.dev1 → auroraomics-0.1.0.dev2}/src/auroraomics/_contracts/public-api.tokens.json

@@ -354,8 +354,14 @@
     "uns_keys": [
       "model",
       "input_spec",
-      "job"
-    ]
+      "job",
+      "resolution"
+    ],
+    "resolution_checks": {
+      "slide": "slide_metadata",
+      "none": "nothing",
+      "unstated": "unstated"
+    }
   },
   "rateBuckets": {
     "read": {

{auroraomics-0.1.0.dev1 → auroraomics-0.1.0.dev2}/src/auroraomics/_text.py

@@ -38,7 +38,7 @@ def not_one_file(path, *, instead: str) -> str:
     return f"{path} is not a regular file; {instead}"
 
 EMBEDDING_COMPONENT = "DeepSpot-H"
-"""The step that turns tiles into vectors, named as a reader meets it.
+"""The step that turns tiles into embeddings, named as a reader meets it.
 
 Typed once, and imported by every message that names it. It was written out
 five times across `cli.py` and `runtimes/deepspotm.py` — the defect the

{auroraomics-0.1.0.dev1 → auroraomics-0.1.0.dev2}/src/auroraomics/bulk.py

@@ -157,10 +157,10 @@ Resolver = Callable[[Sequence[str]], Mapping[str, "str | None"]]
 [Client.resolve_keys][auroraomics.client.api.Client.resolve_keys] is one, and so is
 any callable a caller writes over their own mapping.
 
-An ARGUMENT since #694, because the gene table is the model's own output axis
-and the service holds it — this module used to read a 3.7 MB copy vendored into
-the wheel, which was frozen at build time and was a second implementation of the
-service's resolution order besides.
+An ARGUMENT rather than a lookup this module performs, because the gene table is
+the model's own output axis and the service holds it — this module used to read a
+3.7 MB copy vendored into the wheel, which was frozen at build time and was a
+second implementation of the service's resolution order besides.
 """
 
 
@@ -446,7 +446,7 @@ def _asked_once(resolve: Resolver) -> Resolver:
     decides the layout by resolving ``header[1:]``, and then returns exactly
     those names as the pairs — which ``_resolve_all`` resolves again. Two
     identical passes over a transcriptome's worth of names, and since resolution
-    became the service's (#694), two passes over the NETWORK: measured on a
+    became the service's, two passes over the NETWORK: measured on a
     2,000-column table, the resolver was called twice with 2.0x the header.
 
     Per CALL, not per process. A resolver is a live connection to one
@@ -513,7 +513,7 @@ def _coverage_reference(card: Mapping[str, Any]) -> tuple[frozenset[str], str]:
     """The gene set coverage is judged against: the model's measured set.
 
     The card's, always. It used to fall back to the whole vendored gene table for
-    a caller who named no model, and that fallback went with the table (#694) —
+    a caller who named no model, and that fallback went with the table —
     which is no loss: coverage of "every gene the family can predict" was never
     the number the service refuses on.
     """
@@ -571,7 +571,7 @@ def bulk_rna(
         ``output.gene_mask`` is the measured gene set coverage is judged
         against — the same refusal the service would make. It used to be
         optional, with the vendored gene table standing in; the table is the
-        service's now (#694), and "coverage of every gene the family predicts"
+        service's now, and "coverage of every gene the family predicts"
         was never a number the service refuses on.
     resolve:
         How a symbol becomes the Ensembl id a result is keyed by:

{auroraomics-0.1.0.dev1 → auroraomics-0.1.0.dev2}/src/auroraomics/cli.py

@@ -238,15 +238,11 @@ fetching a finished job's result is what that command is for — while
 and holds both directions: a command declaring ``--wait`` with no row here, or
 a row naming a flag that command does not declare, is a red build.
 """
-
 OUTPUT_NEEDS_WAIT = f"needs --wait: {NEEDS_WAIT['submit']['output']}"
 """What ``submit --output``'s help says, DERIVED from the table the refusal
 reads. It is the flag's own help, the sentence the command's description
 carries, and what the refusal says — and those three drifted once already, which
-is why it is one string. It stopped being one for an hour on 2026-09-10, when
-the refusal moved into a table and the help did not: the existing test caught
-it, which is the whole reason that test names the constant rather than a
-phrase."""
+is why it is one string."""
 
 ACCESS_PENDING_CODE = "access_pending"
 """The mint refusal for an account that has asked and is waiting; the catalogue's code."""
@@ -427,7 +423,7 @@ def _calibration_check(args: argparse.Namespace, model_id: str) -> dict[str, Any
     Every other check in ``doctor`` is cheap, so this one runs only when a
     model is named: it loads an encoder and runs one forward pass. What it buys
     is the answer to the question worth asking before a slide is embedded — will
-    the service accept vectors from this machine — asked once, on one image,
+    the service accept embeddings from this machine — asked once, on one image,
     instead of after an hour of tiles.
 
     Reported, never raised, like every check here: each way it cannot be
@@ -444,7 +440,7 @@ def _calibration_check(args: argparse.Namespace, model_id: str) -> dict[str, Any
             cards = {str(card.get("id")): card for card in client.models()}
             # Fetched in the same session as the cards, because both are the
             # service's now: an encoder is a pinned repository and revision, and
-            # this package stopped carrying a copy of that pin with #694.
+            # this package no longer carries a copy of that pin.
             registry = client.encoders()
     except Exception as exc:  # noqa: BLE001 - a diagnostic reports, it does not raise
         return verdict(False, str(exc))
@@ -455,7 +451,7 @@ def _calibration_check(args: argparse.Namespace, model_id: str) -> dict[str, Any
     reads = accepted_observations(card)
     locally = _embedded_locally()
     if reads and locally and locally not in reads:
-        # This check asks whether vectors from THIS machine would be accepted. A
+        # This check asks whether embeddings from THIS machine would be accepted. A
         # model that reads the tiles themselves is never handed one, so there is
         # no question to ask — and asking it anyway loaded an encoder the caller
         # on that route has every reason not to have installed, then reported
@@ -490,41 +486,108 @@ def _calibration_check(args: argparse.Namespace, model_id: str) -> dict[str, Any
 
     try:
         name = _encoder_name(spec, embed.describe_encoders(registry))
-        vector = _as_a_file_holds_it(
-            embed.calibrate(embed.resolve_encoder(registry, name)), spec
-        )
+        encoder = embed.resolve_encoder(registry, name)
+        run = embed.calibration_pass(encoder, allow_download=args.allow_download)
+        vector, stored = _as_a_file_would_hold_it(run.embedding, spec)
         distance = embed.calibration_offset(vector, reference["reference"])
     except Exception as exc:  # noqa: BLE001
         return verdict(False, str(exc))
     within = distance <= tolerance
+    pace, projection = _pace(run, args.tiles)
     return verdict(
         within,
         f"{name} on this machine is {distance:.3g} from {model_id}'s reference "
-        f"(tolerance {tolerance:.3g})"
-        + ("" if within else "; vectors from this machine would be refused"),
+        f"(tolerance {tolerance:.3g}, measured as {stored} — the element type a "
+        "file written here carries)"
+        + ("" if within else "; embeddings from this machine would be refused")
+        + f". {pace}",
         model=model_id,
         encoder=name,
         offset=distance,
         tolerance=tolerance,
+        dtype=stored,
+        device=run.device,
+        seconds_per_tile=run.seconds,
+        **projection,
     )
 
 
-def _as_a_file_holds_it(vector: Any, spec: dict[str, Any]) -> Any:
-    """The forward pass rounded into the element type the card pins.
+def _as_a_file_would_hold_it(vector: Any, spec: dict[str, Any]) -> tuple[Any, str]:
+    """The forward pass rounded the way the file this machine writes will be.
+
+    The lane compares the numbers a submission STORES, so measuring the raw
+    forward pass here would make the client kinder than the service by exactly
+    that rounding, at the boundary the tolerance sits on. A machine told it
+    agrees and an hour of embedding refused afterwards is the failure this whole
+    check exists to prevent.
+
+    TWO things claim to say what a file stores, and they are not the same thing:
+    the card pins an ``input_spec.dtype``, and
+    [embed_tiles][auroraomics.embed.embed_tiles] writes at
+    [DEFAULT_DTYPE][auroraomics.embed.DEFAULT_DTYPE] — it is handed an encoder,
+    not a model, so it never reads the card. Today the two agree, by coincidence
+    of value rather than by construction, and a card that moved to the wider
+    type would leave this check measuring a rounding no file here would carry.
+    So it measures at whichever of them rounds HARDER, and names it: being
+    stricter than the lane costs a caller a second look, being kinder costs them
+    the afternoon.
+
+    A ``dtype`` the container does not allow is not one of the two: such a file
+    cannot be submitted at all, and it is its element type that would be
+    refused, not its calibration — so the writer's own is used alone.
+    """
+    import numpy as np
+
+    from auroraomics import embed
 
-    The lane compares the numbers a submission STORES, and the writer stores
-    this vector in the card's ``dtype`` — so measuring the raw forward pass
-    here would make the client kinder than the service by that rounding, at
-    exactly the boundary the tolerance sits on. A machine told it agrees and an
-    hour of embedding refused afterwards is the failure this whole check exists
-    to prevent.
+    allowed = contracts.embeddings_npz()["dtypes"]
+    pinned = str(spec.get("dtype") or "")
+    candidates = [embed.DEFAULT_DTYPE, *([pinned] if pinned in allowed else [])]
+    # Narrowest wins, by the element type's own width rather than by a list
+    # written here in an order someone has to keep right.
+    stored = min(candidates, key=lambda name: np.dtype(name).itemsize)
+    return vector.astype(stored), stored
 
-    A ``dtype`` the container does not allow is left alone: such a file cannot
-    be submitted at all, and it is its element type that would be refused, not
-    its calibration.
+
+def _pace(run: Any, tiles: int | None) -> tuple[str, dict[str, Any]]:
+    """What a tile costs on THIS machine, and what that makes of a slide.
+
+    The one number `doctor` was already measuring and throwing away. The
+    published table for ``batch_size`` is a CUDA device's, and the lane most
+    callers run on is the CPU — a different order of magnitude on the same
+    encoder — so "minutes to hours" was a range a caller only resolved by
+    starting. A machine can be asked, in the pass that was happening anyway.
+
+    Stated as an upper bound, because that is what it is: one tile to a pass,
+    where a run feeds ``batch_size`` of them and pays less per tile.
     """
-    stored = str(spec.get("dtype") or "")
-    return vector.astype(stored) if stored in contracts.embeddings_npz()["dtypes"] else vector
+    per = f"One tile takes {run.seconds * 1000:,.0f} ms on {run.device} here"
+    if not tiles:
+        return (
+            f"{per}, one tile to a pass — an upper bound, since a run feeds a "
+            "whole batch at a time. Pass --tiles to turn that into a slide's "
+            "wall clock.",
+            {},
+        )
+    total = run.seconds * tiles
+    return (
+        f"{per}, so {tiles:,} tiles is at most {_how_long(total)} — one tile to "
+        "a pass, and a run feeds a whole batch at a time for less per tile.",
+        {"tiles": int(tiles), "estimated_seconds": total},
+    )
+
+
+def _how_long(seconds: float) -> str:
+    """A duration in the unit a reader decides with, never in bare seconds.
+
+    "14,073 s" and "3.9 hours" are the same number and only one of them answers
+    "do I start this before lunch".
+    """
+    if seconds < 90:
+        return f"{seconds:.0f} seconds"
+    if seconds < 90 * 60:
+        return f"{seconds / 60:.0f} minutes"
+    return f"{seconds / 3600:.1f} hours"
 
 
 def _encoder_name(spec: dict[str, Any], known: dict[str, Any]) -> str:
@@ -550,7 +613,7 @@ def _encoder_name(spec: dict[str, Any], known: dict[str, Any]) -> str:
             if differing:
                 raise errors.ClientError(
                     f"the card's {', '.join(differing)} differ(s) from what this release pins for "
-                    f"{name}; upgrade the package rather than trust a vector computed another way"
+                    f"{name}; upgrade the package rather than trust an embedding computed another way"
                 )
             return name
     raise errors.ClientError(
@@ -747,7 +810,7 @@ def kind_charged_in(unit: str) -> str:
     """The observation kind the registry charges by ``unit``.
 
     The two routes differ in what a submission IS, and the registry already
-    says so: the tiles are charged per tile, the vectors per row. So the
+    says so: the tiles are charged per tile, the embeddings per row. So the
     sentence that describes each route reads its kind from the contract instead
     of naming it.
 
@@ -771,7 +834,7 @@ def _embedded_locally() -> str:
     """The observation kind a caller computes on their own machine, or ``""``.
 
     The two routes differ in where tiles become numbers, and the registry
-    already says which is which by what it charges: the vectors are charged per
+    already says which is which by what it charges: the embeddings are charged per
     ROW. Read from there rather than from ``embed.KIND``, for the reason
     [kind_charged_in][auroraomics.cli.kind_charged_in] gives — this runs inside
     ``doctor``, which is the command an install with no encoder runtime in it is
@@ -796,8 +859,8 @@ def _example_of(kind: str) -> str:
 
     Mixing the two put the same example in both halves of one sentence, so the
     submit description read "`embeddings=sample.npz` sends the tiles
-    themselves; `embeddings=sample.npz` sends the vectors", in the shipped help
-    and on the site.
+    themselves; `embeddings=sample.npz` sends the embeddings", in the
+    shipped help and on the site.
     """
     try:
         extensions = contracts.container_extensions(contracts.input_kind(kind)["container"])
@@ -806,13 +869,52 @@ def _example_of(kind: str) -> str:
     return f"{kind}=sample{extensions[0]}" if extensions else f"{kind}=..."
 
 
+# The covariate entry arrived with the served card's own declaration of it; the
+# date and the change that carried it are in this file's history, and not in the
+# docstring below, which mkdocstrings publishes.
+CATALOGUED_KIND: dict[str, str] = {OBSERVATION_SLOT: "embeddings", COVARIATE_SLOT: "bulk_rna"}
+"""The kind each slot's worked example names when no catalogue is in hand, as
+the published catalogue read when this package was built.
+
+DERIVED, and the derivation is [servable_kinds][auroraomics.cli.servable_kinds]
+itself — the same rule applied to the same cards, run against the catalogue the
+contracts publish rather than against one fetched now.
+`test_the_recorded_kind_is_what_the_catalogue_derives_today` recomputes it and
+names the answer it expected, so a card published for another kind turns a
+build red instead of leaving the first journey a reader is shown quietly wrong.
+
+RECORDED RATHER THAN FETCHED, because the caller here is help. `build_parser`
+runs on ``--help``, on ``--version`` and on every usage refusal — always before
+a credential is read, usually before one exists, and for a reader whose first
+act is to type the command and see what it says. A value that took a request
+would make that depend on a network, a key and a deployment being up; and the
+answer on a bad day would be a fallback, which is the defect this replaces
+rather than a fix for it. The catalogue a reader can actually submit against is
+one command away and `models` answers it for the deployment they are on.
+
+A SLOT WITH NO PUBLISHED KIND IS ABSENT, not guessed at — there is nothing to
+derive from, and inventing something would be this same defect in the other
+flag. Both slots have one now that a served card declares a covariate, so
+``--covariate`` stops showing the registry's own first row and shows the kind a
+reader can actually send. The guard above covers each slot separately, and
+skips the one the catalogue has nothing for.
+"""
+
+
 def _example(slot: str) -> str:
-    """A whole argument a reader can copy, built from the registry's first kind.
+    """A whole argument a reader can copy, with a kind the catalogue accepts.
 
     The kind and the file extension are both the contract's; only the stem is
     invented, and a stem is the one part of an example that has to be.
+
+    Three sources, in order: the catalogue when the caller holds one, the kind
+    [CATALOGUED_KIND][auroraomics.cli.CATALOGUED_KIND] recorded for this slot,
+    and the registry's first row last. That last one is a tiebreak in a list,
+    not an answer about what is served — it printed `patches` for as long as it
+    decided this, while the only card served refused it.
     """
-    kinds = servable_kinds(slot) or kinds_in(slot)
+    recorded = CATALOGUED_KIND.get(slot)
+    kinds = servable_kinds(slot) or ((recorded,) if recorded else ()) or kinds_in(slot)
     if not kinds:  # pragma: no cover - held by test_the_slots_are_the_registrys_own
         return ""
     first = kinds[0]
@@ -828,6 +930,8 @@ def _example(slot: str) -> str:
     return f"{first}=sample{extensions[0]}" if extensions else f"{first}=..."
 
 
+# The cards are not vendored into this wheel, which is why the fallback below
+# is the registry and not a card.
 def servable_kinds(slot: str, cards: Iterable[Mapping[str, Any]] = ()) -> tuple[str, ...]:
     """The kinds the models in ``cards`` will accept, in registry order.
 
@@ -840,11 +944,18 @@ def servable_kinds(slot: str, cards: Iterable[Mapping[str, Any]] = ()) -> tuple[
 
     ``cards`` is EMPTY on every path that builds help text, and that is not an
     oversight. Help is rendered before a command runs and without a credential,
-    and the cards are the service's since #694 — this used to read a card
+    and the cards are the service's — this used to read a card
     vendored into the wheel, which meant a build could print the accepts of a
-    model the deployment it is pointed at does not serve. An empty catalogue
-    falls back to the registry: an example is better than none, and `models` is
-    one command away and answers for the deployment the caller is actually on.
+    model the deployment it is pointed at does not serve.
+
+    What an empty catalogue falls back to is
+    [CATALOGUED_KIND][auroraomics.cli.CATALOGUED_KIND], which is this function's
+    own answer over the published cards, recorded when the package was built and
+    held to them by a test. It fell back to the registry's first row until then,
+    and that row is a position in a list rather than a statement about what is
+    served: it named `patches`, no published card reads that kind, and the
+    journey the top-level help opens with sent a reader's whole archive before
+    the service could say so.
     """
     accepted = {
         kind
@@ -975,6 +1086,22 @@ def _described(text: str) -> str:
     return "\n\n".join(blocks)
 
 
+def _a_count(text: str) -> int:
+    """An argparse type for "how many of something", refused at the boundary.
+
+    Zero and below are not small runs, they are a caller who meant something
+    else, and a projection built from either prints a confident nonsense. Caught
+    here, argparse answers with its own usage line before any work starts.
+    """
+    try:
+        value = int(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"{text!r} is not a whole number") from None
+    if value < 1:
+        raise argparse.ArgumentTypeError(f"{value} is not a count; give at least 1")
+    return value
+
+
 def build_parser() -> argparse.ArgumentParser:
     # These two options may be written on EITHER side of the subcommand, and the
     # top-level help advertises the left-hand side. Making that true takes two
@@ -1023,7 +1150,7 @@ def build_parser() -> argparse.ArgumentParser:
             f"  auroraomics submit --model ID --observation {_example(OBSERVATION_SLOT)} --wait\n"
             "  auroraomics download JOB_ID -o result.h5ad\n\n"
             f"Build the sample with the Python package: auroraomics.embed_tiles "
-            f"runs {EMBEDDING_COMPONENT} on your machine and sends vectors instead "
+            f"runs {EMBEDDING_COMPONENT} on your machine and sends embeddings instead "
             "of pixels, and auroraomics.pack_tiles sends the tiles themselves. "
             "`auroraomics models` says which of the two a model takes. "
             "`auroraomics doctor` says whether this machine is ready before you "
@@ -1063,7 +1190,7 @@ def build_parser() -> argparse.ArgumentParser:
     # Positional, because this is the first command anyone runs and the address
     # is the whole of it: `auroraomics login you@institution.edu` is what every
     # page prints and what a person types. It was `--email` and the two
-    # disagreed for as long as the pages existed (#636).
+    # disagreed for as long as the pages existed.
     login_parser.add_argument("email", metavar="EMAIL", help="the address of the account to sign in")
     login_parser.add_argument(
         "--code",
@@ -1095,7 +1222,13 @@ def build_parser() -> argparse.ArgumentParser:
             "Checks the installed version, the contract documents shipped with "
             "it, the stored credential and whether the deployment is taking "
             "work. Each check prints ok or FAIL; the exit code is 0 only when "
-            "every one passed."
+            "every one passed.\n\n"
+            "--model answers the two questions worth asking before an "
+            "hours-long run, in one forward pass: will this machine's numbers "
+            "be accepted, and what does a tile cost here. The published "
+            "throughput figures are a CUDA device's; a CPU is a different order "
+            "of magnitude, and yours is the one that matters. Add --tiles to "
+            "turn that into a wall clock for the slide."
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
@@ -1111,7 +1244,36 @@ def build_parser() -> argparse.ArgumentParser:
         help=(
             f"also run {EMBEDDING_COMPONENT} over the reference image shipped in this "
             "package and compare the result with this model's reference, which "
-            "answers whether vectors from this machine would be accepted"
+            "answers whether embeddings from this machine would be accepted — "
+            "and time the pass, which answers how long the slide will take"
+        ),
+    )
+    doctor.add_argument(
+        "--tiles",
+        type=_a_count,
+        default=None,
+        metavar="N",
+        help=(
+            "how many tiles you mean to embed; turns the timed pass of --model "
+            "into a wall clock for the whole run before you start it"
+        ),
+    )
+    # THE ADVICE THE FAILURE GIVES HAS TO BE TAKEABLE BY WHOEVER READS IT.
+    # Without `--model` this check is not run at all and nothing fetches
+    # anything; with it and the weights uncached, the refusal says to permit the
+    # download — and said it as `allow_download=True`, a PYTHON keyword
+    # argument, to a reader who is holding a shell. There was no CLI form of it
+    # and no other subcommand that fetched weights either, so the one machine
+    # this command exists to get ready could not be got ready from the command
+    # line. Opt-in, and default off, for the reason `calibrate` states:
+    # a diagnostic does not start a gigabyte download nobody asked for.
+    doctor.add_argument(
+        "--allow-download",
+        action="store_true",
+        help=(
+            "let --model fetch the weights it needs if this machine does not "
+            "already hold them; without it a missing encoder is reported, not "
+            "downloaded"
         ),
     )
     doctor.set_defaults(handler=cmd_doctor)
@@ -1181,7 +1343,7 @@ def build_parser() -> argparse.ArgumentParser:
             "Send one sample for prediction and print the job it created.\n\n"
             "The sample is an --observation. "
             f"`{_example_of(packed_kind)}` sends the tiles themselves; "
-            f"`{_example_of(embedded_kind)}` sends the vectors "
+            f"`{_example_of(embedded_kind)}` sends the embeddings "
             f"{EMBEDDING_COMPONENT} computed from them on your machine, so the "
             "pixels never leave it. Either way a path is uploaded first, and an "
             "upload id you already hold is used as it stands.\n\n"
@@ -1233,7 +1395,13 @@ def build_parser() -> argparse.ArgumentParser:
     submit.add_argument(
         "--land-in-workspace",
         action="store_true",
-        help="also open the result in the web workspace when it finishes",
+        # This said "open the result in the web workspace", and nothing opens
+        # anything: the result is offered to the same account's own workspace
+        # inbox, which nobody else reads, and importing it into a workspace is
+        # a separate step the account holder takes. A flag that moves data has
+        # to say what it does, because the privacy page that describes the
+        # destination and who can see it from there is written against this.
+        help="offer the finished result to the same account's web workspace, to import there",
     )
     submit.add_argument(
         "--idempotency-key",