drowse.ai 5.3.1__py3-none-any.whl

drowse/cli/parsers.py

@@ -0,0 +1,1478 @@
+"""Argparse builders for the drowse CLI."""
+
+from __future__ import annotations
+
+import argparse
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+def _positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return parsed
+
+
+def _nonnegative_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 0:
+        raise argparse.ArgumentTypeError("must be a non-negative integer")
+    return parsed
+
+
+def _bounded_int(lo: int, hi: int):
+    def parse(value: str) -> int:
+        parsed = int(value)
+        if not lo <= parsed <= hi:
+            raise argparse.ArgumentTypeError(f"must be in [{lo}, {hi}]")
+        return parsed
+
+    return parse
+
+
+def _add_config_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("-c", "--config", action="append", default=None, metavar="PATH",
+                   help="Load setup YAML (repeatable; later overrides earlier)")
+    p.add_argument("-s", "--strict", action="store_true",
+                   help="With -c: fail hard on missing vectors")
+
+
+def _add_logit_args(p: argparse.ArgumentParser) -> None:
+    """Logit-capture options for model-backed CLI surfaces.
+
+    Phase 1 of the logit pass: ``--top-k-alts`` sets the session-level
+    default for ``SamplingConfig.return_top_k`` — the number of top-K
+    alternatives the engine decodes per generated token (with text). K=0
+    (the default) means "logprob only", a near-free addition on top of
+    the existing log_softmax in the loom path. K>0 enables the
+    distributional surfaces (drilldown logits tab, inline surprise tint,
+    NodeCompareDrawer logit columns); ~60 KB/turn on the wire at K=8.
+    Per-call ``SamplingConfig.return_top_k > 0`` overrides; K=0 inherits.
+    YAML equivalent: ``return_top_k:`` nonnegative int.
+    """
+    p.add_argument(
+        "--top-k-alts", dest="top_k_alts", type=_nonnegative_int,
+        default=None, metavar="N",
+        help="Session default for top-K alternatives capture. "
+             "0 (default) = chosen-token logprob only; N>0 ships top-N "
+             "decoded alternatives per token for distributional surfaces. "
+             "Unset = inherit YAML ``return_top_k:`` / session default.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Top-level parsers
+# ---------------------------------------------------------------------------
+
+# Verb table for ``drowse manifold <verb>`` — the *compute* surface.  A
+# steering vector is the K=2 case of a flat affine subspace, so the former
+# ``subspace`` verbs (extract / bake / compare / why) fold into the one
+# ``manifold`` verb alongside the full steering-manifold authoring tree.
+# This table is the source of truth for both parser registration order and
+# the bare-verb help block.
+_MANIFOLD_VERBS: list[tuple[str, str]] = [
+    ("extract",   "Extract a steering vector (a 2-node flat subspace)"),
+    ("generate",  "Author a discover-mode manifold from a concept list"),
+    ("from-template", "Author a discover manifold from a standalone template"),
+    ("fit",       "Fit an authored or discover-mode manifold"),
+    ("bake",      "Bake existing vectors into a new manifold"),
+    ("merge",     "Union discover-mode manifolds' nodes into a new manifold"),
+    ("transfer",  "Transfer a manifold to another model via Procrustes"),
+    ("compare",   "Cosine similarity between steering vectors"),
+    ("why",       "Show which layers contribute most to a steering vector"),
+]
+
+# Verb table for ``drowse pack <verb>`` — the *lifecycle* surface (install /
+# share / inspect / remove).  These were the lifecycle leaves of the former
+# ``manifold`` verb; they address an on-disk manifold by ``(namespace, name)``
+# and never load a model.
+_PACK_VERBS: list[tuple[str, str]] = [
+    ("ls",        "List installed manifolds"),
+    ("show",      "Show a manifold's nodes and fitted models"),
+    ("install",   "Install a manifold from HF or a local folder"),
+    ("search",    "Search the HuggingFace hub for manifolds"),
+    ("push",      "Push a manifold to HF as a model repo"),
+    ("rm",        "Fully remove a manifold folder"),
+    ("clear",     "Delete per-model fitted tensors for a manifold"),
+    ("refresh",   "Re-pull / re-materialize a manifold from its source"),
+    ("export",    "Export a manifold as GGUF or .drowse"),
+]
+
+_EXPERIMENT_VERBS: list[tuple[str, str]] = [
+    ("fan",         "Run an alpha grid as one experiment"),
+    ("transcript",  "Replay or inspect saved transcript paths"),
+    ("naturalness", "Score a steered generation's behavior-manifold naturalness"),
+]
+
+# Verb table for ``drowse template <verb>`` — the standalone templated-completion
+# artifact (a slot + candidate values + multi-turn contexts).  Lifecycle verbs
+# (create/ls/show/rm) are pure-IO; ``score`` loads a model for the restricted-
+# choice logprob read.
+_TEMPLATE_VERBS: list[tuple[str, str]] = [
+    ("create",  "Author a template (slot + values + multi-turn contexts)"),
+    ("ls",      "List installed templates"),
+    ("show",    "Show a template's slot, values, and contexts"),
+    ("score",   "Score the value distribution against each context (loads a model)"),
+    ("rm",      "Remove a template folder"),
+]
+
+# Verb table for ``drowse lens <verb>`` — the per-model Jacobian lens
+# (Gurnee et al. 2026): per-layer transport ``J_l = E[∂h_final/∂h_l]`` +
+# vocabulary readout.  ``fit`` loads a model and runs the only backward
+# passes in drowse; ``top``/``decompose`` load a model for one forward;
+# lifecycle verbs are source-aware: local payloads live under DROWSE_HOME,
+# while external payloads remain in provider caches behind pinned bindings.
+_LENS_VERBS: list[tuple[str, str]] = [
+    ("fit",       "Fit the model's Jacobian lens over a text corpus"),
+    ("fetch",     "Fetch an external lens into its provider cache"),
+    ("ls",        "List local and external lens sources for a model"),
+    ("show",      "Show the active or selected lens source"),
+    ("use",       "Select an already available lens source"),
+    ("top",       "Lens readout on a prompt: top vocabulary tokens per layer"),
+    ("decompose", "Split a steerable direction into its J-space component"),
+    ("rm",        "Remove a local lens or forget an external binding"),
+]
+
+_SAE_VERBS: list[tuple[str, str]] = [
+    ("train", "Train a local residual-post sparse autoencoder"),
+    ("fetch", "Fetch an external SAE into its provider cache"),
+    ("ls",    "List local and external SAE sources for a model"),
+    ("show",  "Show the active or selected SAE source"),
+    ("use",   "Select an already available SAE source"),
+    ("rm",    "Remove a local SAE or forget an external binding"),
+]
+
+
+def _add_dls_arg(p: argparse.ArgumentParser) -> None:
+    """The ``--no-dls`` opt-out, shared by every fit-capable surface.
+
+    ``manifold extract`` / ``manifold fit`` carry this alone: the rest of
+    :func:`_add_injection_args` is generation-time compilation state, which
+    an artifact-authoring verb has no use for.
+    """
+    p.add_argument(
+        "--no-dls", dest="no_dls", action="store_true",
+        help="Keep every extracted layer instead of dropping layers whose "
+             "fitted poles do not straddle the neutral baseline.",
+    )
+
+
+def _add_injection_args(p: argparse.ArgumentParser) -> None:
+    """Steering and extraction options for model-backed CLI surfaces.
+
+    ``None`` defaults flow through to the YAML override layer (or ultimately
+    to the session defaults: Mahalanobis projection + DLS on).
+    """
+    _add_dls_arg(p)
+    p.add_argument(
+        "--compile", dest="compile", action="store_true",
+        help="Enable ``torch.compile`` on CUDA or MPS. Off by default because "
+             "of its upfront cost and architecture-specific compiler failures. "
+             "Unsteered and static-affine generations, including live probes, "
+             "use the persistent compiled path; dynamic or transient-hook "
+             "work falls back to eager. CPU is a no-op. YAML equivalent: "
+             "``compile: true``.",
+    )
+    p.add_argument(
+        "--cuda-graphs", dest="cuda_graphs", action="store_true",
+        help="Enable ``transformers.StaticCache`` + CUDA-graph capture "
+             "for additional decode speedup (1.5–2.5× on small models "
+             "on top of plain ``--compile``).  Off by default for the "
+             "same reason as ``--compile``.  Requires ``--compile`` to "
+             "be useful — when on, ``torch.compile(mode=\"reduce-"
+             "overhead\")`` captures decode CUDA graphs internally.  "
+             "Auto-skipped on MPS/CPU and on architectures whose "
+             "StaticCache constructor fails (logged once at session "
+             "init).  YAML equivalent: ``cuda_graphs: true``.",
+    )
+
+
+def _build_serve_parser(parser: argparse.ArgumentParser) -> None:
+    # When a -c/--config YAML with model: set is supplied, the positional
+    # can be omitted. Handled in _run_serve via the composed config.
+    parser.add_argument("model", nargs="?", default=None,
+                        help="HuggingFace model ID or local path")
+    parser.add_argument(
+        "-q", "--quantize",
+        choices=["4bit", "8bit"],
+        default=None,
+        help="Quantization mode (default: bf16/fp16)",
+    )
+    parser.add_argument(
+        "-d", "--device",
+        default="auto",
+        help="Device: auto (detect), cuda, mps, or cpu (default: auto)",
+    )
+    parser.add_argument(
+        "-p", "--probes",
+        nargs="*",
+        default=None,
+        help="Probe categories: all, none, epistemic, alignment, register, cultural (default: all)",
+    )
+    parser.add_argument("-H", "--host", default="127.0.0.1", help="Bind address (non-loopback requires an API key)")
+    parser.add_argument(
+        "-P", "--port", type=_bounded_int(1, 65535), default=8000,
+        help="Bind port",
+    )
+    parser.add_argument("-S", "--steer", default=None, metavar="EXPR",
+                        help='Default steering expression, e.g. "0.5 honest + 0.3 warm"')
+    parser.add_argument("-C", "--cors", action="append", default=[], metavar="ORIGIN",
+                        help="CORS allowed origin (repeatable)")
+    parser.add_argument("-k", "--api-key", default=None, metavar="KEY",
+                        help="Require Bearer token auth; falls back to $DROWSE_API_KEY")
+    parser.add_argument("--no-web", dest="no_web", action="store_true",
+                        help="Skip the analytics dashboard mount at / "
+                             "(API-only mode for production / proxied deployments)")
+    _add_injection_args(parser)
+    _add_logit_args(parser)
+    _add_config_args(parser)
+
+
+# --- pack subtree --------------------------------------------------------
+
+# --- subspace / manifold subtree -----------------------------------------
+
+def _build_vector_extract(p: argparse.ArgumentParser) -> None:
+    p.add_argument("concept", nargs="+",
+                   help="Either one concept (e.g. 'happy.sad') or two poles (e.g. 'happy' 'sad')")
+    p.add_argument("-m", "--model", default=None, metavar="MODEL_ID")
+    p.add_argument("-f", "--force", action="store_true")
+    p.add_argument(
+        "--sae", default=None, metavar="RELEASE",
+        help="Extract via a SAELens SAE release. No implicit default — you "
+             "must name a release.",
+    )
+    p.add_argument(
+        "--role", default=None, metavar="SLUG",
+        help="Role-augmented extraction: render the contrast pairs under a "
+             "chat template whose assistant-role label is replaced by SLUG "
+             "(e.g. 'pirate'), so the fit lives in role-baselined activation "
+             "space. The role bakes into the generated node corpora and the "
+             "fit writes the canonical tensor and returns its "
+             "``:role-<slug>`` selector. Slug must match ``[a-z0-9._-]+``. "
+             "Mutually exclusive with ``--sae``. Mistral-3 families don't "
+             "carry a substitutable role label and raise at runtime.",
+    )
+    p.add_argument(
+        "--kind", choices=("abstract", "concrete", "custom"), default="abstract",
+        help=(
+            "Conceptual kind for both poles (default: abstract).  Selects the "
+            "generation system template + elicitation role label: abstract -> "
+            "'someone {c}', concrete -> '{art} {c}', custom -> the --system "
+            "template (no role swap).  Same knob `manifold generate` carries."
+        ),
+    )
+    p.add_argument(
+        "--system", dest="custom_system", default=None, metavar="TEMPLATE",
+        help=(
+            "Custom elicitation system prompt for --kind custom; use {c} for "
+            "the concept.  The framing rides the system prompt and the corpus "
+            "pools in standard-assistant space, so it works on every model "
+            "family.  Required when --kind custom."
+        ),
+    )
+    p.add_argument(
+        "--namespace", default=None, metavar="NS",
+        help="Destination namespace for the extracted concept manifold. "
+             "Unset lands under "
+             "``~/.drowse/manifolds/local/<canonical>/``. Any other "
+             "value relocates to "
+             "``manifolds/<namespace>/<canonical>/``. Parity with the "
+             "webui ExtractDrawer's namespace control and with "
+             "``manifold`` / ``discover``'s NS slot.",
+    )
+    _add_dls_arg(p)
+    p.set_defaults(quantize=None, device="auto", probes=None)
+
+
+def _build_vector_merge(p: argparse.ArgumentParser) -> None:
+    p.add_argument("name", help="New manifold name (written under local/)")
+    p.add_argument(
+        "expression",
+        help=(
+            'Merge expression, e.g. "0.3 ns/a + 0.4 ns/b" or '
+            '"0.5 ns/a~ns/b" for projection-removal.'
+        ),
+    )
+    p.add_argument("-f", "--force", action="store_true")
+    p.add_argument("-s", "--strict", action="store_true")
+    p.add_argument("-m", "--model", default=None, metavar="MODEL_ID")
+
+
+def _build_vector_compare(p: argparse.ArgumentParser) -> None:
+    p.add_argument("concepts", nargs="+",
+                   help="One or more concept selectors (names, tag:x, namespace:x, all)")
+    p.add_argument("-m", "--model", required=True, metavar="MODEL_ID",
+                   help="Model id (used to locate baked tensors)")
+    p.add_argument("-v", "--verbose", action="store_true",
+                   help="Show per-layer breakdown (2-arg pairwise mode)")
+    p.add_argument("-j", "--json", dest="json_output", action="store_true",
+                   help="Emit machine-readable JSON")
+    p.add_argument(
+        "--ridge-scale", type=float, default=1.0, metavar="FLOAT",
+        help=(
+            "Ridge multiplier on the regularized covariance "
+            "(λ_L = (||X_L||_F²/(N·D)) × ridge_scale); default 1.0 (mean "
+            "diagonal of the un-regularized sample covariance).  Compare is "
+            "Mahalanobis-only — it reads cached neutral activations + layer "
+            "means under ~/.drowse/models/<id>/ to build the per-layer "
+            "whitener and fails if the cache is missing."
+        ),
+    )
+
+
+def _build_vector_why(p: argparse.ArgumentParser) -> None:
+    p.add_argument("concept", help="Concept selector (name or ns/name)")
+    p.add_argument("-m", "--model", required=True, metavar="MODEL_ID",
+                   help="Model id (used to locate the baked tensor)")
+    p.add_argument("-j", "--json", dest="json_output", action="store_true",
+                   help="Emit machine-readable JSON (full per-layer detail)")
+
+
+def _build_manifold_fit(fit: argparse.ArgumentParser) -> None:
+    """``drowse manifold fit`` — fit an authored *or* discover-mode manifold.
+
+    The 4.0 fold of the former ``fit`` (authored folder positional) and
+    ``discover`` (name → folder + hyperparam overrides) verbs into one.
+    The positional is a name-or-folder (``_run_manifold_fit`` resolves it),
+    and the discover hyperparam knobs are accepted but apply only when the
+    resolved folder is discover-mode (``pca`` / ``spectral``); supplying any
+    of them against an authored folder is an error.
+    """
+    fit.add_argument(
+        "target", help="manifold name or folder path",
+    )
+    fit.add_argument("-m", "--model", default=None, metavar="MODEL_ID")
+    fit.add_argument("-f", "--force", action="store_true")
+    fit.add_argument(
+        "--layers", default=None, metavar="L1,L2,...|workspace|all",
+        help="Fit only selected transformer layers (default: all; workspace "
+             "uses the 40–90%% depth band)",
+    )
+    fit.add_argument(
+        "--sae", default=None, metavar="RELEASE",
+        help="Fit in an SAELens SAE feature space; centroids are reconstructed "
+             "through the SAE before the fit.",
+    )
+    # Discover-mode hyperparam overrides.  Written into ``manifold.json``
+    # before the fit; rejected against an authored folder.
+    fit.add_argument(
+        "--method", choices=("pca", "spectral", "auto"), default=None,
+        help="Discover-mode: override the folder's fit_mode. 'auto' picks "
+             "flat (pca) vs curved (spectral) by GCV and detects periodic "
+             "axes via persistent homology (default: keep folder's setting)",
+    )
+    fit.add_argument(
+        "--max-dim", dest="max_dim", type=_positive_int, default=None, metavar="N",
+        help="Discover-mode: cap intrinsic dimension "
+             "(default: 8 for PCA, 8 for spectral)",
+    )
+    fit.add_argument(
+        "--min-dim", dest="min_dim", type=_positive_int, default=None, metavar="N",
+        help="Discover spectral: floor the intrinsic dimension the "
+             "eigenvalue-ratio cliff picks (the cliff undershoots when one "
+             "mode dominates — set --min-dim == --max-dim to pin the dim "
+             "exactly, e.g. PAD's 3). Valid only for spectral/auto fits.",
+    )
+    fit.add_argument(
+        "--var-threshold", dest="var_threshold", type=float, default=None,
+        metavar="T",
+        help="Discover PCA: smallest cumulative-variance prefix that "
+             "crosses T is picked (default: 0.70)",
+    )
+    fit.add_argument(
+        "--k-nn", dest="k_nn", type=_positive_int, default=None, metavar="K",
+        help="Discover spectral: number of nearest neighbors in the k-NN "
+             "graph (default: max(5, ceil(log K)))",
+    )
+    fit.add_argument(
+        "--bandwidth", type=float, default=None, metavar="SIGMA",
+        help="Discover spectral: heat-kernel bandwidth "
+             "(default: median k-NN distance)",
+    )
+    fit.add_argument(
+        "--max-subspace-dim", dest="max_subspace_dim", type=_positive_int,
+        default=None,
+        metavar="R",
+        help="Discover spectral (curved) only: per-layer RBF subspace dim "
+             "cap (default 64). Smaller values give finer-grained steering "
+             "control at large K — each axis the RBF can move along is an "
+             "axis subspace_inject can displace, so fewer axes = smaller "
+             "per-α effect = wider coherence regime. Valid only for spectral/auto "
+             "(a flat fit's subspace dim is its layout dim — use --max-dim).",
+    )
+    fit.add_argument(
+        "--smoothing", dest="smoothing", default=None, metavar="LAMBDA",
+        help="Discover spectral/auto (curved): penalized-RBF smoothing — "
+             "'auto' (GCV-selected, the default), '0' (exact interpolation), "
+             "or a float λ. Valid only for spectral/auto (no PCA RBF surface).",
+    )
+    fit.add_argument(
+        "--persistence-frac", dest="persistence_frac", type=float,
+        default=None, metavar="F",
+        help="Discover auto: H1 loop-significance threshold as a fraction of "
+             "the connectivity scale (default 0.5); higher = stricter periodic "
+             "detection. Valid only for --method auto.",
+    )
+    _add_dls_arg(fit)
+    fit.set_defaults(quantize=None, device="auto", probes=None)
+
+
+def _build_manifold_generate(generate: argparse.ArgumentParser) -> None:
+    generate.add_argument("name", help="Manifold name (use ns/name for non-local)")
+    generate.add_argument(
+        "--concepts", nargs="+", required=True, metavar="CONCEPT",
+        help="Concept slugs to generate corpora for (>= 2)",
+    )
+    generate.add_argument(
+        "--kind", choices=("abstract", "concrete", "custom"), default="abstract",
+        help=(
+            "Conceptual kind for every node (default: abstract).  Selects the "
+            "generation system template + elicitation role label: abstract -> "
+            "'someone {c}', concrete -> '{art} {c}', custom -> the --system "
+            "template (no role swap)."
+        ),
+    )
+    generate.add_argument(
+        "--system", dest="custom_system", default=None, metavar="TEMPLATE",
+        help=(
+            "Custom elicitation system prompt for --kind custom; use {c} for "
+            "the concept (e.g. \"You are the month of {c}; speak as that "
+            "month.\").  The framing rides the system prompt and the corpus "
+            "pools in standard-assistant space, so it works on every model "
+            "family.  Required when --kind custom."
+        ),
+    )
+    generate.add_argument(
+        "--samples-per-prompt", dest="samples_per_prompt",
+        type=_positive_int, default=1, metavar="K",
+        help="In-character responses generated per baseline prompt (default: 1)",
+    )
+    generate.add_argument(
+        "--description", default="", metavar="TEXT",
+        help="Human-readable description for the manifold folder",
+    )
+    generate.add_argument(
+        "--seed", type=int, default=None, metavar="INT",
+        help="Seed the response generation for reproducible corpora "
+             "(default: unseeded)",
+    )
+    generate.add_argument(
+        "--role-per-node", dest="role_per_node", action="store_true",
+        help=(
+            "Role-augmented (persona) manifold: use each --concepts slug "
+            "as that node's assistant-role substitution at fit time.  The "
+            "fitted manifold lives in persona-baseline activation space "
+            "and steering through it implies the nearest node's role at "
+            "decode time (role-paired manifold steering).  Slugs must "
+            "match [a-z0-9._-]+; family must carry a substitutable role "
+            "header (Qwen / Gemma / Llama / GLM / gpt-oss / talkie — "
+            "Mistral-3 raises at fit time)."
+        ),
+    )
+    generate.add_argument(
+        "-f", "--force", action="store_true",
+        help="Overwrite an existing manifold folder",
+    )
+    generate.add_argument("-m", "--model", default=None, metavar="MODEL_ID")
+    generate.set_defaults(quantize=None, device="auto", probes=None)
+
+
+def _build_manifold_from_template(p: argparse.ArgumentParser) -> None:
+    p.add_argument("template", help="Template name (or ns/name) to derive from")
+    p.add_argument(
+        "--name", default=None, metavar="MANIFOLD",
+        help="Manifold name to write (default: the template name; use ns/name "
+             "for a non-local namespace).",
+    )
+    p.add_argument(
+        "--fit-mode", dest="fit_mode",
+        choices=("pca", "spectral", "auto"), default="auto",
+        help="Discover fit mode written into the folder (default: auto — picks "
+             "flat/curved + detects periodic axes, the right default for cyclic "
+             "categories like days/months).",
+    )
+    p.add_argument(
+        "--max-dim", dest="max_dim", type=_positive_int, default=None, metavar="N",
+        help="Cap the discovered intrinsic dimension (optional).",
+    )
+    p.add_argument(
+        "--var-threshold", dest="var_threshold", type=float, default=None,
+        metavar="T", help="PCA cumulative-variance threshold for dim selection.",
+    )
+    p.add_argument(
+        "--description", default="", metavar="TEXT",
+        help="Human-readable description for the manifold folder",
+    )
+    p.add_argument(
+        "-f", "--force", action="store_true",
+        help="Overwrite an existing manifold folder",
+    )
+
+
+def _build_manifold_merge(merge: argparse.ArgumentParser) -> None:
+    merge.add_argument("name", help="New manifold name (or ns/name)")
+    merge.add_argument(
+        "sources", nargs="+", metavar="SOURCE",
+        help="Two or more discover-mode source manifolds (name or ns/name)",
+    )
+    merge.add_argument(
+        "--description", default="", metavar="TEXT",
+        help="Human-readable description for the merged manifold folder",
+    )
+    merge.add_argument(
+        "--method", choices=("pca", "spectral", "auto"), default=None,
+        help="Override the merged fit_mode (default: the sources' shared "
+             "mode; required when sources disagree)",
+    )
+    merge.add_argument(
+        "-f", "--force", action="store_true",
+        help="Overwrite an existing manifold folder",
+    )
+
+
+def _build_manifold_transfer(transfer: argparse.ArgumentParser) -> None:
+    transfer.add_argument("name", help="Manifold name (or ns/name)")
+    transfer.add_argument(
+        "--from", dest="src_model", required=True, metavar="SRC_MODEL",
+        help="Source model id (where the manifold was fitted)",
+    )
+    transfer.add_argument(
+        "--to", dest="tgt_model", required=True, metavar="TGT_MODEL",
+        help="Target model id (where the transferred manifold will live)",
+    )
+    transfer.add_argument(
+        "-f", "--force", action="store_true",
+        help="Recompute alignment + transfer even when cached",
+    )
+    transfer.add_argument(
+        "-j", "--json", dest="json_output", action="store_true",
+        help="Emit machine-readable JSON (path + quality summary)",
+    )
+
+
+# --- pack lifecycle leaf builders ----------------------------------------
+
+def _build_pack_ls(ls: argparse.ArgumentParser) -> None:
+    ls.add_argument("--namespace", default=None, metavar="NS",
+                    help="Restrict to a single namespace")
+    ls.add_argument("-j", "--json", dest="json_output", action="store_true")
+    ls.add_argument("-v", "--verbose", action="store_true",
+                    help="Include descriptions in the table output")
+
+
+def _build_pack_show(show: argparse.ArgumentParser) -> None:
+    show.add_argument("name", help="Manifold name (or ns/name)")
+    show.add_argument("-j", "--json", dest="json_output", action="store_true")
+
+
+def _build_pack_install(install: argparse.ArgumentParser) -> None:
+    install.add_argument(
+        "target",
+        help="<ns>/<name>[@revision], manifold folder, or .drowse path",
+    )
+    install.add_argument(
+        "-a", "--as", dest="as_target", default=None, metavar="NS/NAME",
+        help="Relocate the installed manifold under a different "
+             "namespace/name (must be fully qualified)",
+    )
+    install.add_argument(
+        "-f", "--force", action="store_true",
+        help="Overwrite an existing installation",
+    )
+
+
+def _build_pack_search(search: argparse.ArgumentParser) -> None:
+    search.add_argument(
+        "query", nargs="?", default="",
+        help="Search text (matched against HF model ids)",
+    )
+    search.add_argument(
+        "-j", "--json", dest="json_output", action="store_true",
+        help="Emit machine-readable JSON instead of a table",
+    )
+    search.add_argument(
+        "-v", "--verbose", action="store_true",
+        help="Include descriptions in the table output",
+    )
+
+
+def _build_pack_push(push: argparse.ArgumentParser) -> None:
+    push.add_argument("selector", help="Single manifold (name or ns/name)")
+    push.add_argument(
+        "-a", "--as", dest="as_target", default=None, metavar="OWNER/NAME",
+        help="Target HF coord (default: <whoami>/<name>)",
+    )
+    push.add_argument(
+        "-m", "--model", default=None, metavar="MODEL_ID",
+        help="Restrict the pushed tensors to one base model",
+    )
+    # Long-only, deliberately: `-p` is `--probes` and `-d` is `--device`
+    # everywhere else in the tree, and `pack push` is the one verb that
+    # publishes.  Muscle memory must not flip visibility or skip the upload.
+    push.add_argument(
+        "--private", action="store_true",
+        help="Create the target repo as private",
+    )
+    push.add_argument(
+        "--dry-run", action="store_true",
+        help="Resolve the coord and report what would be pushed",
+    )
+    push.add_argument(
+        "--variant", choices=["raw", "sae", "all"], default="raw",
+        help="Which tensor variant(s) to push. Default: raw. (SAE variants "
+             "carry stronger provenance, so sharing them is opt-in.)",
+    )
+
+
+def _build_pack_rm(rm: argparse.ArgumentParser) -> None:
+    rm.add_argument("selector", help="Manifold name (or ns/name)")
+    rm.add_argument(
+        "-y", "--yes", action="store_true",
+        help="Confirm removal (required — removal is irrecoverable outside "
+             "the bundled default/ namespace)",
+    )
+
+
+def _build_pack_clear(clear: argparse.ArgumentParser) -> None:
+    clear.add_argument("selector", help="Manifold name (or ns/name)")
+    clear.add_argument(
+        "-m", "--model", default=None, metavar="MODEL_ID",
+        help="Scope to one model's tensors only (default: all models)",
+    )
+    clear.add_argument(
+        "--variant", choices=["raw", "sae", "all"], default="all",
+        help="Which tensor variant(s) to delete. Default: all.",
+    )
+
+
+def _build_pack_refresh(refresh: argparse.ArgumentParser) -> None:
+    refresh.add_argument("selector", help="Manifold name (or ns/name)")
+    refresh.add_argument(
+        "-m", "--model", default=None, metavar="MODEL_ID",
+        help="Scope to one model: clear its fitted tensor pair so it re-fits "
+             "on next use (does not re-pull from source). Default: all-source "
+             "re-pull.",
+    )
+
+
+def _build_pack_export(export: argparse.ArgumentParser) -> None:
+    export_fmt = export.add_subparsers(dest="format", required=True)
+    gguf = export_fmt.add_parser(
+        "gguf", help="Export a folded manifold to llama.cpp GGUF",
+    )
+    gguf.add_argument("name", help="Manifold name (or ns/name)")
+    gguf.add_argument("-m", "--model", default=None, metavar="MODEL_ID")
+    gguf.add_argument("-o", "--output", default=None, metavar="PATH")
+    gguf.add_argument("--model-hint", default=None, metavar="HINT")
+    archive = export_fmt.add_parser(
+        "archive",
+        help="Export a manifold and referenced template as .drowse",
+    )
+    archive.add_argument("name", help="Manifold name (or ns/name)")
+    archive.add_argument("-o", "--output", default=None, metavar="FILE")
+
+
+# --- manifold (compute) + pack (lifecycle) parser wiring -----------------
+
+# Long-form ``description=`` blocks per manifold compute verb (the verb's
+# ``-h`` carries these; the short ``help=`` lives in ``_MANIFOLD_VERBS``).
+_MANIFOLD_DESCRIPTIONS: dict[str, str] = {
+    "extract": "Extract a steering vector (a 2-node flat `pca` manifold).",
+    "generate": (
+        "For every concept, have the loaded model answer the shared "
+        "baseline prompts *in character* (the concept rides the system "
+        "prompt + a kind-derived elicitation role), writing one corpus per "
+        "node.  Writes a fresh discover-mode manifold folder under "
+        "~/.drowse/manifolds/<ns>/<name>/ ready for `drowse manifold fit` "
+        "to fit.  The shared baseline prompts hold the topic common-mode "
+        "across nodes, so the per-concept centroids stay comparable "
+        "(response[i] aligns to baseline prompt[i % k])."
+    ),
+    "from-template": (
+        "Author a discover manifold whose node corpora derive from a standalone "
+        "template (`drowse template create`). Resolves the template, expands its "
+        "values x contexts into per-value node corpora (the slot-filled assistant "
+        "turns), and writes a discover folder that stores the corpus and "
+        "`template_ref`-erences the template — so the fit resolves the template's "
+        "multi-turn contexts as elicitation prefixes. Deterministic (no model "
+        "load); run `drowse manifold fit <name> -m MODEL` next. fit_mode auto "
+        "suits cyclic categories (days/months) — the fit detects the loop."
+    ),
+    "fit": (
+        "Pool per-node centroids, fit a per-layer PCA subspace (+ RBF "
+        "interpolant for curved manifolds), and write the per-model manifold "
+        "tensor into the folder.  The positional is a manifold name OR a "
+        "folder path.  Authored folders supply their own coords; discover-mode "
+        "folders (fit_mode pca/spectral, usually authored by `drowse manifold "
+        "generate`) derive coords per-model and accept the --method / "
+        "--max-dim / --var-threshold / --k-nn / --bandwidth / "
+        "--max-subspace-dim hyperparam overrides (written into manifold.json "
+        "before the fit; rejected against an authored folder)."
+    ),
+    "bake": (
+        "Bake a steering expression into a corpus-less manifold under local/ "
+        "(the merge op): a linear combination / projection of existing fitted "
+        "vectors, written as a fit_mode=baked manifold."
+    ),
+    "merge": (
+        "Union the *nodes* of two or more discover-mode source manifolds into "
+        "a fresh, unfitted discover folder, then run `drowse manifold fit "
+        "<merged>` to fit it.  The corpus analogue of `manifold bake` — but on "
+        "node corpora rather than steering directions.  Restricted to "
+        "discover-mode sources (authored manifolds carry user-declared "
+        "geometry that isn't mergeable without a shared coordinate system).  "
+        "Label collisions across sources raise; rename one side before merging."
+    ),
+    "transfer": (
+        "Transfer a fitted manifold from a source model to a target model by "
+        "fitting a per-layer Procrustes alignment between their cached neutral "
+        "activations and mapping the fitted subspace into target space.  "
+        "Writes the transferred tensor at the target's `_from-<safe_src>` "
+        "variant path."
+    ),
+    "compare": "Cosine similarity between steering vectors (Mahalanobis).",
+    "why": (
+        "Per-layer ‖baked‖ histogram (16 buckets) showing which layers "
+        "contribute most to a steering vector."
+    ),
+}
+
+_MANIFOLD_BUILDERS = {
+    "extract":  _build_vector_extract,
+    "generate": _build_manifold_generate,
+    "from-template": _build_manifold_from_template,
+    "fit":      _build_manifold_fit,
+    "bake":     _build_vector_merge,
+    "merge":    _build_manifold_merge,
+    "transfer": _build_manifold_transfer,
+    "compare":  _build_vector_compare,
+    "why":      _build_vector_why,
+}
+
+_PACK_DESCRIPTIONS: dict[str, str] = {
+    "ls": "List local manifolds under ~/.drowse/manifolds/.",
+    "show": (
+        "Print one manifold's domain, node coordinates, and per-model fitted "
+        "tensors."
+    ),
+    "install": (
+        "Pull a manifold from a HuggingFace drowse-manifold repo "
+        "(`<ns>/<name>[@revision]`) or copy-install a local folder path."
+    ),
+    "search": "Search HF for `drowse-manifold`-tagged model repos.",
+    "push": (
+        "Push a manifold folder (corpus + fitted tensors) to HF as a "
+        "`drowse-manifold`-tagged model repo.  The corpus is always uploaded "
+        "(a manifold can't re-fit without it); per-model tensors are filtered "
+        "by `-m`/`--variant`."
+    ),
+    "rm": (
+        "Remove a whole manifold folder.  Bundled manifolds (`default/` "
+        "namespace) re-materialize on next session init."
+    ),
+    "clear": (
+        "Delete a manifold's per-model fitted tensors (they re-fit on next "
+        "use) while keeping `manifold.json` + the node corpus."
+    ),
+    "refresh": (
+        "Re-pull a manifold from its source: `local` is skipped, "
+        "`bundled`/`default/` re-materializes from package data, `hf://` "
+        "re-pulls.  With `-m/--model`, instead does a scoped refresh — drops "
+        "just that model's fitted tensor pair so it re-fits on next use, "
+        "without re-pulling from the source."
+    ),
+    "export": (
+        "Export either a folded 2-node ``pca`` manifold as a llama.cpp GGUF, "
+        "or one complete manifold closure as a validated ``.drowse``. The "
+        "archive form preserves the manifold folder and includes its exact "
+        "referenced template when present. Checksums establish integrity, not "
+        "publisher identity."
+    ),
+}
+
+_PACK_BUILDERS = {
+    "ls":       _build_pack_ls,
+    "show":     _build_pack_show,
+    "install":  _build_pack_install,
+    "search":   _build_pack_search,
+    "push":     _build_pack_push,
+    "rm":       _build_pack_rm,
+    "clear":    _build_pack_clear,
+    "refresh":  _build_pack_refresh,
+    "export":   _build_pack_export,
+}
+
+
+def _build_template_create(p: argparse.ArgumentParser) -> None:
+    p.add_argument("name", help="Template name (use ns/name for non-local)")
+    p.add_argument(
+        "--slot", required=True, metavar="TOKEN",
+        help="The placeholder substituted per value, e.g. '[DAY]'. Must appear "
+             "exactly once in each context's final assistant turn and in no "
+             "history turn.",
+    )
+    p.add_argument(
+        "--values", nargs="+", required=True, metavar="VALUE",
+        help="Candidate slot values (>= 2). The raw value is substituted into "
+             "the text; its slug is the node label ('New York' -> 'new_york').",
+    )
+    p.add_argument(
+        "--contexts", dest="contexts_file", required=True, metavar="PATH",
+        help="JSON file: a list of contexts. Each is either "
+             "{\"turns\": [{\"role\", \"content\"}...], \"assistant\": \"...slot...\"} "
+             "for multi-turn, or the single-turn sugar "
+             "{\"user\": ..., \"assistant\": \"...slot...\"}. The slotted "
+             "assistant turn carries the slot.",
+    )
+    p.add_argument(
+        "--description", default="", metavar="TEXT",
+        help="Human-readable description for the template folder",
+    )
+    p.add_argument(
+        "-f", "--force", action="store_true",
+        help="Overwrite an existing template folder",
+    )
+
+
+def _build_template_ls(p: argparse.ArgumentParser) -> None:
+    p.add_argument("-j", "--json", dest="json_output", action="store_true", help="JSON output")
+
+
+def _build_template_show(p: argparse.ArgumentParser) -> None:
+    p.add_argument("name", help="Template name (or ns/name)")
+    p.add_argument("-j", "--json", dest="json_output", action="store_true", help="JSON output")
+
+
+def _build_template_rm(p: argparse.ArgumentParser) -> None:
+    p.add_argument("name", help="Template name (or ns/name)")
+    p.add_argument("-y", "--yes", action="store_true", help="Skip confirmation")
+
+
+def _build_template_score(p: argparse.ArgumentParser) -> None:
+    p.add_argument("name", help="Template name (or ns/name)")
+    p.add_argument(
+        "-m", "--model", required=True, metavar="MODEL_ID",
+        help="Model to score against",
+    )
+    p.add_argument(
+        "-S", "--steer", default=None, metavar="EXPR",
+        help="Optional steering expression — score the completion distribution "
+             "under steering (the distributional before/after read).",
+    )
+    p.add_argument(
+        "--by", choices=("sum", "mean"), default="sum",
+        help="Rank/highlight statistic: 'sum' (joint logprob, length-biased to "
+             "short completions) or 'mean' (length-normalized). Default sum.",
+    )
+    p.add_argument("-d", "--device", default="auto",
+                   help="Device: auto (detect), cuda, mps, or cpu")
+    p.add_argument("-q", "--quantize", choices=["4bit", "8bit"], default=None,
+                   help="Quantization mode (default: bf16/fp16)")
+    p.add_argument("-j", "--json", dest="json_output", action="store_true", help="JSON output")
+
+
+_TEMPLATE_DESCRIPTIONS: dict[str, str] = {
+    "create": (
+        "Author a standalone template artifact under "
+        "~/.drowse/templates/<ns>/<name>/. A template is a slot token, a set of "
+        "candidate values, and one or more multi-turn contexts whose final "
+        "assistant turn carries the slot. Two consumers read it: the completion "
+        "scorer (`template score`) reports the restricted-choice logprob "
+        "distribution over the values, and a manifold can `template_ref` it to "
+        "pool each value's slot-filled centroid into a node. The right tool for "
+        "categories you reference rather than embody — days, months, durations — "
+        "where 'someone {c}' makes no sense. Deterministic (no model load)."
+    ),
+    "ls": "List local templates under ~/.drowse/templates/.",
+    "show": "Print one template's slot, values, and contexts.",
+    "score": (
+        "Score the value distribution against each of the template's contexts: "
+        "for every context, the model's restricted-choice probability over the "
+        "candidate slot-fills (the logit counterpart to a manifold fit). Reports "
+        "both the joint (sum) and length-normalized (mean) views. With "
+        "`-S/--steer`, scores under a steering expression so you can read how "
+        "steering reshapes the distribution — did it shift, not just the argmax?"
+    ),
+    "rm": "Remove a whole template folder.",
+}
+
+_TEMPLATE_BUILDERS = {
+    "create": _build_template_create,
+    "ls":     _build_template_ls,
+    "show":   _build_template_show,
+    "score":  _build_template_score,
+    "rm":     _build_template_rm,
+}
+
+
+# --- lens subtree ---------------------------------------------------------
+
+def _build_lens_fit(p: argparse.ArgumentParser) -> None:
+    p.add_argument("model", help="HuggingFace model ID or local path")
+    corpus = p.add_mutually_exclusive_group()
+    corpus.add_argument(
+        "--corpus", default=None, metavar="FILE",
+        help="Text corpus: one document per line (a JSONL line with a 'text' "
+             "field also works). With neither this nor --hf-corpus, stream "
+             "the default web-text sample "
+             "(HuggingFaceFW/fineweb-edu:sample-10BT) via the `datasets` "
+             "library (pip install 'drowse.ai[hf]').",
+    )
+    corpus.add_argument(
+        "--hf-corpus", action="append", default=None,
+        metavar="REPO[:CONFIG][@REV][,KEY=VALUE...]",
+        help="Stream the first N non-empty documents of a Hugging Face "
+             "dataset's train split instead, pinned to the commit REV "
+             "resolves to (default: main) and to CONFIG (default: the "
+             "dataset's default). Options: text_field=F (default text); "
+             "files=K reads round-robin from K of its data files, ordered by "
+             "a seed=S hash of their paths, to spread the sample over a "
+             "dataset whose rows are not shuffled. Repeat the flag to mix "
+             "corpora by weight=W (default 1). The pins are recorded in the "
+             "corpus spec, and a larger --prompts later resumes by prefix.",
+    )
+    p.add_argument(
+        "--prompts", type=_positive_int, default=100, metavar="N",
+        help="Number of corpus documents to average over (default 100 — "
+             "quality saturates quickly; the paper used 1000)",
+    )
+    p.add_argument(
+        "--seq-len", type=_positive_int, default=None, metavar="T",
+        help="Truncate each document to this many tokens (default 128)",
+    )
+    p.add_argument(
+        "--dim-batch", type=_positive_int, default=None, metavar="K",
+        help="Output dims per backward pass (default 8). Total backward work "
+             "is K-invariant — the knob trades memory for per-pass overhead "
+             "and barely moves wall time; halves automatically on OOM.",
+    )
+    p.add_argument(
+        "--prompt-batch", type=_positive_int, default=None, metavar="B",
+        help="Corpus prompts per autograd graph (default: 4 on CPU/CUDA, 2 on "
+             "MPS). Preserves equal-prompt estimator weighting; backs off "
+             "independently on OOM.",
+    )
+    p.add_argument(
+        "--checkpoint-every", type=_positive_int, default=None, metavar="N",
+        help="Write a self-contained resumable checkpoint every N usable "
+             "prompts (default 25); the full artifact is written durably once "
+             "at finalization.",
+    )
+    p.add_argument(
+        "--layers", default=None, metavar="L1,L2,...|workspace|all",
+        help="Fit only these source layers (default: every layer below the "
+             "final one). Restricting to the workspace band — roughly the "
+             "40-90%% depth the jlens/<word> atoms use — skips the backward "
+             "work below the lowest requested layer and shrinks the artifact; "
+             "readout surfaces then cover only the fitted layers. Pass "
+             "`workspace` as shorthand for that band or `all` explicitly.",
+    )
+    estimator = p.add_mutually_exclusive_group()
+    estimator.add_argument(
+        "--relp", dest="relp", action="store_true",
+        help="Fit the R-lens (default): the same estimator through the "
+             "LRP-modified backward graph. Lands at local:relp.",
+    )
+    estimator.add_argument(
+        "--standard", dest="relp", action="store_false",
+        help="Fit the standard Jacobian lens at local:default instead of the "
+             "default RelP R-lens.",
+    )
+    p.set_defaults(relp=True)
+    p.add_argument(
+        "-f", "--force", action="store_true",
+        help="Restart from zero (default: resume a matching partial fit)",
+    )
+    p.add_argument("-d", "--device", default="auto",
+                   help="Device: auto (detect), cuda, mps, or cpu")
+    p.add_argument("-q", "--quantize", choices=["4bit", "8bit"], default=None,
+                   help="Quantization mode (default: bf16/fp16)")
+
+
+def _build_lens_fetch(p: argparse.ArgumentParser) -> None:
+    p.add_argument("model", help="HuggingFace model ID")
+    p.add_argument(
+        "source", nargs="?", default="neuronpedia",
+        help="External source: neuronpedia, workspace-r (RelP), workspace-j",
+    )
+    p.add_argument("--revision", default="main", help="Provider revision to resolve and pin")
+    p.add_argument(
+        "--repo", default=None, metavar="REPO",
+        help="Override the provider repository (default: the source's own)",
+    )
+    p.add_argument("-f", "--force", action="store_true", help="Refresh the binding")
+    p.add_argument("-j", "--json", dest="json_output", action="store_true")
+
+
+def _build_lens_ls(p: argparse.ArgumentParser) -> None:
+    p.add_argument("model", help="Model ID whose lens sources to list")
+    p.add_argument("-j", "--json", dest="json_output", action="store_true")
+
+
+def _build_lens_use(p: argparse.ArgumentParser) -> None:
+    p.add_argument("model", help="Model ID whose active lens to change")
+    p.add_argument(
+        "source", help="local:NAME or a fetched binding (neuronpedia, workspace-r, workspace-j)",
+    )
+
+
+def _build_lens_show(p: argparse.ArgumentParser) -> None:
+    p.add_argument("model", help="Model ID whose lens artifact to inspect")
+    p.add_argument("source", nargs="?", default=None,
+                   help="Source to inspect (default: active)")
+    p.add_argument("-j", "--json", dest="json_output", action="store_true", help="JSON output")
+
+
+def _build_lens_top(p: argparse.ArgumentParser) -> None:
+    p.add_argument("model", help="HuggingFace model ID or local path")
+    p.add_argument("prompt", help="Raw prompt to read out (no chat template)")
+    p.add_argument(
+        "-k", "--top-k", type=_positive_int, default=8, metavar="K",
+        help="Tokens per (layer, position) readout (default 8)",
+    )
+    p.add_argument(
+        "--layers", default=None, metavar="L1,L2,...|sample|workspace|all",
+        help="Comma-separated layer indices or a layer mode (default: all fitted layers)",
+    )
+    p.add_argument(
+        "--position", type=int, action="append", default=None, metavar="P",
+        help="Token position to read (repeatable; negative from the end; "
+             "default: final position)",
+    )
+    p.add_argument("-d", "--device", default="auto",
+                   help="Device: auto (detect), cuda, mps, or cpu")
+    p.add_argument("-q", "--quantize", choices=["4bit", "8bit"], default=None,
+                   help="Quantization mode (default: bf16/fp16)")
+    p.add_argument("-j", "--json", dest="json_output", action="store_true", help="JSON output")
+
+
+def _build_lens_decompose(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "selector",
+        help="Steerable direction to split (concept name, ns/name, or "
+             "jlens/<word>)",
+    )
+    p.add_argument(
+        "-m", "--model", required=True, metavar="MODEL_ID",
+        help="Model whose lens + fitted direction to use",
+    )
+    p.add_argument(
+        "-k", "--top-k", type=_positive_int, default=16, metavar="K",
+        help="Sparsity budget: atoms in the J-space component (default 16)",
+    )
+    p.add_argument(
+        "--layers", default=None, metavar="L1,L2,...|workspace|all",
+        help="Comma-separated layer indices or a layer mode (default: every "
+             "fitted layer the direction covers)",
+    )
+    p.add_argument("-d", "--device", default="auto",
+                   help="Device: auto (detect), cuda, mps, or cpu")
+    p.add_argument("-q", "--quantize", choices=["4bit", "8bit"], default=None,
+                   help="Quantization mode (default: bf16/fp16)")
+    p.add_argument("-j", "--json", dest="json_output", action="store_true", help="JSON output")
+
+
+def _build_lens_rm(p: argparse.ArgumentParser) -> None:
+    p.add_argument("model", help="Model ID whose lens artifact to remove")
+    p.add_argument("source", nargs="?", default=None,
+                   help="local:NAME or neuronpedia (default: active)")
+    p.add_argument("-y", "--yes", action="store_true", help="Skip confirmation")
+
+
+_LENS_DESCRIPTIONS: dict[str, str] = {
+    "fit": (
+        "Fit the per-model Jacobian lens: J_l = E[dh_final/dh_l], the average "
+        "first-order effect of each layer's residual on the final-layer "
+        "residual over a web-text corpus. One forward + ceil(d_model/dim_batch) "
+        "backward passes per document — the only backward passes in drowse. "
+        "The artifact lands under ~/.drowse/models/<model>/jlens/local/default "
+        "as an atomic manifest plus fp32 per-layer shards (~1-3 GB total) "
+        "and backs `lens top`, `lens decompose`, the "
+        "jlens/<word> steering atoms, and @when:jlens/<word> gates. "
+        "Interrupted fits checkpoint and resume by default."
+    ),
+    "fetch": (
+        "Fetch an official external Jacobian lens into its provider-owned "
+        "cache, pin the repository and base-model revisions, and write only a "
+        "small Drowse binding. No provider payload is copied into DROWSE_HOME."
+    ),
+    "ls": "List Drowse-owned local lenses and external cache bindings.",
+    "show": "Print a lens source's layers, prompts, corpus, provenance, and size.",
+    "use": "Select a fetched/fitted source without downloading or copying it.",
+    "top": (
+        "Run one forward pass on a raw prompt and decode selected layers' "
+        "residuals through the lens: softmax(W_U · norm(J_l h)) — the tokens "
+        "the activation is disposed to make the model say. The window into "
+        "unverbalized intermediate computation (Gurnee et al. 2026)."
+    ),
+    "decompose": (
+        "Split a steerable direction into its J-space component: the best "
+        "sparse nonnegative combination of k J-lens token vectors, per layer. "
+        "Reports the variance share (how *verbalizable* the direction is — "
+        "concept vectors typically carry only ~6-15% of their variance in the "
+        "workspace) and the contributing tokens."
+    ),
+    "rm": "Delete a local lens or forget an external binding without touching its provider cache.",
+}
+
+_LENS_BUILDERS = {
+    "fit":       _build_lens_fit,
+    "fetch":     _build_lens_fetch,
+    "ls":        _build_lens_ls,
+    "show":      _build_lens_show,
+    "use":       _build_lens_use,
+    "top":       _build_lens_top,
+    "decompose": _build_lens_decompose,
+    "rm":        _build_lens_rm,
+}
+
+
+def _build_manifold_parser(parser: argparse.ArgumentParser) -> None:
+    """``drowse manifold`` — the steering-vector / manifold compute verbs."""
+    sub = parser.add_subparsers(dest="manifold_cmd", required=False, metavar="VERB")
+    for verb, desc in _MANIFOLD_VERBS:
+        child = sub.add_parser(
+            verb, help=desc,
+            description=_MANIFOLD_DESCRIPTIONS.get(verb, desc),
+        )
+        _MANIFOLD_BUILDERS[verb](child)
+
+
+def _build_pack_parser(parser: argparse.ArgumentParser) -> None:
+    """``drowse pack`` — the manifold lifecycle (install/share/inspect) verbs."""
+    sub = parser.add_subparsers(dest="pack_cmd", required=False, metavar="VERB")
+    for verb, desc in _PACK_VERBS:
+        child = sub.add_parser(
+            verb, help=desc,
+            description=_PACK_DESCRIPTIONS.get(verb, desc),
+        )
+        _PACK_BUILDERS[verb](child)
+
+
+def _build_template_parser(parser: argparse.ArgumentParser) -> None:
+    """``drowse template`` — the standalone templated-completion artifact."""
+    sub = parser.add_subparsers(dest="template_cmd", required=False, metavar="VERB")
+    for verb, desc in _TEMPLATE_VERBS:
+        child = sub.add_parser(
+            verb, help=desc,
+            description=_TEMPLATE_DESCRIPTIONS.get(verb, desc),
+        )
+        _TEMPLATE_BUILDERS[verb](child)
+
+
+def _build_lens_parser(parser: argparse.ArgumentParser) -> None:
+    """``drowse lens`` — the per-model Jacobian-lens artifact."""
+    sub = parser.add_subparsers(dest="lens_cmd", required=False, metavar="VERB")
+    for verb, desc in _LENS_VERBS:
+        child = sub.add_parser(
+            verb, help=desc,
+            description=_LENS_DESCRIPTIONS.get(verb, desc),
+        )
+        _LENS_BUILDERS[verb](child)
+
+
+def _build_sae_parser(parser: argparse.ArgumentParser) -> None:
+    """``drowse sae`` — local/external sparse-autoencoder sources."""
+    sub = parser.add_subparsers(dest="sae_cmd", required=False, metavar="VERB")
+    for verb, desc in _SAE_VERBS:
+        child = sub.add_parser(verb, help=desc)
+        child.add_argument("model", help="HuggingFace model ID or local path")
+        if verb == "train":
+            child.add_argument("name", help="Local SAE name")
+            child.add_argument("--corpus", default=None, metavar="FILE",
+                               help="One text document per line; default: FineWeb-Edu")
+            child.add_argument("--layer", type=_nonnegative_int, default=None,
+                               help="Residual-post layer (default: nearest 65%% depth)")
+            child.add_argument("--tokens", type=_positive_int, default=1_000_000, metavar="N")
+            child.add_argument("--seq-len", type=_positive_int, default=128, metavar="T")
+            child.add_argument("--batch-size", type=_positive_int, default=8, metavar="B")
+            child.add_argument("--width", type=_positive_int, default=None, metavar="N")
+            child.add_argument("--expansion", type=_positive_int, default=8, metavar="K")
+            child.add_argument("--learning-rate", type=float, default=3e-4, metavar="LR")
+            child.add_argument("--l1", type=float, default=1e-3, metavar="LAMBDA")
+            child.add_argument("--dead-threshold", type=float, default=1e-6, metavar="T")
+            child.add_argument("--seed", type=int, default=0)
+            child.add_argument("-f", "--force", action="store_true")
+            child.add_argument("-d", "--device", default="auto")
+            child.add_argument("-q", "--quantize", choices=["4bit", "8bit"], default=None)
+            child.add_argument("-j", "--json", dest="json_output", action="store_true")
+        elif verb == "fetch":
+            # Pure IO, like ``lens fetch``: the provider's SAE weights land in
+            # the Hugging Face cache and Drowse writes a small binding.  The
+            # base model is never loaded, so there is no ``-d``/``-q``.
+            child.add_argument("source", help="saelens:RELEASE")
+            child.add_argument("--layer", type=_nonnegative_int, default=None,
+                               help="Explicit covered hook layer (default: nearest 65%% depth)")
+            child.add_argument(
+                "--revision", default=None, metavar="REV",
+                help="Provider revision to resolve and pin (default: the "
+                     "release's own resolved commit)",
+            )
+            child.add_argument("-j", "--json", dest="json_output", action="store_true")
+        elif verb == "show":
+            child.add_argument("source", nargs="?", default=None,
+                               help="local:NAME or saelens:RELEASE (default: active)")
+            child.add_argument("-j", "--json", dest="json_output", action="store_true")
+        elif verb == "rm":
+            # No ``-j``: removal reports one line of prose, matching
+            # ``lens rm``.  (``show`` needs JSON; ``rm`` never emitted any.)
+            child.add_argument("source", nargs="?", default=None,
+                               help="local:NAME or saelens:RELEASE (default: active)")
+            child.add_argument("-y", "--yes", action="store_true")
+        elif verb == "use":
+            child.add_argument("source", help="local:NAME or saelens:RELEASE")
+        else:  # ls
+            child.add_argument("-j", "--json", dest="json_output", action="store_true")
+
+
+# --- config subtree ------------------------------------------------------
+
+def _build_config_parser(parser: argparse.ArgumentParser) -> None:
+    sub = parser.add_subparsers(dest="config_cmd", required=False, metavar="VERB")
+
+    show = sub.add_parser("show", help="Print the effective merged config")
+    show.add_argument("-c", "--config", action="append", default=None, metavar="PATH",
+                      help="Extra YAML files to compose on top of ~/.drowse/config.yaml")
+    show.add_argument("-m", "--model", default=None,
+                      help="Override model field in output")
+    show.add_argument("--no-default", action="store_true",
+                      help="Skip loading ~/.drowse/config.yaml")
+
+    validate = sub.add_parser("validate", help="Validate a config file (CI hook)")
+    validate.add_argument("file", help="Path to YAML config file")
+
+
+# --- experiment subtree --------------------------------------------------
+
+def _build_experiment_fan(p: argparse.ArgumentParser) -> None:
+    p.add_argument("model", help="HuggingFace model ID or local path")
+    p.add_argument("prompt", help="Prompt to fan out")
+    p.add_argument(
+        "-g", "--grid",
+        action="append",
+        required=True,
+        metavar="CONCEPT=ALPHAS",
+        help=(
+            "Alpha grid term, repeatable. Example: "
+            "happy.sad=-0.4,0,0.4"
+        ),
+    )
+    p.add_argument(
+        "-S", "--steer",
+        dest="base_steering",
+        default=None,
+        metavar="EXPR",
+        help="Fixed steering expression composed under each grid row",
+    )
+    # Historical spelling, same dest — kept working, kept out of --help so
+    # `-S/--steer` reads identically on every verb that takes one.
+    p.add_argument(
+        "--base-steering",
+        dest="base_steering",
+        default=None,
+        metavar="EXPR",
+        help=argparse.SUPPRESS,
+    )
+    p.add_argument("-q", "--quantize", choices=["4bit", "8bit"], default=None)
+    p.add_argument("-d", "--device", default="auto")
+    p.add_argument("-p", "--probes", nargs="*", default=None)
+    # ``None`` (not 256) so ``_load_effective_config`` can tell "unset" from
+    # an explicit ``--max-tokens 256``; the runner supplies 256 after the
+    # config merge.
+    p.add_argument("--max-tokens", type=_positive_int, default=None,
+                   help="Max generation tokens per grid row (default: 256)")
+    p.add_argument("-j", "--json", dest="json_output", action="store_true")
+    _add_injection_args(p)
+    _add_logit_args(p)
+    _add_config_args(p)
+
+
+def _build_experiment_transcript_parser(parser: argparse.ArgumentParser) -> None:
+    """``drowse experiment transcript`` — replay saved tree paths."""
+    sub = parser.add_subparsers(dest="transcript_cmd", required=False, metavar="VERB")
+
+    run = sub.add_parser(
+        "run",
+        help="Replay a transcript on the current session and report readings",
+        description=(
+            "Load a YAML transcript, replay each user turn with the recorded "
+            "recipe, and report per-turn readings against the recorded ones."
+        ),
+    )
+    run.add_argument("path", help="Path to a drowse_transcript YAML file")
+    # Override the model arg shape so transcript replay can fall back to
+    # the embedded ``model_id`` header (the common case) instead of
+    # forcing the user to repeat it on the command line.  When the
+    # transcript also lacks ``model_id`` the runner fails with a clear
+    # message; that's caught early so we don't load a model just to
+    # complain about it after.
+    run.add_argument(
+        "model",
+        nargs="?",
+        default=None,
+        help="HuggingFace model ID or local path (defaults to transcript's `model_id`)",
+    )
+    run.add_argument(
+        "-q", "--quantize",
+        choices=["4bit", "8bit"],
+        default=None,
+        help="Quantization mode (default: bf16/fp16)",
+    )
+    run.add_argument(
+        "-d", "--device",
+        default="auto",
+        help="Device: auto (detect), cuda, mps, or cpu (default: auto)",
+    )
+    run.add_argument(
+        "-p", "--probes",
+        nargs="*",
+        default=None,
+        help="Probe categories (default: all)",
+    )
+    run.add_argument(
+        # ``None`` = unset, so YAML ``max_tokens:`` can fill it and an
+        # explicit value survives the config merge; the runner floors it
+        # at 256 afterwards.
+        "--max-tokens", type=_positive_int, default=None,
+        help="Default max generation tokens per replay turn (default: 256)",
+    )
+    _add_injection_args(run)
+    _add_config_args(run)
+    # ``--strict`` reuses the ``-s/--strict`` flag added by
+    # ``_add_config_args`` — same name, but here it gates "refuse on
+    # probe drift" instead of "fail hard on missing vectors".  Both
+    # interpretations share the spirit of the flag.
+
+
+def _build_experiment_naturalness(p: argparse.ArgumentParser) -> None:
+    """``drowse experiment naturalness`` — behavior-manifold naturalness eval.
+
+    Fits a behavior-space manifold from the manifold pack's node corpus
+    (each node's mean next-token distribution, mapped to Hellinger
+    space), runs a steered generation, re-runs the model over the
+    generated text to recover its behavioral trajectory, and reports the
+    mean / max Bhattacharyya distance of that trajectory to the behavior
+    manifold — low is natural, high flags off-manifold "teleportation".
+    """
+    p.add_argument("model", help="HuggingFace model ID or local path")
+    p.add_argument("prompt", help="Prompt to generate from")
+    p.add_argument(
+        "--manifold", required=True, metavar="FOLDER",
+        help="Manifold folder whose node corpus seeds the behavior manifold",
+    )
+    p.add_argument(
+        "-S", "--steer", required=True, metavar="EXPR",
+        help="Steering expression to evaluate (e.g. 'mood%%0.5')",
+    )
+    p.add_argument(
+        "--compare-linear", dest="compare_linear", action="store_true",
+        help="Also score a linear-chord steering baseline (the manifold "
+             "term must be a single '%%' term)",
+    )
+    # ``None`` = unset (see ``experiment fan``); the runner floors it at 128
+    # after the config merge.
+    p.add_argument("--max-tokens", type=_positive_int, default=None,
+                   help="Max generation tokens per scored run (default: 128)")
+    p.add_argument("-q", "--quantize", choices=["4bit", "8bit"], default=None)
+    p.add_argument("-d", "--device", default="auto")
+    p.add_argument("-p", "--probes", nargs="*", default=None)
+    p.add_argument("-j", "--json", dest="json_output", action="store_true")
+    _add_injection_args(p)
+    _add_config_args(p)
+
+
+_EXPERIMENT_BUILDERS = {
+    "fan": _build_experiment_fan,
+    "transcript": _build_experiment_transcript_parser,
+    "naturalness": _build_experiment_naturalness,
+}
+
+
+def _build_experiment_parser(parser: argparse.ArgumentParser) -> None:
+    sub = parser.add_subparsers(dest="experiment_cmd", required=False, metavar="VERB")
+    for verb, desc in _EXPERIMENT_VERBS:
+        child = sub.add_parser(verb, help=desc, description=desc)
+        _EXPERIMENT_BUILDERS[verb](child)
+
+
+def _build_root_parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(
+        prog="drowse",
+        description="Activation steering + trait monitoring for local HuggingFace models",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Run `drowse <verb> -h` for verb-specific options.",
+    )
+    sub = root.add_subparsers(dest="command", required=False, metavar="VERB")
+
+    # Each ``help=`` here is the single source of truth — it lands in
+    # the auto-generated ``positional arguments`` table on ``drowse -h``.
+    # Keep it short enough to fit one line at the typical terminal
+    # width; the verb's own ``-h`` carries the long-form description.
+    serve = sub.add_parser(
+        "serve",
+        help="Start the OpenAI + Ollama API server + analytics dashboard at /",
+        description="Start the OpenAI + Ollama compatible API server",
+    )
+    _build_serve_parser(serve)
+
+    manifold = sub.add_parser(
+        "manifold",
+        help=(
+            "Manifold compute "
+            "(extract/generate/from-template/fit/bake/merge/transfer/compare/why)"
+        ),
+        description="Steering-vector / manifold authoring, fitting, and analysis",
+    )
+    _build_manifold_parser(manifold)
+
+    pack = sub.add_parser(
+        "pack",
+        help="Manifold lifecycle (ls/show/install/search/push/rm/clear/refresh/export)",
+        description="Manifold install / share / inspect / removal lifecycle",
+    )
+    _build_pack_parser(pack)
+
+    cfg = sub.add_parser(
+        "config",
+        help="Inspect and validate drowse config files",
+        description="Inspect/validate config",
+    )
+    _build_config_parser(cfg)
+
+    experiment = sub.add_parser(
+        "experiment",
+        help="Run and replay experiment trees",
+        description="Run and replay experiment trees",
+    )
+    _build_experiment_parser(experiment)
+
+    template = sub.add_parser(
+        "template",
+        help="Templated completions (create/ls/show/score/rm)",
+        description="Standalone templated-completion artifact: author, inspect, "
+                    "and score the restricted-choice value distribution",
+    )
+    _build_template_parser(template)
+
+    lens = sub.add_parser(
+        "lens",
+        help="Jacobian lens (fit/fetch/ls/show/use/top/decompose/rm)",
+        description="Per-model Jacobian lens: fit the residual→output "
+                    "transport, read out what intermediate activations are "
+                    "disposed to say, and split directions into their "
+                    "verbalizable (J-space) component",
+    )
+    _build_lens_parser(lens)
+
+    sae = sub.add_parser(
+        "sae",
+        help="Sparse autoencoders (train/fetch/ls/show/use/rm)",
+        description="Train, fetch, select, and inspect per-model sparse-autoencoder sources",
+    )
+    _build_sae_parser(sae)
+
+    return root