Library page with tested demos; no-agent veil; energy meters and J/token; 15 new skills; external MCP catalogue; py3.10 gate

.gitattributes

@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 *.webp filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text

distinct_agent/README.md

@@ -60,21 +60,32 @@ whole PC. Unsupported and failed measurements contain `available: false` and
 
 ## Models and runner
 
-Discovery recognizes local GGUF files for Llama-2-7B-Chat, gpt-oss-20b,
-Qwen3-0.6B, and Qwen3-4B. It performs no download and executes no remote model
-code. Production manifests should pin SHA-256 values. `LlamaCppRunner` invokes
-an installed `llama-cli` with an argument array and `shell=False`.
+Discovery recognizes local GGUF files for OLMoE-1B-7B-0924-Instruct,
+OLMo-2-1124-7B-Instruct and Llama-2-7B-Chat. It performs no download and
+executes no remote model code. `LlamaCppRunner` invokes an installed
+`llama-cli` with an argument array and `shell=False`.
+
+The catalogue is short on purpose. Every model in it has a published,
+model-specific assessment of its training, recorded with its primary source in
+`model_assessments.json`; a release nobody has published anything about is not
+offered, because measured and disclosed environmental cost is the only claim
+this project makes. The two OLMo entries are first party end to end -- Ai2
+trained the models, measured the training, quantised the weights and published
+the digests -- and both are pinned by repository, revision and SHA-256. Llama 2
+is listed and withheld: Meta publish no GGUF and the source repository is
+gated, so there is no digest to pin, and the worker names it as unavailable on
+every start rather than dropping it silently.
 
 An explicit deterministic smoke test is:
 
 ```console
-python -m distinct_agent --model qwen3-0.6b=/models/qwen.gguf --demo-prompt "hello"
+python -m distinct_agent --model olmoe-1b-7b-0924-instruct=/models/olmoe.gguf --demo-prompt "hello"
 ```
 
 To pair with a server, log in there, generate a one-use code, and run:
 
 ```console
-python -m distinct_agent --server https://owner-space.hf.space --pair XXXX-XXXX-XXXX-XXXX --name "My efficient worker" --model qwen3-0.6b=/models/qwen.gguf --llama-cli /opt/llama/llama-cli
+python -m distinct_agent --server https://owner-space.hf.space --pair XXXX-XXXX-XXXX-XXXX --name "My efficient worker" --model olmoe-1b-7b-0924-instruct=/models/olmoe.gguf --llama-cli /opt/llama/llama-cli
 ```
 
 The default harness is `dspy-rlm`; startup performs its cached-only

distinct_agent/__main__.py

@@ -1,4 +1,15 @@
+import sys
+
+# The same gate cli.py carries, one frame earlier: ``python -m distinct_agent``
+# on a pre-3.10 interpreter must say so before any project import runs.
+if sys.version_info < (3, 10):
+    sys.exit(
+        "distinct needs Python 3.10 or newer; this is "
+        f"{sys.version_info.major}.{sys.version_info.minor} ({sys.executable}).\n"
+        "On Windows, run:  py -3.12 -m distinct_agent ...\n"
+        "Elsewhere, run:   python3.12 -m distinct_agent ..."
+    )
+
 from .cli import main
 
 raise SystemExit(main())
-

distinct_agent/cli.py

@@ -18,6 +18,18 @@ from dataclasses import replace
 from pathlib import Path
 from urllib.parse import urlsplit
 
+# Before any project import: the project uses 3.10 syntax at module level
+# (PEP 604 unions in isinstance), so on an older interpreter the failure is
+# an unrelated-looking TypeError deep in an import. A person on Windows whose
+# ``python`` is a stray 3.9 deserves the actual sentence instead.
+if sys.version_info < (3, 10):  # pragma: no cover - cannot run under test
+    sys.exit(
+        "distinct needs Python 3.10 or newer; this is "
+        f"{sys.version_info.major}.{sys.version_info.minor} ({sys.executable}).\n"
+        "On Windows, run:  py -3.12 -m distinct_agent ...\n"
+        "Elsewhere, run:   python3.12 -m distinct_agent ..."
+    )
+
 from distinct_protocol import (
     MODE_AGENT,
     MODE_SIMPLE,
@@ -42,6 +54,7 @@ from distinct_tools import (
 )
 from distinct_tools.approval import APPROVED_TOOLS_ENV_VAR
 
+from .access import announce_access_code, new_access_code
 from .energy import detect_energy_meter
 from .fanout import MultiServerTransport, ServerLink
 from .isolation import describe_request_isolation, describe_support
@@ -59,7 +72,6 @@ from .servers import (
     ServerRegistry,
 )
 from .tools import advertised_tool_refs
-from .access import announce_access_code, new_access_code
 from .transport import (
     AgentTransportError,
     GradioAgentTransport,

distinct_agent/energy.py

@@ -1052,6 +1052,200 @@ class ZeusEnergyMeter:
         )
 
 
+
+class NvidiaSmiPowerMeter:
+    """Measured GPU board power, integrated from ``nvidia-smi`` samples.
+
+    ``nvidia-smi --query-gpu=power.draw`` reports the board's instantaneous
+    draw in watts from the driver's own sensor. This meter samples it on a
+    small interval for the life of a run and integrates by the trapezoid
+    rule, which turns a power series into joules without a vendor library:
+    the same figure ``nvml``'s energy counter gives on hardware that has one,
+    obtained portably on hardware that does not.
+
+    The scope is the whole GPU board — memory, fans and idle draw included —
+    which is broader than a compute-only figure and is named so it can never
+    be summed with a cpu-package number. Sampling costs one subprocess per
+    interval; 250 ms keeps that below the noise floor of inference itself.
+    """
+
+    provider = "nvidia-smi"
+    scope = "gpu-board-measured"
+
+    _INTERVAL_SECONDS = 0.25
+
+    def __init__(self, *, executable: str | None = None) -> None:
+        import shutil as _shutil
+
+        self._meter_id = uuid.uuid4().hex
+        self._executable = executable or _shutil.which("nvidia-smi") or ""
+        self._sessions: dict[str, dict[str, object]] = {}
+        self._available = False
+        self._reason: str | None = None
+        if not self._executable:
+            self._reason = "nvidia-smi is not on PATH"
+            return
+        sample = self._sample_watts()
+        if sample is None:
+            self._reason = "nvidia-smi answered without a readable power figure"
+            return
+        self._available = True
+
+    @property
+    def available(self) -> bool:
+        return self._available
+
+    @property
+    def unavailable_reason(self) -> str | None:
+        return self._reason
+
+    def _sample_watts(self) -> float | None:
+        import subprocess
+
+        try:
+            completed = subprocess.run(
+                [
+                    self._executable,
+                    "--query-gpu=power.draw",
+                    "--format=csv,noheader,nounits",
+                ],
+                capture_output=True,
+                text=True,
+                timeout=3,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError):
+            return None
+        if completed.returncode != 0:
+            return None
+        total = 0.0
+        seen = False
+        for line in completed.stdout.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                watts = float(line)
+            except ValueError:
+                continue
+            if math.isfinite(watts) and 0.0 <= watts <= 10_000.0:
+                total += watts
+                seen = True
+        return total if seen else None
+
+    def start(self) -> EnergyToken:
+        token = EnergyToken(
+            meter_id=self._meter_id,
+            provider=self.provider,
+            scope=self.scope,
+            started_at=time.monotonic(),
+        )
+        if not self._available:
+            return token
+        stop = threading.Event()
+        session: dict[str, object] = {"stop": stop, "joules": 0.0, "samples": 0}
+
+        def poll() -> None:
+            last_time = time.monotonic()
+            last_watts = self._sample_watts()
+            while not stop.wait(self._INTERVAL_SECONDS):
+                now = time.monotonic()
+                watts = self._sample_watts()
+                if watts is not None and last_watts is not None:
+                    session["joules"] = (
+                        float(session["joules"])
+                        + (watts + last_watts) / 2.0 * (now - last_time)
+                    )
+                    session["samples"] = int(session["samples"]) + 1
+                last_time, last_watts = now, watts
+
+        thread = threading.Thread(target=poll, name="nvidia-smi-energy", daemon=True)
+        session["thread"] = thread
+        self._sessions[token.token_id] = session
+        thread.start()
+        return token
+
+    def stop(self, token: EnergyToken) -> EnergyUsage:
+        _check_token_owner(token, self._meter_id)
+        duration = max(0.0, time.monotonic() - token.started_at)
+        session = self._sessions.pop(token.token_id, None)
+        if not self._available or session is None:
+            return _unavailable_usage(token, duration)
+        stop = session["stop"]
+        assert isinstance(stop, threading.Event)
+        stop.set()
+        thread = session.get("thread")
+        if isinstance(thread, threading.Thread):
+            thread.join(timeout=2.0)
+        if int(session["samples"]) == 0:
+            return EnergyUsage(
+                self.provider,
+                self.scope,
+                available=False,
+                joules=None,
+                duration_seconds=duration,
+                reason="run ended before a second power sample arrived",
+            )
+        return EnergyUsage(
+            self.provider,
+            self.scope,
+            available=True,
+            joules=float(session["joules"]),
+            duration_seconds=duration,
+        )
+
+
+class PowermetricsProbeMeter:
+    """Apple Silicon: names the working path rather than faking one.
+
+    macOS exposes package power through ``powermetrics``, which requires
+    root, and through the undocumented counters ``zeus-apple-silicon``
+    wraps. When neither is usable this meter stays unavailable with the
+    reason spelled out, so a Mac worker reports why its figure is absent
+    instead of a bare absence. Zeus (tried before this in the ladder)
+    remains the measured path when its Apple support is installed.
+    """
+
+    provider = "powermetrics"
+    scope = "cpu-package"
+
+    def __init__(self) -> None:
+        import shutil as _shutil
+
+        self._meter_id = uuid.uuid4().hex
+        self._available = False
+        located = _shutil.which("powermetrics")
+        if not located:
+            self._reason = "powermetrics is not on PATH (macOS ships it in /usr/bin)"
+        else:
+            # Running it needs root; probing with sudo would prompt, and a
+            # meter must never prompt. State the requirement instead.
+            self._reason = (
+                "powermetrics needs root. Run the worker with sudo, or install "
+                "zeus-apple-silicon for the unprivileged counter path"
+            )
+
+    @property
+    def available(self) -> bool:
+        return self._available
+
+    @property
+    def unavailable_reason(self) -> str | None:
+        return self._reason
+
+    def start(self) -> EnergyToken:
+        return EnergyToken(
+            meter_id=self._meter_id,
+            provider=self.provider,
+            scope=self.scope,
+            started_at=time.monotonic(),
+        )
+
+    def stop(self, token: EnergyToken) -> EnergyUsage:
+        _check_token_owner(token, self._meter_id)
+        return _unavailable_usage(token, max(0.0, time.monotonic() - token.started_at))
+
+
 def detect_energy_meter(*, system: str | None = None) -> EnergyMeter:
     """Choose a backend: measured counters first, the stated model last.
 
@@ -1073,6 +1267,20 @@ def detect_energy_meter(*, system: str | None = None) -> EnergyMeter:
         zeus = ZeusEnergyMeter()
         if zeus.available:
             return zeus
+    if operating_system == "Darwin":
+        # Zeus above already covers a Mac with zeus-apple-silicon installed.
+        # Below it, powermetrics is the OS's own meter but needs root; the
+        # probe meter names that requirement, and the load model keeps a Mac
+        # worker reporting a labelled figure rather than nothing.
+        probe = PowermetricsProbeMeter()
+        if probe.available:
+            return probe
+        model = CpuLoadModelMeter()
+        if model.available:
+            return model
+        return UnavailableEnergyMeter(
+            probe.unavailable_reason or "no macOS energy backend is available"
+        )
     if operating_system == "Linux":
         # Direct powercap first: same hardware counter pyRAPL wraps, without
         # importing an abandoned package that logs warnings at import time.
@@ -1082,6 +1290,12 @@ def detect_energy_meter(*, system: str | None = None) -> EnergyMeter:
         pyrapl = PyRaplEnergyMeter()
         if pyrapl.available:
             return pyrapl
+        # A machine whose inference runs on the GPU: the board figure is the
+        # honest one when the CPU counters are fenced off (as they are in
+        # containers), and it is measured rather than modelled.
+        smi = NvidiaSmiPowerMeter()
+        if smi.available:
+            return smi
         model = CpuLoadModelMeter()
         if model.available:
             return model
@@ -1095,6 +1309,9 @@ def detect_energy_meter(*, system: str | None = None) -> EnergyMeter:
         counter = WindowsPerformanceCounterRaplMeter()
         if counter.available:
             return counter
+        smi = NvidiaSmiPowerMeter()
+        if smi.available:
+            return smi
         # Modelled, and labelled as modelled. A Windows worker with no usable
         # counter used to report nothing at all, which made every one of its
         # runs an absence; the model is a real number about a real run and it

distinct_agent/models.py

@@ -27,12 +27,16 @@ class UnpinnedModelError(ModelVerificationError):
 # A model is advertised only after its file is found locally. Presence in this
 # catalogue never means usable.
 #
-# PUBLISHER POLICY. unsloth is the *default* publisher, not the only permitted
-# one. Their GGUF republications are smaller for the same nominal quantisation,
-# which on a project about energy per run is a defensible engineering choice
-# rather than a convenience: fewer bytes to download, less resident memory, less
-# work per token. Other publishers stay selectable, and the publisher is always
-# visible in the entry so nobody has to guess whose weights they are running.
+# PUBLISHER POLICY. Weights are taken from the organisation that trained them,
+# and from nobody else. The earlier policy defaulted to unsloth's GGUF
+# republications on the argument that a smaller file for the same nominal
+# quantisation is less to download and less to hold in memory. That argument is
+# still true and it is still not the deciding one: a digest attests to whoever
+# built the file, so a third-party requantisation pins the repackager rather
+# than the trainer, and this catalogue's whole claim is that you can check who
+# made what you are running. Ai2 publish their own GGUFs, which is what makes
+# the entries below first party end to end -- the same organisation trained the
+# model, measured its training, quantised it and published the digest.
 #
 # DIGESTS. A digest is meaningless without the repository and revision it came
 # from: the same nominal quantisation published twice is two different files.
@@ -40,10 +44,6 @@ class UnpinnedModelError(ModelVerificationError):
 # pending, and an empty digest is an unanswered question rather than a passing
 # check; `discover_models(verify_hashes=True)` refuses them loudly.
 #
-# Llama-2-7B-Chat has no unsloth GGUF (their Llama-2 publications are
-# safetensors and bitsandbytes only), so it stays unpinned pending a decision
-# on whether to convert locally or accept a third-party GGUF.
-#
 # WHAT AN UNPINNED ENTRY NOW MEANS. Weights are fetched on demand rather than
 # placed on disk by the operator, so a manifest is only usable when its
 # repository, revision *and* digest are all recorded: without a revision there
@@ -51,78 +51,98 @@ class UnpinnedModelError(ModelVerificationError):
 # was run. :func:`distinct_agent.weights.fetchable_manifests` filters this list
 # to the entries that satisfy all three, and a worker offers nothing else.
 #
-# The unpinned entries stay here rather than being deleted. They are the
-# record of what is missing and for which model, they keep the rubric surface
-# able to name a release it has assessed but cannot run, and completing one is
-# then a data change (three strings) rather than an archaeology exercise. The
-# worker prints every withheld model and its missing part on every start, so
-# an absence is never silent.
+# The unpinned entry stays here rather than being deleted. It is the record of
+# what is missing and for which model, it keeps the assessment surface able to
+# name a release it has assessed but cannot run, and completing it is then a
+# data change (three strings) rather than an archaeology exercise. The worker
+# prints every withheld model and its missing part on every start, so an
+# absence is never silent.
+#
+# WHY THESE THREE. Every entry here has a published, model-specific assessment
+# of its training, recorded in ``model_assessments.json`` with its primary
+# source. Models with no such assessment were removed rather than shown with an
+# empty record: this project's only claim is about disclosed and measured
+# environmental cost, and a model nobody has published anything about is one it
+# has no business shipping. What was removed, and why:
+#
+#   Qwen3 0.6B and 4B   Qwen has published nothing for any release, in any
+#                       version. Previously kept as the worked example of zero
+#                       disclosure; that example now lives in the assessment
+#                       surface's own copy, which does not require shipping the
+#                       weights to make the point.
+#   gpt-oss-20b         No disclosure of any kind on the model card or
+#                       elsewhere.
+#   OLMo 2 0425 1B      Released a month after Ai2's assessment closed. Ai2 have
+#                       published nothing for it since, and a figure for a
+#                       different OLMo checkpoint is not a figure for this one.
+#   OLMoE 0125          Superseded here by OLMoE 0924, which is the checkpoint
+#                       Ai2 actually measured. Same architecture, same parameter
+#                       count, four months apart -- and by this catalogue's own
+#                       rule a different version is a different model, so the
+#                       date stamp is the entire difference between an entry
+#                       with evidence and an entry without.
 KNOWN_MODEL_MANIFESTS: tuple[ModelManifest, ...] = (
-    # DEFAULT. Chosen on assessed environmental impact, not on capability.
+    # DEFAULT. Chosen on published, measured environmental impact, not on
+    # capability, and not on file size.
+    #
+    # Ai2 measured this run: GPU power sampled at sub-second intervals rather
+    # than inferred from rated wattage, giving 54 MWh, 18 tCO2e and 70 kL of
+    # water for the pretraining run. That is the lowest published figure of any
+    # assessed release at a size this network can run, and it is roughly a third
+    # of the dense OLMo 2 7B measured by the same team on the same cluster.
+    # Mixture of experts: 6.9B parameters resident, about 1.3B active per token.
     #
-    # Ai2 publish this GGUF themselves, so the provenance chain is first party
-    # end to end: the same organisation trained the model, quantised it and
-    # published the digest. Every other OLMo GGUF is a third-party requantisation,
-    # which means the digest attests to a repackager's file rather than to the
-    # publisher's. Given how much of this project rests on weights identity,
-    # that distinction decided the pin. See PLAN.md 10.16.
+    # See model_assessments.json, record ``olmoe-1b-7b-0924``, and
+    # https://arxiv.org/abs/2503.05804 for the measurement.
+    #
+    # NOTE ON COVERAGE. The published figures cover the 0924 *pretraining* run.
+    # This entry is the Instruct checkpoint, whose tuning stage the source does
+    # not separately cost. The assessment record says so; do not quietly promote
+    # it to complete coverage.
     ModelManifest(
-        id="olmo-2-1b-instruct",
-        label="OLMo 2 1B Instruct · Ai2 · Q4_K_M",
-        filename="OLMo-2-0425-1B-Instruct-Q4_K_M.gguf",
-        min_ram_gb=2.0,
-        sha256="abd8187934a438fbf7cfff0a1de5b9d2793ce913f158794df1951dcba6c93cc6",
-        source_repo="allenai/OLMo-2-0425-1B-Instruct-GGUF",
-        source_revision="62f8c199538474c3e33ed5d7e0580abd66686a27",
+        id="olmoe-1b-7b-0924-instruct",
+        label="OLMoE 1B-7B 0924 Instruct · Ai2 · Q4_K_M",
+        filename="olmoe-1b-7b-0924-instruct-q4_k_m.gguf",
+        min_ram_gb=8.0,
+        sha256="8c310f1435a1222338fd2d3d974975be9cd908180b644bab0c2a94da1ac32f3f",
+        source_repo="allenai/OLMoE-1B-7B-0924-Instruct-GGUF",
+        source_revision="02ab6ea6894a8418eb14f6d8ee1bfb08bd298080",
         context_length=4096,
     ),
-    # Kept as the comparison point: the rubric sheet uses it to show what zero
-    # environmental disclosure looks like. Not the default.
-    ModelManifest(
-        id="qwen3-0.6b",
-        label="Qwen3-0.6B · unsloth · Q4_K_M",
-        filename="Qwen3-0.6B-Q4_K_M.gguf",
-        min_ram_gb=2.0,
-        # Verified by downloading this exact revision and hashing the file;
-        # see scripts/fetch_runtime.py.
-        sha256="ac2d97712095a558e31573f62f466a3f9d93990898b0ec79d7c974c1780d524a",
-        source_repo="unsloth/Qwen3-0.6B-GGUF",
-        source_revision="50968a4468ef4233ed78cd7c3de230dd1d61a56b",
-        context_length=40960,
-    ),
-    # OLMoE: first-party GGUF, and Ai2 tag these repos with co2_eq_emissions,
-    # which is the disclosure the rubric rewards. Digest pending; the repo and
-    # revision are recorded so it can be pinned without another search.
+    # The dense comparison, and the fallback if the MoE architecture misbehaves
+    # under a given llama.cpp build. Same team, same cluster, same measurement
+    # method, same year, so the gap between this and OLMoE above is one of the
+    # few genuinely like-for-like comparisons in this literature: 157 MWh,
+    # 52 tCO2e, 202 kL. Roughly three times OLMoE on every disclosed axis.
+    #
+    # See model_assessments.json, record ``olmo-2-1124-7b``.
     ModelManifest(
-        id="olmoe-1b-7b-instruct",
-        label="OLMoE 1B-7B Instruct · Ai2 · Q4_K_M",
-        filename="OLMoE-1B-7B-0125-Instruct-Q4_K_M.gguf",
+        id="olmo-2-1124-7b-instruct",
+        label="OLMo 2 1124 7B Instruct · Ai2 · Q4_K_M",
+        filename="olmo-2-1124-7B-instruct-Q4_K_M.gguf",
         min_ram_gb=8.0,
-        source_repo="allenai/OLMoE-1B-7B-0125-Instruct-GGUF",
+        sha256="e08112e5f84aab7c05fa6e713c58e5214cd5d8e32ed773ff3354b006eed41b95",
+        source_repo="allenai/OLMo-2-1124-7B-Instruct-GGUF",
+        source_revision="410e0069f64869e4b1d17d8de04810b881fd824b",
         context_length=4096,
     ),
-    ModelManifest(
-        id="qwen3-4b",
-        label="Qwen3-4B · unsloth · Q4_K_M",
-        filename="Qwen3-4B-Q4_K_M.gguf",
-        min_ram_gb=6.0,
-        source_repo="unsloth/Qwen3-4B-GGUF",
-        context_length=40960,
-    ),
+    # Kept as the contrast case: the only non-Ai2 release in this catalogue with
+    # a published model-specific figure, and a partial one. Meta published
+    # GPU-hours and a modelled 31.22 tCO2e; no energy, no water, no materials.
+    #
+    # Still unpinned, and for two reasons that are worth keeping visible rather
+    # than resolving quietly. Meta publish no GGUF, so any file would be a third
+    # party's, which the publisher policy above rules out. And the source
+    # repository is gated, so there is no unauthenticated revision to pin even
+    # if that policy changed. ``fetchable_manifests`` therefore withholds it and
+    # the worker says so on every start. It is here to be named, not run.
     ModelManifest(
         id="llama-2-7b-chat",
-        label="Llama-2-7B-Chat · Q4_K_M",
+        label="Llama 2 7B Chat · Meta · gated licence",
         filename="llama-2-7b-chat.Q4_K_M.gguf",
         min_ram_gb=8.0,
         context_length=4096,
     ),
-    ModelManifest(
-        id="gpt-oss-20b",
-        label="gpt-oss-20b · MXFP4",
-        filename="gpt-oss-20b-mxfp4.gguf",
-        min_ram_gb=16.0,
-        context_length=131072,
-    ),
 )
 
 
@@ -131,17 +151,13 @@ _FILENAME_ALIASES: Mapping[str, tuple[str, ...]] = {
         "llama-2-7b-chat.Q4_K_M.gguf",
         "Llama-2-7B-Chat.Q4_K_M.gguf",
     ),
-    "gpt-oss-20b": (
-        "gpt-oss-20b-mxfp4.gguf",
-        "gpt-oss-20b-Q4_K_M.gguf",
-    ),
-    "qwen3-0.6b": (
-        "Qwen3-0.6B-Q4_K_M.gguf",
-        "qwen3-0.6b-q4_k_m.gguf",
+    "olmoe-1b-7b-0924-instruct": (
+        "olmoe-1b-7b-0924-instruct-q4_k_m.gguf",
+        "OLMoE-1B-7B-0924-Instruct-Q4_K_M.gguf",
     ),
-    "qwen3-4b": (
-        "Qwen3-4B-Q4_K_M.gguf",
-        "qwen3-4b-q4_k_m.gguf",
+    "olmo-2-1124-7b-instruct": (
+        "olmo-2-1124-7B-instruct-Q4_K_M.gguf",
+        "OLMo-2-1124-7B-Instruct-Q4_K_M.gguf",
     ),
 }
 

distinct_mcp/external.py

@@ -0,0 +1,275 @@
+"""A catalogue of external, locally-run MCP servers, and the way in.
+
+These are other people's programs. The in-process servers beside this module
+run inside the worker and are governed by it; everything listed here runs as
+a child process speaking MCP over stdio, does its own I/O, and is exactly as
+trustworthy as its publisher. So this module is a catalogue and a doorway,
+never an installer: nothing below downloads anything, nothing starts unless
+an operator names the server, and a server whose credentials are absent
+refuses at connect time with the variable names it wanted — the credential
+values themselves are never read into this process beyond handing the child
+its environment.
+
+**Authentication is per server and stays in the environment.** Each entry
+names the environment variables its server reads (an API key, or Google
+Application Default Credentials established with ``gcloud auth login``).
+This module checks presence, never value, and passes the environment through
+to the child. Nothing here stores, logs or transmits a credential.
+
+The Google entries come from https://github.com/google/mcp — the repository
+is a directory of Google's official servers, and the ones catalogued here
+are its "open-source, run locally" set. The Playwright and Postman entries
+are the official publishers' packages. Remote/hosted MCP endpoints from that
+list are deliberately not catalogued: a remote tool server is a different
+trust conversation from a local child process, and this catalogue refuses to
+blur it.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+
+from distinct_tools.mcp import McpError, StdioMcpTransport
+
+__all__ = [
+    "ExternalMcpServer",
+    "EXTERNAL_CATALOGUE",
+    "connect_external",
+    "describe_external",
+    "external_by_name",
+]
+
+
+@dataclass(frozen=True)
+class ExternalMcpServer:
+    """One locally-runnable server: how to start it, what it needs, who made it."""
+
+    name: str
+    publisher: str
+    summary: str
+    #: The command line, exactly. ``npx --yes`` and ``uvx`` fetch on first
+    #: run; that is the publisher's distribution mechanism, stated rather
+    #: than hidden.
+    command: tuple[str, ...]
+    #: Environment variable NAMES the server authenticates with. Presence is
+    #: checked before spawn; values are never read by this module.
+    auth_env: tuple[str, ...] = ()
+    #: Auth that is a local login state rather than a variable, e.g. Google
+    #: Application Default Credentials. Recorded for the operator's console.
+    auth_note: str = ""
+    #: Hosts the operator consents to this server reaching. A record of
+    #: consent, not a control: the child does its own I/O.
+    hosts: tuple[str, ...] = ()
+    source: str = ""
+
+    @property
+    def runtime(self) -> str:
+        return self.command[0]
+
+
+_GOOGLE_ADC = (
+    "Authenticate with Google Application Default Credentials: run "
+    "`gcloud auth application-default login` once as the operator."
+)
+
+EXTERNAL_CATALOGUE: tuple[ExternalMcpServer, ...] = (
+    ExternalMcpServer(
+        name="playwright",
+        publisher="Microsoft",
+        summary=(
+            "Drive a real browser: navigate, click, fill and read pages. Needs a "
+            "Chromium install; set PLAYWRIGHT_BROWSERS_PATH to reuse one already "
+            "on the machine instead of downloading another."
+        ),
+        command=("npx", "--yes", "@playwright/mcp@latest"),
+        auth_env=(),
+        auth_note="No account. The browser itself is the capability.",
+        hosts=("*",),
+        source="https://github.com/microsoft/playwright-mcp",
+    ),
+    ExternalMcpServer(
+        name="postman",
+        publisher="Postman",
+        summary=(
+            "Postman's official server: collections, environments and API "
+            "definitions in your workspaces, the public API network included."
+        ),
+        command=("npx", "--yes", "@postman/postman-mcp-server"),
+        auth_env=("POSTMAN_API_KEY",),
+        auth_note="Create a key at https://postman.com/settings/me/api-keys.",
+        hosts=("api.getpostman.com",),
+        source="https://github.com/postmanlabs/postman-mcp-server",
+    ),
+    ExternalMcpServer(
+        name="google-workspace",
+        publisher="Google",
+        summary="Docs, Sheets, Slides, Calendar and Gmail in the operator's Workspace.",
+        command=("npx", "--yes", "@googleworkspace/mcp"),
+        auth_env=(),
+        auth_note=_GOOGLE_ADC,
+        hosts=("*.googleapis.com",),
+        source="https://github.com/gemini-cli-extensions/workspace",
+    ),
+    ExternalMcpServer(
+        name="google-analytics",
+        publisher="Google",
+        summary="Report on Analytics properties: audiences, events, conversions.",
+        command=("uvx", "analytics-mcp"),
+        auth_env=(),
+        auth_note=_GOOGLE_ADC,
+        hosts=("analyticsdata.googleapis.com", "analyticsadmin.googleapis.com"),
+        source="https://github.com/googleanalytics/google-analytics-mcp",
+    ),
+    ExternalMcpServer(
+        name="google-cloud-storage",
+        publisher="Google",
+        summary="List, read and manage Cloud Storage buckets and objects.",
+        command=("npx", "--yes", "@google-cloud/storage-mcp"),
+        auth_env=(),
+        auth_note=_GOOGLE_ADC,
+        hosts=("storage.googleapis.com",),
+        source="https://github.com/googleapis/gcloud-mcp",
+    ),
+    ExternalMcpServer(
+        name="gcloud",
+        publisher="Google",
+        summary="The gcloud CLI as tools: inspect and manage Google Cloud projects.",
+        command=("npx", "--yes", "@google-cloud/gcloud-mcp"),
+        auth_env=(),
+        auth_note=_GOOGLE_ADC + " Also requires the gcloud CLI on PATH.",
+        hosts=("*.googleapis.com",),
+        source="https://github.com/googleapis/gcloud-mcp",
+    ),
+    ExternalMcpServer(
+        name="google-observability",
+        publisher="Google",
+        summary="Cloud Logging, Monitoring and Trace: read logs and metrics.",
+        command=("npx", "--yes", "@google-cloud/observability-mcp"),
+        auth_env=(),
+        auth_note=_GOOGLE_ADC,
+        hosts=("logging.googleapis.com", "monitoring.googleapis.com"),
+        source="https://github.com/googleapis/gcloud-mcp",
+    ),
+    ExternalMcpServer(
+        name="mcp-toolbox-databases",
+        publisher="Google",
+        summary=(
+            "Databases behind one server: BigQuery, Cloud SQL, AlloyDB, Spanner, "
+            "Postgres and more, from a tools.yaml the operator writes."
+        ),
+        command=("toolbox", "--stdio"),
+        auth_env=(),
+        auth_note=(
+            "Install the MCP Toolbox binary and write its tools.yaml; database "
+            "credentials live in that file or in " + _GOOGLE_ADC
+        ),
+        hosts=("*",),
+        source="https://github.com/googleapis/genai-toolbox",
+    ),
+    ExternalMcpServer(
+        name="gke",
+        publisher="Google",
+        summary="Kubernetes Engine: inspect clusters, workloads and events.",
+        command=("npx", "--yes", "@google-cloud/gke-mcp"),
+        auth_env=(),
+        auth_note=_GOOGLE_ADC,
+        hosts=("container.googleapis.com",),
+        source="https://github.com/GoogleCloudPlatform/gke-mcp",
+    ),
+    ExternalMcpServer(
+        name="chrome-devtools",
+        publisher="Google (Chrome DevTools)",
+        summary="Debug a running Chrome: inspect pages, console, network and traces.",
+        command=("npx", "--yes", "chrome-devtools-mcp@latest"),
+        auth_env=(),
+        auth_note="No account. Attaches to a local Chrome the operator starts.",
+        hosts=(),
+        source="https://github.com/ChromeDevTools/chrome-devtools-mcp",
+    ),
+)
+
+
+def external_by_name(name: str) -> ExternalMcpServer:
+    for entry in EXTERNAL_CATALOGUE:
+        if entry.name == name:
+            return entry
+    raise McpError(f"no external MCP server named {name!r} is catalogued")
+
+
+def _missing_auth(entry: ExternalMcpServer, environ: Mapping[str, str]) -> tuple[str, ...]:
+    return tuple(var for var in entry.auth_env if not environ.get(var, "").strip())
+
+
+def describe_external(environ: Mapping[str, str] | None = None) -> str:
+    """The operator's view: every entry, its runtime, and its auth state."""
+
+    values = os.environ if environ is None else environ
+    lines = [
+        "External MCP servers this worker can connect on request. Nothing below",
+        "is installed, running or approved until an operator names it.",
+    ]
+    for entry in EXTERNAL_CATALOGUE:
+        missing = _missing_auth(entry, values)
+        runtime_present = shutil.which(entry.runtime) is not None
+        state = []
+        state.append(f"runtime {entry.runtime}: {'present' if runtime_present else 'absent'}")
+        if entry.auth_env:
+            state.append(
+                "auth: ready" if not missing else "auth: missing " + ", ".join(missing)
+            )
+        else:
+            state.append("auth: " + (entry.auth_note or "none"))
+        lines.append(f"  {entry.name}  ({entry.publisher})")
+        lines.append(f"    {entry.summary}")
+        lines.append(f"    {'; '.join(state)}")
+    return "\n".join(lines)
+
+
+def connect_external(
+    name: str,
+    *,
+    environ: Mapping[str, str] | None = None,
+    timeout: float = 60.0,
+) -> StdioMcpTransport:
+    """Spawn one catalogued server and complete the MCP handshake.
+
+    Fails closed, with the exact variable names, when its credentials are
+    absent — a server started without them would answer the handshake and
+    then fail every real call, which is a worse failure because it is a
+    later one. The caller owns the transport and must ``close()`` it; the
+    spawn uses no shell and passes the operator's environment through
+    untouched, which is the entire credential path.
+    """
+
+    entry = external_by_name(name)
+    values = os.environ if environ is None else environ
+    missing = _missing_auth(entry, values)
+    if missing:
+        raise McpError(
+            f"{entry.name} needs {', '.join(missing)} set in the environment. "
+            f"{entry.auth_note}".strip()
+        )
+    if shutil.which(entry.runtime) is None:
+        raise McpError(
+            f"{entry.name} needs {entry.runtime!r} on PATH; install it and retry"
+        )
+
+    def spawn(command: Sequence[str]) -> subprocess.Popen:
+        return subprocess.Popen(
+            list(command),
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            env=dict(values),
+            text=True,
+        )
+
+    transport = StdioMcpTransport(
+        tuple(entry.command), spawn=spawn, handshake_timeout=timeout
+    )
+    transport.start()
+    return transport

distinct_server.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: distinct-server
+Version: 0.1.0
+Summary: Session-only Gradio control plane for community-run open-weight LLM agents
+Requires-Python: >=3.10
+Requires-Dist: gradio[oauth]==6.24.0
+Provides-Extra: agent
+Requires-Dist: dspy[deno]==3.3.0; extra == "agent"
+Requires-Dist: gradio_client==2.6.0; extra == "agent"
+Requires-Dist: pyRAPL==0.2.3.1; sys_platform == "linux" and extra == "agent"
+Requires-Dist: textual==8.2.8; extra == "agent"
+Provides-Extra: dev
+Requires-Dist: pytest==8.4.2; extra == "dev"
+Requires-Dist: ruff==0.12.11; extra == "dev"

distinct_server.egg-info/SOURCES.txt

@@ -0,0 +1,92 @@
+README.md
+pyproject.toml
+distinct_agent/__init__.py
+distinct_agent/__main__.py
+distinct_agent/access.py
+distinct_agent/auth.py
+distinct_agent/cli.py
+distinct_agent/containment.py
+distinct_agent/dashboard.py
+distinct_agent/deno.lock
+distinct_agent/desktop.py
+distinct_agent/energy.py
+distinct_agent/fanout.py
+distinct_agent/firstrun.py
+distinct_agent/guard.py
+distinct_agent/harness.py
+distinct_agent/httpapi.py
+distinct_agent/models.py
+distinct_agent/queue.py
+distinct_agent/rlm.py
+distinct_agent/runners.py
+distinct_agent/sandbox.py
+distinct_agent/server_runner.py
+distinct_agent/servers.py
+distinct_agent/state.py
+distinct_agent/tools.py
+distinct_agent/transport.py
+distinct_agent/tui.py
+distinct_agent/weights.py
+distinct_agent/worker.py
+distinct_agent/isolation/__init__.py
+distinct_agent/isolation/base.py
+distinct_agent/isolation/linux.py
+distinct_agent/isolation/request.py
+distinct_agent/isolation/windows.py
+distinct_agent/isolation/windows_appcontainer.py
+distinct_mcp/__init__.py
+distinct_mcp/common.py
+distinct_mcp/files.py
+distinct_mcp/lists.py
+distinct_mcp/numbers.py
+distinct_mcp/text.py
+distinct_protocol/__init__.py
+distinct_protocol/fences.py
+distinct_protocol/handshake.py
+distinct_protocol/models.py
+distinct_protocol/netpolicy.py
+distinct_protocol/telemetry.py
+distinct_server/__init__.py
+distinct_server/api.py
+distinct_server/auth_routes.py
+distinct_server/catalog.py
+distinct_server/control_plane.py
+distinct_server/identity.py
+distinct_server/models.py
+distinct_server/presentation.py
+distinct_server/render.py
+distinct_server/security.py
+distinct_server/ui.py
+distinct_server/ui_state.py
+distinct_server.egg-info/PKG-INFO
+distinct_server.egg-info/SOURCES.txt
+distinct_server.egg-info/dependency_links.txt
+distinct_server.egg-info/requires.txt
+distinct_server.egg-info/top_level.txt
+distinct_skills/NOTICE.md
+distinct_skills/__init__.py
+distinct_skills/__main__.py
+distinct_skills/handlers.py
+distinct_skills/loader.py
+distinct_skills/manifest.py
+distinct_skills/skills/csv-table/SKILL.md
+distinct_skills/skills/csv-table/tool.json
+distinct_skills/skills/review-checklist/SKILL.md
+distinct_skills/skills/review-checklist/tool.json
+distinct_skills/skills/review-checklist/assets/checklist.md
+distinct_skills/skills/review-checklist/assets/claim-block.md
+distinct_skills/skills/skill-scaffold/SKILL.md
+distinct_skills/skills/skill-scaffold/tool.json
+distinct_skills/skills/skill-scaffold/assets/skill-template.md
+distinct_skills/skills/status-update/SKILL.md
+distinct_skills/skills/status-update/tool.json
+distinct_skills/skills/status-update/assets/status-update.md
+distinct_tools/__init__.py
+distinct_tools/approval.py
+distinct_tools/core.py
+distinct_tools/local.py
+distinct_tools/mcp.py
+distinct_tools/skills.py
+distinct_tools/testing.py
+distinct_tools/trace.py
+distinct_tools/workspace.py

distinct_server.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

distinct_server.egg-info/requires.txt

@@ -0,0 +1,13 @@
+gradio[oauth]==6.24.0
+
+[agent]
+dspy[deno]==3.3.0
+gradio_client==2.6.0
+textual==8.2.8
+
+[agent:sys_platform == "linux"]
+pyRAPL==0.2.3.1
+
+[dev]
+pytest==8.4.2
+ruff==0.12.11

distinct_server.egg-info/top_level.txt

@@ -0,0 +1,6 @@
+distinct_agent
+distinct_mcp
+distinct_protocol
+distinct_server
+distinct_skills
+distinct_tools

distinct_server/catalog.py

@@ -20,7 +20,7 @@ never graded against each other, and never rendered in the same total.
 
 from __future__ import annotations
 
-from collections.abc import Iterable, Mapping
+from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass
 from enum import Enum
 from types import MappingProxyType
@@ -137,53 +137,78 @@ def _all_missing(reason: str) -> Mapping[str, AreaResult]:
 class ReleaseAssessment:
     """A cradle-to-release assessment of one model release.
 
-    ``evidence_grade`` grades *evidence quality only* and is absolute, never
-    cohort-relative.  When there is no usable evidence it is ``None`` -- "No
-    data" is not a grade and must not be rendered as one.
+    This used to carry an ``evidence_grade`` letter alongside the areas, and a
+    sibling ordinal for impact.  Both are gone.  A letter is a ranking this
+    catalogue invented on top of numbers somebody else published, and once the
+    published numbers are shown in full -- with their units, their method and
+    their primary source -- the letter adds no information and one more way to
+    be wrong.  What replaced it is ``coverage``, which is not a score: it counts
+    how many of the six areas have a published result and says nothing about
+    whether those results are large or small.
     """
 
     model_id: str
     coverage: str
     areas: Mapping[str, AreaResult]
-    evidence_grade: Optional[str] = None
+    summary: str = ""
+    covers: str = ""
     weights_sha256: str = ""
     lineage: str = ""
     boundary: str = RELEASE_BOUNDARY
     reason: str = ""
+    links: Sequence[Mapping[str, str]] = ()
 
     def __post_init__(self) -> None:
         missing_areas = set(RUBRIC_AREAS) - set(self.areas)
         if missing_areas:
             raise ValueError(f"release assessment omits areas: {sorted(missing_areas)}")
-        if self.evidence_grade is not None and self.evidence_grade not in {"A", "B", "C", "D"}:
-            raise ValueError("evidence grade must be A-D, or None for no data")
         if self.coverage not in {"Complete", "Partial", "Insufficient", "No data"}:
             raise ValueError("coverage must be Complete, Partial, Insufficient or No data")
-        if self.coverage == "No data" and self.evidence_grade is not None:
-            raise ValueError("'No data' is not a grade and cannot carry one")
+        if self.coverage == "No data" and self.has_any_result:
+            raise ValueError("'No data' cannot carry a published result")
+        if self.coverage != "No data" and not self.has_any_result:
+            raise ValueError("a coverage other than 'No data' requires at least one result")
+        for link in self.links:
+            if not link.get("label") or not link.get("url"):
+                raise ValueError("every link needs both a label and a url")
         object.__setattr__(self, "areas", MappingProxyType(dict(self.areas)))
+        object.__setattr__(self, "links", tuple(MappingProxyType(dict(link)) for link in self.links))
 
     @property
     def has_any_result(self) -> bool:
         return any(item.status is not AreaStatus.MISSING for item in self.areas.values())
 
     @property
-    def grade_display(self) -> str:
-        """Grade, coverage and boundary are visually inseparable."""
+    def assessed_areas(self) -> int:
+        return sum(1 for item in self.areas.values() if item.status is not AreaStatus.MISSING)
 
-        grade = self.evidence_grade or "No data"
-        return f"{grade} · coverage: {self.coverage}"
+    @property
+    def coverage_display(self) -> str:
+        """Coverage and its boundary, inseparable.
+
+        Coverage on its own invites the reading that four of six is a middling
+        score.  It is not a score at all, so the count always travels with the
+        word that says what it counts.
+        """
+
+        if self.coverage == "No data":
+            return "no published result"
+        return f"{self.coverage.lower()} · {self.assessed_areas} of {len(RUBRIC_AREAS)} areas published"
 
     def to_dict(self) -> dict:
         return {
             "model_id": self.model_id,
-            "evidence_grade": self.evidence_grade,
-            "grade_display": self.grade_display,
             "coverage": self.coverage,
+            "coverage_display": self.coverage_display,
+            "assessed_areas": self.assessed_areas,
+            "total_areas": len(RUBRIC_AREAS),
+            "summary": self.summary,
+            "covers": self.covers,
             "boundary": self.boundary,
             "weights_sha256": self.weights_sha256,
             "lineage": self.lineage,
             "reason": self.reason,
+            "links": [dict(link) for link in self.links],
             "areas": {area: item.to_dict() for area, item in self.areas.items()},
         }
 
@@ -191,143 +216,262 @@ class ReleaseAssessment:
 # LABELS NAME THE PUBLICATION, NOT THE SIZE.
 #
 # These used to read "smallest", "balanced test model" and "largest test
-# model". Size is not something this rubric evaluates, and putting it in the
-# name of the thing being chosen invited exactly the reasoning the rubric
+# model". Size is not something this catalogue evaluates, and putting it in the
+# name of the thing being chosen invited exactly the reasoning this surface
 # exists to refuse: that a smaller file is a better environmental choice. It
 # might be, and it might not, and the only way to know is a published result.
 # What belongs in a label is who published the weights, because that is what
-# the evidence grade is about.
+# the reader has to be able to check.
+#
+# WHY THESE THREE. Every model here has a published, model-specific assessment
+# of its training. Models with none were removed rather than listed with an
+# empty record; see the note in ``distinct_agent.models`` for what went and why.
 MODEL_CATALOG: dict[str, ModelManifest] = {
-    # DEFAULT of the worker catalogue: chosen on assessed environmental impact.
-    # Kept in step with distinct_agent.models.KNOWN_MODEL_MANIFESTS; the drift
-    # test in tests/test_catalog.py pins filename, RAM and context length.
-    "olmo-2-1b-instruct": ModelManifest(
-        id="olmo-2-1b-instruct",
-        label="OLMo 2 1B Instruct · first-party GGUF",
-        filename="OLMo-2-0425-1B-Instruct-Q4_K_M.gguf",
-        min_ram_gb=2.0,
+    # DEFAULT of the worker catalogue: the lowest published figures of any
+    # assessed release at a size this network can run. Kept in step with
+    # distinct_agent.models.KNOWN_MODEL_MANIFESTS; the drift test in
+    # tests/test_catalog.py pins filename, RAM and context length.
+    "olmoe-1b-7b-0924-instruct": ModelManifest(
+        id="olmoe-1b-7b-0924-instruct",
+        label="OLMoE 1B-7B 0924 Instruct · Ai2 first-party GGUF",
+        filename="olmoe-1b-7b-0924-instruct-q4_k_m.gguf",
+        min_ram_gb=8.0,
         context_length=4_096,
     ),
-    "olmoe-1b-7b-instruct": ModelManifest(
-        id="olmoe-1b-7b-instruct",
-        label="OLMoE 1B-7B Instruct · first-party GGUF",
-        filename="OLMoE-1B-7B-0125-Instruct-Q4_K_M.gguf",
+    "olmo-2-1124-7b-instruct": ModelManifest(
+        id="olmo-2-1124-7b-instruct",
+        label="OLMo 2 1124 7B Instruct · Ai2 first-party GGUF",
+        filename="olmo-2-1124-7B-instruct-Q4_K_M.gguf",
         min_ram_gb=8.0,
         context_length=4_096,
     ),
-    "qwen3-0.6b": ModelManifest(
-        id="qwen3-0.6b",
-        label="Qwen3 0.6B · unsloth",
-        filename="Qwen3-0.6B-Q4_K_M.gguf",
-        min_ram_gb=2,
-        context_length=40_960,
-    ),
-    "qwen3-4b": ModelManifest(
-        id="qwen3-4b",
-        label="Qwen3 4B · unsloth",
-        filename="Qwen3-4B-Q4_K_M.gguf",
-        min_ram_gb=6,
-        context_length=40_960,
-    ),
     "llama-2-7b-chat": ModelManifest(
         id="llama-2-7b-chat",
-        label="Llama 2 7B Chat · gated licence",
+        label="Llama 2 7B Chat · Meta · gated licence",
         filename="llama-2-7b-chat.Q4_K_M.gguf",
-        min_ram_gb=8,
+        min_ram_gb=8.0,
         context_length=4_096,
     ),
-    "gpt-oss-20b": ModelManifest(
-        id="gpt-oss-20b",
-        label="gpt-oss-20b · MXFP4",
-        filename="gpt-oss-20b-mxfp4.gguf",
-        min_ram_gb=16,
-        context_length=131_072,
-    ),
 }
 
 
-# Why every entry below is "No data".
+# THE ONE ROUTE, AND WHAT IT NOW LETS THROUGH.
 #
-# The rubric forbids assessor-created impact estimates: GPU-hours, FLOPs,
-# tokens, parameters, TDP, PUE, grid factors or another model's LCA must not be
-# converted into invented MWh, tonnes or litres.  Since rubric v1.1 exactly ONE
-# route exists: a published model-specific result, used exactly as published.
-# The contextual route that previously allowed an ordinal judgement from
-# "disclosed scale, hardware, location and controls" has been deleted, because
+# The rule has not changed: a published, model-specific result, used exactly as
+# published. GPU-hours, FLOPs, tokens, parameters, TDP, PUE, grid factors and
+# another model's assessment must not be converted here into invented MWh,
+# tonnes or litres. The contextual route that once allowed an ordinal judgement
+# from "disclosed scale, hardware, location and controls" stays deleted, because
 # it was caught reasoning "a small 0.49B checkpoint moderates demand" into a
-# grade.  That is the parameters-to-impact conversion below, wearing a letter
-# instead of a number.  An area now either has a published result or it is
-# Missing.
+# grade, which is the parameters-to-impact conversion wearing a letter.
 #
-# This repository holds no published model-specific assessment for any of the
-# four catalogue models, so there is nothing to enter by the direct route.  In
-# particular the Qwen3 entries may NOT inherit the Qwen2.5-0.5B-Instruct
-# assessment: transferring an impact value from another model is exactly what
-# the grade sheet prohibits, and a different model version is a different
-# model.
+# What changed is that the catalogue now holds models this rule has something to
+# say about. Every entry below carries real published figures instead of the
+# uniform "No data" this structure used to render, and the detail -- the method
+# behind each number, the primary source, the plain-language summary -- lives in
+# ``model_assessments.json`` and is rendered from there by ``distinct_server.ui``.
+# This structure is the in-catalogue record: enough to be correct on its own if
+# that file is absent, never the fuller surface.
 #
-# The previous code in this file derived tiers 1-4 from `min_ram_gb` and called
-# the result ENVIRONMENTAL_RUBRIC.  That is the parameters-to-impact conversion
-# the grade sheet names explicitly.  It has been removed rather than renamed,
-# because a renamed ordinal is the same invented quantity wearing a different
-# label.  `min_ram_gb` is still shown -- it is a disclosed hardware requirement,
-# a fact about the file, and it makes no environmental claim.
+# WHAT IS STILL FORBIDDEN. Llama 2's energy area stays Missing even though Meta
+# disclosed 184,320 GPU-hours at 400 W, because GPU-hours are not joules and the
+# multiplication is ours, not Meta's. Naming the disclosure in the note is the
+# honest handling; converting it is not.
+_AI2_ASSESSMENT = "https://arxiv.org/abs/2503.05804"
+_LLAMA2_ASSESSMENT = "https://arxiv.org/abs/2307.09288"
+
+_NO_LAND = AreaResult(
+    AreaStatus.MISSING,
+    note=(
+        "No published per-model land or biodiversity figure exists for any model, from "
+        "any lab. ITU-T L.1801 lists the area and states the methodology is developing."
+    ),
+)
+
 RELEASE_ASSESSMENT: dict[str, ReleaseAssessment] = {
-    # The OLMo entries stay "No data" HERE because this structure is the
-    # in-catalogue fallback only. The published Ai2 assessments are rendered
-    # from model_assessments.json's website_display block, which carries the
-    # per-category state discipline this flat structure cannot.
-    "olmo-2-1b-instruct": ReleaseAssessment(
-        model_id="olmo-2-1b-instruct",
-        coverage="No data",
-        areas=_all_missing(
-            "Rendered from model_assessments.json where a published result exists; "
-            "this in-catalogue record deliberately carries none."
+    "olmoe-1b-7b-0924-instruct": ReleaseAssessment(
+        model_id="olmoe-1b-7b-0924-instruct",
+        coverage="Partial",
+        covers=(
+            "The 0924 pretraining run. The tuning that produced this Instruct checkpoint "
+            "is not separately costed in the source."
         ),
-        reason="see the rubric surface, which renders the published assessment set",
-    ),
-    "olmoe-1b-7b-instruct": ReleaseAssessment(
-        model_id="olmoe-1b-7b-instruct",
-        coverage="No data",
-        areas=_all_missing(
-            "Rendered from model_assessments.json where a published result exists; "
-            "this in-catalogue record deliberately carries none."
+        summary=(
+            "The lowest published footprint of any assessed release at a size this network "
+            "can run. Ai2 sampled real GPU power at sub-second intervals rather than "
+            "assuming chips draw their rated wattage, which makes the energy figure one of "
+            "very few genuinely measured training numbers in print. Carbon and water follow "
+            "from that measured energy using the site's own grid factor and cooling "
+            "efficiency, so they describe Texas as much as they describe the model."
         ),
-        reason="see the rubric surface, which renders the published assessment set",
-    ),
-    "qwen3-0.6b": ReleaseAssessment(
-        model_id="qwen3-0.6b",
-        coverage="No data",
-        areas=_all_missing(
-            "No published assessment for this model release. The Qwen2.5-0.5B-Instruct "
-            "assessment is not transferable to Qwen3-0.6B."
+        areas={
+            "energy": AreaResult(
+                AreaStatus.MEASURED,
+                value="54",
+                unit="MWh",
+                note="Final pretraining run, Jupiter cluster, Texas.",
+                source_url=_AI2_ASSESSMENT,
+            ),
+            "climate": AreaResult(
+                AreaStatus.MODELLED,
+                value="18",
+                unit="tCO2e",
+                note=(
+                    "Measured energy at 0.332 kg CO2 per kWh, PUE 1.2. Location-based; "
+                    "no offset applied."
+                ),
+                source_url=_AI2_ASSESSMENT,
+            ),
+            "water": AreaResult(
+                AreaStatus.MODELLED,
+                value="70",
+                unit="kL",
+                note=(
+                    "Measured energy at a water usage effectiveness of 1.29 L per kWh. "
+                    "On-site cooling only; upstream power-station water is not counted."
+                ),
+                source_url=_AI2_ASSESSMENT,
+            ),
+            "land": _NO_LAND,
+            "materials": AreaResult(
+                AreaStatus.MISSING,
+                note=(
+                    "Ai2 report 22 tCO2e and 4.8 kL of embodied hardware impact across their "
+                    "whole programme. That is a programme total, not this release's share."
+                ),
+            ),
+            "pollution": AreaResult(AreaStatus.MISSING, note="Not assessed in the source."),
+        },
+        links=(
+            {
+                "label": "Model card",
+                "url": "https://huggingface.co/allenai/OLMoE-1B-7B-0924-Instruct",
+            },
+            {
+                "label": "Pinned weights",
+                "url": "https://huggingface.co/allenai/OLMoE-1B-7B-0924-Instruct-GGUF",
+            },
+            {"label": "Published assessment", "url": _AI2_ASSESSMENT},
         ),
-        reason="no published model-specific assessment for this release",
     ),
-    "qwen3-4b": ReleaseAssessment(
-        model_id="qwen3-4b",
-        coverage="No data",
-        areas=_all_missing(
-            "No published assessment for this model release. The Qwen2.5-0.5B-Instruct "
-            "assessment is not transferable to Qwen3-4B."
+    "olmo-2-1124-7b-instruct": ReleaseAssessment(
+        model_id="olmo-2-1124-7b-instruct",
+        coverage="Partial",
+        covers=(
+            "The 1124 pretraining run. The tuning that produced this Instruct checkpoint "
+            "is not separately costed in the source."
+        ),
+        summary=(
+            "A dense 7B measured by the same team, in the same data centre, in the same "
+            "year, by the same method as OLMoE. That makes the pair one of the few honest "
+            "like-for-like comparisons in this field: about three times the energy, carbon "
+            "and water for comparable capability. Offered as the fallback if the "
+            "mixture-of-experts architecture gives trouble locally, not because it is lighter."
+        ),
+        areas={
+            "energy": AreaResult(
+                AreaStatus.MEASURED,
+                value="157",
+                unit="MWh",
+                note="Final pretraining run, Jupiter cluster, Texas.",
+                source_url=_AI2_ASSESSMENT,
+            ),
+            "climate": AreaResult(
+                AreaStatus.MODELLED,
+                value="52",
+                unit="tCO2e",
+                note=(
+                    "Measured energy at 0.332 kg CO2 per kWh, PUE 1.2. Location-based; "
+                    "no offset applied."
+                ),
+                source_url=_AI2_ASSESSMENT,
+            ),
+            "water": AreaResult(
+                AreaStatus.MODELLED,
+                value="202",
+                unit="kL",
+                note=(
+                    "Measured energy at 1.29 L per kWh. The 13B sibling drank four times as "
+                    "much on the same architecture because it trained in Iowa, where the "
+                    "figure is 3.1 L per kWh: water tracks the site more than the model."
+                ),
+                source_url=_AI2_ASSESSMENT,
+            ),
+            "land": _NO_LAND,
+            "materials": AreaResult(
+                AreaStatus.MISSING,
+                note=(
+                    "Ai2 report 22 tCO2e and 4.8 kL of embodied hardware impact across their "
+                    "whole programme. That is a programme total, not this release's share."
+                ),
+            ),
+            "pollution": AreaResult(AreaStatus.MISSING, note="Not assessed in the source."),
+        },
+        links=(
+            {
+                "label": "Model card",
+                "url": "https://huggingface.co/allenai/OLMo-2-1124-7B-Instruct",
+            },
+            {
+                "label": "Pinned weights",
+                "url": "https://huggingface.co/allenai/OLMo-2-1124-7B-Instruct-GGUF",
+            },
+            {"label": "Published assessment", "url": _AI2_ASSESSMENT},
         ),
-        reason="no published model-specific assessment for this release",
     ),
     "llama-2-7b-chat": ReleaseAssessment(
         model_id="llama-2-7b-chat",
-        coverage="No data",
-        areas=_all_missing(
-            "No published whole-programme assessment recorded in this repository."
+        coverage="Partial",
+        covers=(
+            "Llama 2 7B pretraining. This Chat checkpoint is a post-trained variant; Meta "
+            "report fine-tuning compute inside the family total without breaking it out."
         ),
-        reason="no published model-specific assessment recorded here",
-    ),
-    "gpt-oss-20b": ReleaseAssessment(
-        model_id="gpt-oss-20b",
-        coverage="No data",
-        areas=_all_missing(
-            "No published whole-programme assessment recorded in this repository."
+        summary=(
+            "The only non-Ai2 release here with a published model-specific figure, and a "
+            "thin one: carbon and nothing else, modelled from rated chip wattage rather "
+            "than measured draw. It is a different kind of number from the two above and "
+            "should not be lined up beside them. Meta also report a second carbon column "
+            "reading zero on the grounds that they buy matching renewable electricity "
+            "annually; that is an accounting position, not a physical one, and the figure "
+            "shown here is what the grid actually delivered."
+        ),
+        reason="unpinned: Meta publish no GGUF and the source repository is gated",
+        areas={
+            "energy": AreaResult(
+                AreaStatus.MISSING,
+                note=(
+                    "Meta disclosed 184,320 A100-80GB GPU-hours at 400 W rated draw but "
+                    "published no energy figure. Multiplying those out would be an estimate "
+                    "this catalogue invented, so the area stays Missing and the disclosure "
+                    "is named instead."
+                ),
+            ),
+            "climate": AreaResult(
+                AreaStatus.MODELLED,
+                value="31.22",
+                unit="tCO2e",
+                note=(
+                    "Modelled by Meta from GPU-hours and rated device power. Location-based. "
+                    "Meta separately report it as fully offset, which nets to zero on paper "
+                    "but not on the grid."
+                ),
+                source_url=_LLAMA2_ASSESSMENT,
+            ),
+            "water": AreaResult(AreaStatus.MISSING, note="Not disclosed."),
+            "land": _NO_LAND,
+            "materials": AreaResult(
+                AreaStatus.MISSING,
+                note="Not disclosed. Embodied hardware impact is absent from Meta's accounting.",
+            ),
+            "pollution": AreaResult(AreaStatus.MISSING, note="Not disclosed."),
+        },
+        links=(
+            {
+                "label": "Model card",
+                "url": "https://huggingface.co/meta-llama/Llama-2-7b-chat-hf",
+            },
+            {"label": "Published assessment", "url": _LLAMA2_ASSESSMENT},
         ),
-        reason="no published model-specific assessment recorded here",
     ),
 }
 

distinct_server/presentation.py

@@ -84,6 +84,40 @@ HEAD = """
       href="https://fonts.googleapis.com/css2?family=Inter:opsz,wght@14..32,400..800&display=swap">
 <link rel="stylesheet"
       href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400..700&display=swap">
+
+<script>
+(function(){
+  function media(el){return el.closest ? el.closest('.c-libcard__media') : null;}
+  function show(m){
+    if(!m || m.classList.contains('is-playing')) return;
+    var src = m.getAttribute('data-gif');
+    if(!src) return;
+    var img = document.createElement('img');
+    img.src = src; img.alt='';
+    m.appendChild(img); m.classList.add('is-playing');
+  }
+  function hide(m){
+    if(!m) return;
+    m.classList.remove('is-playing');
+    m.querySelectorAll('img').forEach(function(i){i.remove();});
+  }
+  document.addEventListener('mouseover', function(e){show(media(e.target));});
+  document.addEventListener('mouseout', function(e){
+    var m = media(e.target);
+    if(m && !m.contains(e.relatedTarget)) hide(m);
+  });
+  var holdTimer=null;
+  document.addEventListener('touchstart', function(e){
+    var m = media(e.target); if(!m) return;
+    holdTimer = setTimeout(function(){show(m);}, 300);
+  }, {passive:true});
+  ['touchend','touchcancel'].forEach(function(name){
+    document.addEventListener(name, function(e){
+      clearTimeout(holdTimer); hide(media(e.target));
+    }, {passive:true});
+  });
+})();
+</script>
 """
 
 
@@ -1320,4 +1354,93 @@ details[open] .c-libhelp__toggle::after{content:" -";}
   .c-panel code,.c-panel pre{overflow-wrap:anywhere;}
   .c-join__qr svg{width:128px; height:128px;}
 }
+
+
+/* ---- Library page: cards over tick boxes ------------------------------ */
+.c-library-section{scroll-margin-top:24px;}
+.c-libgrid{display:grid; grid-template-columns:repeat(auto-fill,minmax(240px,1fr));
+           gap:var(--s4); margin:var(--s4) 0;}
+.c-libcard{background:var(--c-surface); border:1px solid var(--c-hairline);
+           border-radius:var(--r-lg); padding:var(--s4);
+           display:flex; flex-direction:column; gap:6px;
+           transition:box-shadow .18s ease, transform .18s ease;}
+.c-libcard:hover{box-shadow:var(--e2); transform:translateY(-2px);}
+.c-libcard__media{margin:calc(var(--s4)*-1) calc(var(--s4)*-1) var(--s2);
+                  aspect-ratio:16/9; border-radius:var(--r-lg) var(--r-lg) 0 0;
+                  background:var(--c-fill) center/cover no-repeat;
+                  display:flex; align-items:center; justify-content:center;
+                  overflow:hidden; position:relative;}
+.c-libcard__media img{width:100%; height:100%; object-fit:cover; display:block;}
+.c-libcard__play{font-size:22px; color:var(--c-muted); opacity:.8;}
+.c-libcard__media.is-playing .c-libcard__play{display:none;}
+.c-libcard__head{display:flex; align-items:center; gap:var(--s2);}
+.c-libcard__kind{font-size:var(--t-micro); letter-spacing:.06em; text-transform:uppercase;
+                 padding:2px 8px; border-radius:999px; background:var(--c-fill);
+                 color:var(--c-text-2);}
+.c-libcard__kind--skill{background:var(--c-sage-wash, #e7efe7); color:var(--c-sage-deep);}
+.c-libcard__default{margin-left:auto; font-size:var(--t-micro); color:var(--c-sage-deep);
+                    border:1px solid currentColor; border-radius:999px; padding:1px 8px;}
+.c-libcard__name{margin:0; font-size:var(--t-body); font-weight:650; color:var(--c-text);
+                 text-transform:capitalize;}
+.c-libcard__author{margin:0; font-size:var(--t-micro); color:var(--c-muted);}
+.c-libcard__desc{margin:2px 0 0; font-size:var(--t-small, 13px); line-height:1.5;
+                 color:var(--c-text-2);
+                 display:-webkit-box; -webkit-line-clamp:4; -webkit-box-orient:vertical;
+                 overflow:hidden;}
+.c-libcard__ref{margin-top:auto; padding-top:var(--s2); font-family:var(--mono);
+                font-size:11px; color:var(--c-muted);}
+.c-librarydefaults-head{margin-top:var(--s4);}
+
+/* ---- Quick nav under the identity box --------------------------------- */
+.c-quicknav{display:flex; gap:var(--s3); justify-content:flex-end;
+            margin:calc(var(--s2)*-1) 0 var(--s2);}
+.c-quicknav__link{font-size:var(--t-micro); letter-spacing:.04em; text-decoration:none;
+                  color:var(--c-sage-deep); border:1px solid var(--c-hairline);
+                  background:var(--c-surface); padding:4px 12px; border-radius:999px;}
+.c-quicknav__link:hover{border-color:var(--c-sage-deep);}
+
+/* ---- The no-agents veil ----------------------------------------------- */
+/* Shown only while somebody is signed in (the identity span has text) and
+   the worker panel is in its empty state. Pure CSS state: no events. */
+.c-veil{display:none;}
+.c-conversation{position:relative;}
+.c-shell:has(.c-identity:not(:empty)):has(.c-noworker-hook) .c-veil{
+  display:flex; position:absolute; inset:0; z-index:12;
+  align-items:center; justify-content:center; padding:var(--s5);
+  background:color-mix(in srgb, var(--c-bg, #f7f9f3) 62%, transparent);
+  backdrop-filter:blur(2.5px); border-radius:var(--r-lg);
+  /* The veil informs; it does not imprison. Pointer events pass through
+     everywhere except its own panel, so a transient no-worker blip (a poll
+     gap, a mode change) can never trap a click mid-flow. */
+  pointer-events:none;}
+.c-veil__panel{pointer-events:auto;}
+.c-shell:has(.c-identity:not(:empty)):has(.c-noworker-hook) .c-conversation > *:not(.c-veil):not(:first-child){
+  opacity:.45; filter:saturate(.7);}
+.c-veil__panel{max-width:380px; text-align:center; background:var(--c-surface);
+               border:1px solid var(--c-hairline); border-radius:var(--r-lg);
+               box-shadow:var(--e2); padding:var(--s5);}
+.c-veil__title{margin:0 0 6px; font-weight:650; font-size:var(--t-lg); color:var(--c-text);}
+.c-veil__body{margin:0 0 var(--s4); color:var(--c-text-2); line-height:1.55;}
+.c-veil__action{display:inline-block; text-decoration:none; background:var(--c-sage-deep);
+                color:#fff; padding:10px 20px; border-radius:999px; font-weight:600;}
+.c-veil__action:hover{filter:brightness(1.08);}
+
+/* ---- Professional polish pass ----------------------------------------- */
+/* Calmer sections: the tail accordions read as pages, not widgets. */
+.c-tail .gradio-accordion, .c-tail details{background:var(--c-surface);
+  border:1px solid var(--c-hairline) !important; border-radius:var(--r-lg) !important;
+  padding:var(--s3) var(--s4) !important; margin-bottom:var(--s4) !important;}
+.c-tail .label-wrap span{font-weight:650 !important; font-size:var(--t-lg) !important;}
+/* One shadow language everywhere. */
+.c-grade-card,.c-panel,.c-legend,.c-workers article{box-shadow:none !important;}
+/* Inputs: quiet until focused. */
+.gradio-container input[type="text"], .gradio-container textarea{
+  border-radius:var(--r-md) !important;}
+@media (max-width:700px){
+  .c-libgrid{grid-template-columns:1fr 1fr; gap:var(--s3);}
+  .c-quicknav{justify-content:flex-start;}
+}
+@media (max-width:460px){
+  .c-libgrid{grid-template-columns:1fr;}
+}
 """

distinct_server/render.py

@@ -177,7 +177,7 @@ def no_tools_note(notice_text: str) -> str:
     )
 
 
-def join_this_server(*, addresses, code: str, qr: str = "") -> str:
+def join_this_server(*, addresses, code: str, qr: str = "", tools: str = "local") -> str:
     """What to point an agent at, with the address filled in.
 
     This panel exists because the previous instruction was a command with
@@ -215,11 +215,13 @@ def join_this_server(*, addresses, code: str, qr: str = "") -> str:
         else '<p class="c-join__lead">Generate a pairing code below, then run the '
         "command with it.</p>"
     )
+    # One line on purpose. The previous form used backslash continuations,
+    # which are bash syntax: pasted into PowerShell they became stray
+    # arguments and the command half-ran. A single line pastes correctly
+    # into every shell anybody actually uses.
     command = (
-        f"python -m distinct_agent \\\n"
-        f"  --server {first} \\\n"
-        f"  --pair {code or 'YOUR-CODE'} \\\n"
-        f"  --models qwen3-0.6b --tools local"
+        f"python -m distinct_agent --server {first} "
+        f"--pair {code or 'YOUR-CODE'} --models qwen3-0.6b --tools {tools or 'local'}"
     )
     picture = f'<div class="c-join__qr">{qr}</div>' if qr else ""
     return (
@@ -509,7 +511,7 @@ def worker_cards(rows: Sequence[Sequence[object]], *, narrowed_by: str = "") ->
     """
 
     if not rows:
-        return empty_state(
+        return '<div class="c-noworker-hook">' + empty_state(
             glyph="○",
             title="No compatible worker",
             # Which of the choices above emptied the list. Without this the
@@ -531,7 +533,7 @@ def worker_cards(rows: Sequence[Sequence[object]], *, narrowed_by: str = "") ->
                 )
             ),
             compact=True,
-        )
+        ) + "</div>"
 
     cards: list[str] = []
     for row in rows:
@@ -781,6 +783,18 @@ def energy_headline(
     )
 
 
+def format_joules_per_token(value: float) -> str:
+    """Joules per token at a scale people can read.
+
+    A small model's figure is millijoules; a big machine's is joules. Two
+    decades of unit, chosen by size, so neither reads as zero.
+    """
+
+    if value >= 1.0:
+        return f"{value:.2f} J/tok"
+    return f"{value * 1000:.1f} mJ/tok"
+
+
 def format_joules(joules: float) -> str:
     """A figure with a unit people read without converting.
 
@@ -1162,6 +1176,79 @@ def _energy_block(lines: Sequence[str], *, measured: bool, quiet: bool = False)
 # --------------------------------------------------------------------------
 
 
+
+# --------------------------------------------------------------------------
+# Library cards
+# --------------------------------------------------------------------------
+
+_DEMO_DIR = (Path(__file__).resolve().parent.parent / "assets" / "library-demos")
+_DEMO_BASE = f"/gradio_api/file={_DEMO_DIR.as_posix()}"
+
+
+def _demo_gif(ref: str) -> str:
+    """The demo GIF's URL for a library member, or nothing.
+
+    The file is looked for on disk at render time so a card never promises a
+    demonstration the repository does not carry. Slug: the ref with ``@`` and
+    ``.`` flattened, which is how the recorder names them.
+    """
+
+    slug = ref.replace("@", "-").replace(".", "-")
+    if (_DEMO_DIR / f"{slug}.gif").is_file():
+        return f"{_DEMO_BASE}/{slug}.gif"
+    return ""
+
+
+def library_cards(rows: Sequence[Mapping[str, object]], chosen: Sequence[str]) -> str:
+    """The library as cards a person reads, not a list of tick boxes.
+
+    Every field is escaped: descriptions come from tool specs, which workers
+    and third-party repositories can influence. The demo image is attached as
+    ``data-gif`` and only swapped in by the page's own hover script, so a
+    card with no recording is simply a card, not a broken image.
+    """
+
+    if not rows:
+        return empty_state(
+            glyph="◇",
+            title="Nothing matches",
+            body="No library member matches that search. Clear it to see the shelf.",
+        )
+    picked = set(chosen)
+    cards = []
+    for row in rows:
+        ref = str(row.get("ref", ""))
+        kind = str(row.get("kind", "tool"))
+        name = str(row.get("name", ref))
+        author = str(row.get("author", "distinct"))
+        description = str(row.get("description", ""))
+        gif = _demo_gif(ref)
+        media = (
+            f'<figure class="c-libcard__media" data-gif="{esc(gif)}">'
+            '<span class="c-libcard__play" aria-hidden="true">&#9656;</span>'
+            "<figcaption class=\"c-visually-hidden\">Hover or hold to preview</figcaption>"
+            "</figure>"
+            if gif
+            else ""
+        )
+        default_mark = (
+            '<span class="c-libcard__default">default</span>' if ref in picked else ""
+        )
+        cards.append(
+            f'<article class="c-libcard c-libcard--{esc(kind)}">'
+            f"{media}"
+            '<div class="c-libcard__head">'
+            f'<span class="c-libcard__kind c-libcard__kind--{esc(kind)}">{esc(kind)}</span>'
+            f"{default_mark}"
+            "</div>"
+            f'<h3 class="c-libcard__name">{esc(name)}</h3>'
+            f'<p class="c-libcard__author">by {esc(author)}</p>'
+            f'<p class="c-libcard__desc">{esc(description)}</p>'
+            f'<code class="c-libcard__ref">{esc(ref)}</code>'
+            "</article>"
+        )
+    return '<div class="c-libgrid">' + "".join(cards) + "</div>"
+
 # --------------------------------------------------------------------------
 # Better Images of AI: the artwork set, and attribution that cannot drift
 # --------------------------------------------------------------------------

distinct_server/ui.py

@@ -13,9 +13,10 @@ from typing import Any, Mapping, Optional, Sequence
 import gradio as gr
 
 from distinct_protocol import (
-    AGENT_MODES,
     MAX_LIVE_STEP_TEXT,
     MAX_RUN_STEPS,
+    MODE_AGENT,
+    MODE_SIMPLE,
     PHASE_CALLING_TOOL,
     PHASE_FETCHING_WEIGHTS,
     PHASE_GENERATING,
@@ -27,8 +28,6 @@ from distinct_protocol import (
     PHASE_QUEUED_ON_WORKER,
     PHASE_WAITING_FOR_WORKER,
     PHASE_WORKING,
-    MODE_AGENT,
-    MODE_SIMPLE,
     STEP_KINDS,
     STEP_PHASE,
     AgentStatus,
@@ -37,13 +36,13 @@ from distinct_protocol import (
     ToolSelection,
     normalise_phase,
 )
-from distinct_protocol.fences import FILE_FENCE_BODIES
+from distinct_protocol.fences import FILE_FENCE_BODIES, defang_marker_value
 from distinct_protocol.fences import defang as _defang_fences
-from distinct_protocol.fences import defang_marker_value
 from distinct_protocol.handshake import Allowance
 
 from . import render
 from .api import AgentApi
+from .auth_routes import identity_from_session
 from .catalog import (
     AREA_LABELS,
     MODEL_CATALOG,
@@ -54,7 +53,6 @@ from .catalog import (
     model_choices,
 )
 from .control_plane import ControlPlane
-from .auth_routes import LOGIN_PATH, identity_from_session
 from .identity import (
     LoginRequired,
     SessionAuthorizer,
@@ -186,15 +184,24 @@ def _library_specs() -> Mapping[str, Mapping[str, str]]:
 
     try:
         import distinct_tools
+        from distinct_tools.skills import REPOSITORY_SKILLS, REPOSITORY_SPECS
 
-        return {
-            f"{spec.tool_id}@{spec.version}": {
+        adapted: dict[str, str] = {}
+        for skill in REPOSITORY_SKILLS:
+            source = str(getattr(skill, "source", "") or "")
+            adapted[skill.tool_id] = (
+                "Anthropic · adapted" if "anthropics/skills" in source else "distinct"
+            )
+        specs: dict[str, dict[str, str]] = {}
+        for spec in tuple(distinct_tools.INSTALLABLE_SPECS) + tuple(REPOSITORY_SPECS):
+            ref = f"{spec.tool_id}@{spec.version}"
+            specs[ref] = {
                 "kind": getattr(spec, "kind", "tool"),
                 "name": str(spec.tool_id).replace("_", " "),
                 "description": str(getattr(spec, "description", "")),
+                "author": adapted.get(str(spec.tool_id), "distinct"),
             }
-            for spec in distinct_tools.INSTALLABLE_SPECS
-        }
+        return specs
     except Exception:
         return {}
 
@@ -401,11 +408,29 @@ class EnergyReading:
     scope: str
     provider: str
     reason: Optional[str] = None
+    #: Real output token count from the runner, when the runner counted one.
+    #: Never derived from characters: an estimated token is not a token.
+    output_tokens: Optional[int] = None
 
     @property
     def measured(self) -> bool:
         return self.status == ENERGY_MEASURED
 
+    @property
+    def joules_per_token(self) -> Optional[float]:
+        """Joules per generated token: the efficiency figure, when honest.
+
+        Defined only when both halves were actually measured — a joule figure
+        from the meter and a token count from the runner. This is the
+        ``average power ÷ generation speed`` identity, computed on totals.
+        """
+
+        if not self.measured or not self.joules or not self.output_tokens:
+            return None
+        if self.output_tokens <= 0:
+            return None
+        return float(self.joules) / float(self.output_tokens)
+
     @property
     def line(self) -> str:
         """The one line a completed run carries in the transcript.
@@ -427,7 +452,16 @@ class EnergyReading:
             return f"Electricity: — **No data**{detail} · not counted as zero"
         means = render.comparator(float(self.joules or 0.0))
         suffix = f" · {means}" if means else ""
-        return f"Electricity: **{render.format_joules(float(self.joules))}**{suffix}"
+        per_token = ""
+        if self.joules_per_token is not None:
+            per_token = (
+                f" · {self.output_tokens} tok"
+                f" · {render.format_joules_per_token(self.joules_per_token)}"
+            )
+        return (
+            f"Electricity: **{render.format_joules(float(self.joules))}**"
+            f"{per_token}{suffix}"
+        )
 
 
 def _energy_reading(result: Any) -> EnergyReading:
@@ -470,7 +504,13 @@ def _energy_reading(result: Any) -> EnergyReading:
         return EnergyReading(
             ENERGY_MISSING, None, scope, provider, reason or "worker reported no joule value"
         )
-    return EnergyReading(ENERGY_MEASURED, total, scope, provider)
+    tokens = None
+    usage = payload.get("usage")
+    if isinstance(usage, Mapping):
+        raw_tokens = usage.get("output_tokens")
+        if isinstance(raw_tokens, int) and not isinstance(raw_tokens, bool) and raw_tokens > 0:
+            tokens = raw_tokens
+    return EnergyReading(ENERGY_MEASURED, total, scope, provider, output_tokens=tokens)
 
 
 def _session_energy_markdown(readings: Sequence[EnergyReading]) -> str:
@@ -683,8 +723,27 @@ def _measurement_note(readings: Sequence[EnergyReading]) -> str:
     if providers:
         parts.append("Measured by: " + ", ".join(providers) + ".")
     parts.append(
-        "Reported by the worker that ran it and not verifiable from here. A run "
-        "that returned no measurement is counted as a run and never as zero."
+        "Measured figures come from hardware counters — Intel RAPL through "
+        "powercap or the Windows EMI driver, an NVIDIA board through NVML or "
+        "nvidia-smi sampling, Apple silicon through its package counters — "
+        "and modelled figures come from CPU busy-time and say so in their "
+        "scope. The two kinds are never added together: different scopes are "
+        "different questions."
+    )
+    parts.append(
+        "Where the runner reported a real token count, each answer also shows "
+        "joules per generated token — total energy over total tokens, the "
+        "same identity as average power divided by generation speed. Token "
+        "counts are never estimated from characters."
+    )
+    parts.append(
+        "Agent-mode runs spend energy beyond generation: tool calls and the "
+        "safety screen are separate passes, and the guard's cost is recorded "
+        "against the run apart from the answer's own — the pipeline overhead "
+        "that measurement studies of agentic systems (e.g. arXiv:2604.00053) "
+        "find can dominate. Reported by the worker that ran it and not "
+        "verifiable from here. A run that returned no measurement is counted "
+        "as a run and never as zero."
     )
     return " ".join(parts)
 
@@ -1057,7 +1116,6 @@ def _grade_suffix(model_id: str) -> str:
         return "no assessment recorded"
     overall = record.get("overall") if isinstance(record.get("overall"), Mapping) else {}
     evidence = record.get("evidence") if isinstance(record.get("evidence"), Mapping) else {}
-    parts: list[str] = []
     letter = _letter(overall.get("letter"))
     if rules.get("impact") and str(overall.get("state") or "") == "grade" and letter:
         assessed = overall.get("areas_assessed")
@@ -1195,10 +1253,15 @@ def _default_server_catalogue() -> "Allowance":
     tools: tuple[str, ...] = ()
     try:
         import distinct_tools
-
-        tools = tuple(
-            sorted(f"{spec.tool_id}@{spec.version}" for spec in distinct_tools.INSTALLABLE_SPECS)
-        )
+        from distinct_tools.skills import REPOSITORY_SPECS
+
+        # The installable set plus the digest-pinned repository: the
+        # repository members are exactly as offerable by a worker, and a
+        # catalogue that omits them silently strips them from every
+        # operator approval — which is how a worker that offered a
+        # repository skill ended up approved for none of them.
+        members = tuple(distinct_tools.INSTALLABLE_SPECS) + tuple(REPOSITORY_SPECS)
+        tools = tuple(sorted(f"{spec.tool_id}@{spec.version}" for spec in members))
     except Exception:
         tools = ()
     return Allowance(models=tuple(MODEL_CATALOG), tools=tools)
@@ -1283,19 +1346,27 @@ class DistinctUI:
 
     # Library ----------------------------------------------------------
 
-    def _advertised_library_refs(self) -> tuple[str, ...]:
-        """Every exact ``id@version`` some agent currently advertises."""
+    def _advertised_library_refs(self, viewer_id: Optional[str] = None) -> tuple[str, ...]:
+        """Every exact ``id@version`` an agent this viewer may see advertises.
+
+        The viewer matters: ``list_agents`` filters by visibility, so asking
+        with no viewer returns nothing at all. That is exactly what happened —
+        every caller here asked viewer-less, the picker's choice list was
+        permanently empty, and "no tools installed" showed beside workers
+        that were advertising a dozen. The library page's descriptions are
+        public; which of them is *offered right now* is per-viewer.
+        """
 
         refs: set[str] = set()
         try:
-            for view in self.control.list_agents():
+            for view in self.control.list_agents(viewer_id=viewer_id):
                 for item in view.capabilities.tools:
                     refs.add(item if "@" in item else f"{item}@1.0.0")
         except ControlPlaneError:
             pass
         return tuple(sorted(refs))
 
-    def _library_choices(self) -> list[tuple[str, str]]:
+    def _library_choices(self, viewer_id: Optional[str] = None) -> list[tuple[str, str]]:
         """Options for the composer's library picker, named for people.
 
         The label leads with a readable name and its kind, because that is
@@ -1306,7 +1377,7 @@ class DistinctUI:
 
         specs = _library_specs()
         choices: list[tuple[str, str]] = []
-        for ref in self._advertised_library_refs():
+        for ref in self._advertised_library_refs(viewer_id):
             spec = specs.get(ref)
             if spec is None:
                 choices.append((f"{ref} · library member", ref))
@@ -1333,8 +1404,12 @@ class DistinctUI:
             )
         return render.library_help(rows)
 
-    def _tool_selections(self, values: Optional[Sequence[str]]) -> tuple[ToolSelection, ...]:
-        advertised = frozenset(self._advertised_library_refs())
+    def _tool_selections(
+        self,
+        values: Optional[Sequence[str]],
+        viewer_id: Optional[str] = None,
+    ) -> tuple[ToolSelection, ...]:
+        advertised = frozenset(self._advertised_library_refs(viewer_id))
         result = []
         for value in values or ():
             if not isinstance(value, str) or "@" not in value:
@@ -1353,6 +1428,7 @@ class DistinctUI:
         selected: Optional[Sequence[str]] = None,
         *,
         defaults: Optional[Sequence[str]] = None,
+        viewer_id: Optional[str] = None,
     ) -> tuple[Any, str]:
         """The refreshed selector plus its undernote, preserving selection.
 
@@ -1365,7 +1441,7 @@ class DistinctUI:
         what a run starts with, never what it is stuck with.
         """
 
-        choices = self._library_choices()
+        choices = self._library_choices(viewer_id)
         valid = {ref for _, ref in choices}
         if selected is None and defaults:
             value = [ref for ref in defaults if ref in valid]
@@ -1409,8 +1485,10 @@ class DistinctUI:
             rows.append({"ref": ref, **spec})
         return rows[: self.LIBRARY_PAGE_LIMIT], len(rows)
 
-    def _library_page(self, query: str, defaults: Sequence[str]) -> tuple[Any, str]:
-        """The page a person picks their defaults on, and its summary line."""
+    def _library_page(
+        self, query: str, defaults: Sequence[str]
+    ) -> tuple[Any, str, str]:
+        """The page a person picks their defaults on: cards, summary, picker."""
 
         rows, matched = self._library_rows(query)
         total = len(_library_specs())
@@ -1429,11 +1507,12 @@ class DistinctUI:
             render.library_summary(
                 shown=len(rows), matched=matched, total=total, chosen=len(kept)
             ),
+            render.library_cards(rows, kept),
         )
 
     def update_library_page(
         self, query: str, state: Mapping[str, Any]
-    ) -> tuple[Any, str]:
+    ) -> tuple[Any, str, str]:
         """Re-filter the page without touching what has been chosen."""
 
         return self._library_page(query, _library_defaults(state))
@@ -1443,7 +1522,9 @@ class DistinctUI:
         visible_choice: Sequence[str],
         query: str,
         state: Mapping[str, Any],
-    ) -> tuple[Any, Any, str, Any, str]:
+        profile: "gr.OAuthProfile | None" = None,
+        request: "gr.Request | None" = None,
+    ) -> tuple[Any, Any, str, str, Any, str]:
         """Record the defaults, merging the visible page into the kept set.
 
         The subtlety is that the component only reports what it can see. A
@@ -1462,11 +1543,17 @@ class DistinctUI:
         }
         specs = _library_specs()
         updated = {**state, "library_defaults": sorted(ref for ref in chosen if ref in specs)}
+        try:
+            viewer_id = self._authorize(dict(state), profile, request)
+        except LoginRequired:
+            viewer_id = None
         selector, note = self._library_components(
-            _library_defaults(updated), defaults=_library_defaults(updated)
+            _library_defaults(updated),
+            defaults=_library_defaults(updated),
+            viewer_id=viewer_id,
         )
-        _, summary = self._library_page(query, _library_defaults(updated))
-        return updated, updated, summary, selector, note
+        _, summary, cards = self._library_page(query, _library_defaults(updated))
+        return updated, updated, summary, cards, selector, note
 
     # Outputs ----------------------------------------------------------
 
@@ -1777,9 +1864,9 @@ class DistinctUI:
             DEFAULT_MODEL_ID, (), "auto", MODE_SIMPLE, viewer_id=user_id
         )
         library, library_note = self._library_components(
-            None, defaults=_library_defaults(updated)
+            None, defaults=_library_defaults(updated), viewer_id=user_id
         )
-        page, page_summary = self._library_page("", _library_defaults(updated))
+        page, page_summary, page_cards = self._library_page("", _library_defaults(updated))
         return (
             updated,
             updated,
@@ -1800,6 +1887,7 @@ class DistinctUI:
             # the moment the accordion is expanded.
             page,
             page_summary,
+            page_cards,
         )
 
     def _live_steps(self, view: Any) -> list[Mapping[str, Any]]:
@@ -1893,7 +1981,7 @@ class DistinctUI:
         """
 
         try:
-            tools = self._tool_selections(tool_values)
+            tools = self._tool_selections(tool_values, viewer_id)
             views = self.control.compatible_agents(
                 model_id, tools, viewer_id=viewer_id, include_offline=True
             )
@@ -2181,7 +2269,7 @@ class DistinctUI:
                 raise ValueError("Enter a request")
             if model_id not in MODEL_CATALOG:
                 raise ValueError("Select a supported model")
-            tools = self._tool_selections(tool_values)
+            tools = self._tool_selections(tool_values, user_id)
             conversation = active_conversation(state)
             parent_job_id = conversation["job_ids"][-1] if conversation["job_ids"] else None
             stored = self._store_attachments(state["session_id"], uploads or ())
@@ -2274,11 +2362,17 @@ class DistinctUI:
         # CheckboxGroup on every tick races the user's own clicks: a box
         # ticked while a tick was in flight would be silently unticked by the
         # stale value coming back.
-        current_refs = self._advertised_library_refs()
-        if current_refs != getattr(self, "_last_library_refs", None):
-            self._last_library_refs = current_refs
+        current_refs = self._advertised_library_refs(viewer_id)
+        cache = getattr(self, "_last_library_refs", None)
+        if not isinstance(cache, dict):
+            cache = {}
+            self._last_library_refs = cache
+        if current_refs != cache.get(viewer_id):
+            cache[viewer_id] = current_refs
             library, library_note = self._library_components(
-                tool_values or None, defaults=_library_defaults(updated)
+                tool_values or None,
+                defaults=_library_defaults(updated),
+                viewer_id=viewer_id,
             )
         else:
             library, library_note = gr.skip(), gr.skip()
@@ -2878,7 +2972,7 @@ class DistinctUI:
             pass
         return ""
 
-    def _join_panel(self, code: str = "") -> str:
+    def _join_panel(self, code: str = "", state: Mapping[str, Any] | None = None) -> str:
         """The address an agent should be pointed at, and the code if minted.
 
         The port comes from the same policy the launch uses, so the panel
@@ -2909,7 +3003,11 @@ class DistinctUI:
                 qr = qr_svg(addresses[0])
             except Exception:  # noqa: BLE001 - the address alone is enough
                 qr = ""
-        return render.join_this_server(addresses=addresses, code=code, qr=qr)
+        # The command mirrors the defaults this browser chose on the library
+        # page, so what the person copies is what their runs will expect.
+        chosen = _library_defaults(state) if state is not None else ()
+        tools = ",".join(chosen) if chosen else "local"
+        return render.join_this_server(addresses=addresses, code=code, qr=qr, tools=tools)
 
     # Pairing/downloads ------------------------------------------------
 
@@ -2922,7 +3020,7 @@ class DistinctUI:
         try:
             user_id = self._authorize(state, profile, request)
             value = self.control.create_pairing_code(user_id)
-            return self._join_panel(value.code)
+            return self._join_panel(value.code, state)
         except (ControlPlaneError, LoginRequired, ValueError) as exc:
             raise gr.Error(str(exc)) from exc
 
@@ -3011,6 +3109,15 @@ class DistinctUI:
                 # button below is the one sign-in control, so a header link
                 # would only duplicate it.
                 identity = gr.HTML(_identity_html(""))
+                # The quick nav sits directly under the identity box: one
+                # anchor per page-worthy section. Links, not buttons, because
+                # they navigate rather than act.
+                gr.HTML(
+                    '<nav class="c-quicknav" aria-label="Sections">'
+                    '<a class="c-quicknav__link" href="#library">Library</a>'
+                    '<a class="c-quicknav__link" href="#join-agent">Run an agent</a>'
+                    "</nav>"
+                )
 
                 # THE SIGN-IN CONTROL, AND WHY IT IS CONDITIONAL.
                 #
@@ -3177,6 +3284,23 @@ class DistinctUI:
                         )
 
                     with gr.Column(elem_classes="c-conversation", min_width=0):
+                        # The no-agents veil. Static markup; presentation.py
+                        # shows it with :has() only while somebody is signed in
+                        # and the worker panel is in its empty state, so there
+                        # is no event plumbing to fall out of date. It softly
+                        # fades the chat rather than hiding it: the interface
+                        # is not broken, it is waiting for a worker.
+                        gr.HTML(
+                            '<div class="c-veil" role="status">'
+                            '<div class="c-veil__panel">'
+                            '<p class="c-veil__title">No agents available</p>'
+                            '<p class="c-veil__body">Nothing can run until a '
+                            "community agent pairs with this server. Set one up "
+                            "in a minute, or come back when one is online.</p>"
+                            '<a class="c-veil__action" href="#join-agent">'
+                            "Set up an agent</a>"
+                            "</div></div>"
+                        )
                         chat = gr.Chatbot(
                             label="Conversation",
                             show_label=False,
@@ -3297,7 +3421,9 @@ class DistinctUI:
                 # left edge of their own. Inside the tail they share the shell's
                 # padding box like everything else.
                 with gr.Column(elem_classes="c-tail"):
-                    with gr.Accordion("Run a community agent", open=False):
+                    with gr.Accordion(
+                        "Run a community agent", open=False, elem_id="join-agent"
+                    ):
                         gr.Markdown(
                             # "The agent owns its bounded FIFO and reports it
                             # on every poll" is true and is a sentence for
@@ -3327,7 +3453,7 @@ class DistinctUI:
                                 "Download agent", variant="secondary"
                             )
                             create_code = gr.Button("Generate pairing code")
-                        code_output = gr.Markdown()
+                        gr.Markdown()
 
                     # THE LIBRARY, AT THE SIZE IT IS GOING TO BE.
                     #
@@ -3338,12 +3464,17 @@ class DistinctUI:
                     # person does here is choose their defaults once; those
                     # are remembered in this browser and tick themselves on
                     # every run where a worker offers them.
-                    with gr.Accordion("Library and your defaults", open=False):
+                    with gr.Accordion(
+                        "Library", open=True, elem_id="library",
+                        elem_classes="c-library-section",
+                    ):
                         gr.Markdown(
-                            "Everything this server knows about. Tick the ones you "
-                            "usually want: they will be selected for you whenever a "
-                            "worker offers them, and you can untick any of them for a "
-                            "single run without changing what is saved here."
+                            "Every tool and skill this server can offer, who wrote "
+                            "it, and what it does. Hover a card — or press and hold "
+                            "on a phone — to watch its demonstration. Tick the "
+                            "members you usually want below: they select themselves "
+                            "whenever a worker offers them, and any run can untick "
+                            "them without changing what is saved."
                         )
                         library_search = gr.Textbox(
                             label="Search the library",
@@ -3355,6 +3486,8 @@ class DistinctUI:
                         library_summary = gr.HTML(
                             render.library_summary(shown=0, matched=0, total=0, chosen=0)
                         )
+                        library_cards_html = gr.HTML(elem_classes="c-librarycards")
+                        gr.Markdown("**Your defaults**", elem_classes="c-librarydefaults-head")
                         library_defaults = gr.CheckboxGroup(
                             label="Your defaults",
                             show_label=False,
@@ -3412,6 +3545,7 @@ class DistinctUI:
                     activity_panel,
                     library_defaults,
                     library_summary,
+                    library_cards_html,
                 ],
                 queue=False,
                 api_visibility="private",
@@ -3612,7 +3746,7 @@ class DistinctUI:
             library_search.input(
                 self.update_library_page,
                 inputs=[library_search, session_state],
-                outputs=[library_defaults, library_summary],
+                outputs=[library_defaults, library_summary, library_cards_html],
                 queue=False,
                 api_visibility="private",
             )
@@ -3623,6 +3757,7 @@ class DistinctUI:
                     session_state,
                     browser_state,
                     library_summary,
+                    library_cards_html,
                     tools,
                     library_note,
                 ],

distinct_skills/handlers.py

@@ -32,7 +32,7 @@ import base64
 import csv
 import io
 import re
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 
 from .loader import (
     MAX_DESCRIPTION_CHARACTERS,
@@ -363,6 +363,637 @@ def csv_table(arguments: Mapping[str, object], skill: SkillDefinition) -> dict[s
     }
 
 
+# --------------------------------------------------------------------------
+# Binary artifacts, and the office formats built as zips of XML
+# --------------------------------------------------------------------------
+
+
+def _multiline(arguments: Mapping[str, object], name: str, *, limit: int) -> str:
+    """Like ``_line`` but newlines are structure here, so they survive.
+
+    Each line is cleaned individually; the line breaks between them are the
+    input format for every handler below that reads rows, slides or sections.
+    """
+
+    value = arguments.get(name)
+    if not isinstance(value, str) or not value.strip():
+        raise SkillInputError(f"{name} must be a non-empty string")
+    if len(value) > limit:
+        raise SkillInputError(f"{name} must be at most {limit} characters")
+    lines = [" ".join(clean_text(line, limit).split()) for line in value.splitlines()]
+    return "\n".join(lines)
+
+
+def bytes_artifact(name: str, media_type: str, payload: bytes) -> dict[str, object]:
+    """The artifact envelope for content that is bytes rather than text.
+
+    ``text_artifact`` above encodes prose. The office formats are zip
+    archives, so they arrive here already encoded; wrapping them through a
+    text path would corrupt them on the first non-ASCII byte.
+    """
+
+    return {
+        "name": name,
+        "media_type": media_type,
+        "base64": base64.b64encode(payload).decode("ascii"),
+        "size_bytes": len(payload),
+    }
+
+
+def _xml_escape(value: str) -> str:
+    return (
+        value.replace("&", "&")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+def _zip_bytes(parts: Mapping[str, str]) -> bytes:
+    """One deterministic zip: fixed timestamps, fixed order, deflate.
+
+    Deterministic because two runs with the same arguments should produce
+    byte-identical files; a timestamp that encodes the wall clock would make
+    every artifact unique for no reason a user can see.
+    """
+
+    import io
+    import zipfile
+
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w", zipfile.ZIP_DEFLATED) as archive:
+        for name in parts:
+            info = zipfile.ZipInfo(name, date_time=(2020, 1, 1, 0, 0, 0))
+            info.compress_type = zipfile.ZIP_DEFLATED
+            archive.writestr(info, parts[name])
+    return buffer.getvalue()
+
+
+_SEPARATORS: Mapping[str, str] = {"pipe": "|", "tab": "\t", "semicolon": ";"}
+
+
+def _rows_from_text(arguments: Mapping[str, object]) -> list[list[str]]:
+    """Header-then-rows lines, split on the named separator, shape-checked.
+
+    The same input convention as ``csv_table`` and for the same reason: a
+    comma would collide with commas inside the data, and a model below 7B
+    handles "one line per row, fields split by a pipe" reliably.
+    """
+
+    text = _multiline(arguments, "text", limit=6000)
+    separator_name = str(arguments.get("separator") or "pipe")
+    if separator_name not in _SEPARATORS:
+        raise SkillInputError("separator must be pipe, tab or semicolon")
+    separator = _SEPARATORS[separator_name]
+    lines = [line for line in text.splitlines() if line.strip()]
+    if len(lines) < 2:
+        raise SkillInputError("text needs a header line and at least one row")
+    rows = [[cell.strip() for cell in line.split(separator)] for line in lines]
+    width = len(rows[0])
+    for index, row in enumerate(rows[1:], start=2):
+        if len(row) != width:
+            raise SkillInputError(
+                f"line {index} has {len(row)} fields where the header has {width}. "
+                "Fix the row rather than letting a column silently shift"
+            )
+    return rows
+
+
+_DOCX_CONTENT_TYPES = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
+    '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
+    '<Default Extension="xml" ContentType="application/xml"/>'
+    '<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>'
+    '<Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>'
+    "</Types>"
+)
+
+_DOCX_ROOT_RELS = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>'
+    "</Relationships>"
+)
+
+_DOCX_DOCUMENT_RELS = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>'
+    "</Relationships>"
+)
+
+_DOCX_STYLES = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">'
+    '<w:style w:type="paragraph" w:styleId="Title"><w:name w:val="Title"/>'
+    '<w:rPr><w:b/><w:sz w:val="48"/></w:rPr></w:style>'
+    '<w:style w:type="paragraph" w:styleId="Heading1"><w:name w:val="heading 1"/>'
+    '<w:rPr><w:b/><w:sz w:val="32"/></w:rPr></w:style>'
+    "</w:styles>"
+)
+
+_W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+
+def _docx_paragraph(text: str, style: str | None = None) -> str:
+    properties = f'<w:pPr><w:pStyle w:val="{style}"/></w:pPr>' if style else ""
+    return (
+        f"<w:p>{properties}<w:r><w:t xml:space=\"preserve\">"
+        f"{_xml_escape(text)}</w:t></w:r></w:p>"
+    )
+
+
+def document_docx(arguments: Mapping[str, object], skill: SkillDefinition) -> dict[str, object]:
+    """A real, minimal ``.docx``: title, headings and paragraphs.
+
+    Lines are paragraphs. A line beginning ``# `` becomes a heading. That is
+    the entire input language, because the point of this skill is that the
+    model supplies sentences and the format arithmetic happens here.
+    """
+
+    del skill
+    _known(arguments, frozenset({"title", "body", "filename"}))
+    title = _line(arguments, "title", limit=200)
+    body = _multiline(arguments, "body", limit=6000)
+    blocks = [_docx_paragraph(title, "Title")]
+    for raw_line in body.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line.startswith("# "):
+            blocks.append(_docx_paragraph(line[2:].strip(), "Heading1"))
+        else:
+            blocks.append(_docx_paragraph(line))
+    document = (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        f'<w:document xmlns:w="{_W}"><w:body>' + "".join(blocks) + "</w:body></w:document>"
+    )
+    payload = _zip_bytes(
+        {
+            "[Content_Types].xml": _DOCX_CONTENT_TYPES,
+            "_rels/.rels": _DOCX_ROOT_RELS,
+            "word/_rels/document.xml.rels": _DOCX_DOCUMENT_RELS,
+            "word/styles.xml": _DOCX_STYLES,
+            "word/document.xml": document,
+        }
+    )
+    return {
+        "artifact": bytes_artifact(
+            _filename(arguments.get("filename"), "document.docx", ".docx"),
+            "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+            payload,
+        )
+    }
+
+
+_XLSX_CONTENT_TYPES = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
+    '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
+    '<Default Extension="xml" ContentType="application/xml"/>'
+    '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>'
+    '<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>'
+    "</Types>"
+)
+
+_XLSX_ROOT_RELS = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>'
+    "</Relationships>"
+)
+
+_XLSX_WORKBOOK = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" '
+    'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">'
+    '<sheets><sheet name="Sheet1" sheetId="1" r:id="rId1"/></sheets></workbook>'
+)
+
+_XLSX_WORKBOOK_RELS = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>'
+    "</Relationships>"
+)
+
+
+def _column_name(index: int) -> str:
+    name = ""
+    while index >= 0:
+        name = chr(ord("A") + index % 26) + name
+        index = index // 26 - 1
+    return name
+
+
+def _xlsx_cell(reference: str, value: str) -> str:
+    if _looks_numeric(value):
+        return f'<c r="{reference}" t="n"><v>{value.strip()}</v></c>'
+    return (
+        f'<c r="{reference}" t="inlineStr"><is><t xml:space="preserve">'
+        f"{_xml_escape(value)}</t></is></c>"
+    )
+
+
+def spreadsheet_xlsx(arguments: Mapping[str, object], skill: SkillDefinition) -> dict[str, object]:
+    """A real ``.xlsx`` from header-then-rows text.
+
+    Numbers become number cells so the spreadsheet can sum them; everything
+    else is an inline string, so nothing here can become a live formula. The
+    same guard reasoning as ``csv_table``: a cell of untrusted text must not
+    run when the file opens.
+    """
+
+    del skill
+    _known(arguments, frozenset({"text", "separator", "filename"}))
+    rows = _rows_from_text(arguments)
+    body: list[str] = []
+    for row_index, row in enumerate(rows, start=1):
+        cells = []
+        for column_index, value in enumerate(row):
+            reference = f"{_column_name(column_index)}{row_index}"
+            guarded, _ = _guard(value)
+            cells.append(_xlsx_cell(reference, guarded))
+        body.append(f'<row r="{row_index}">' + "".join(cells) + "</row>")
+    sheet = (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">'
+        "<sheetData>" + "".join(body) + "</sheetData></worksheet>"
+    )
+    payload = _zip_bytes(
+        {
+            "[Content_Types].xml": _XLSX_CONTENT_TYPES,
+            "_rels/.rels": _XLSX_ROOT_RELS,
+            "xl/workbook.xml": _XLSX_WORKBOOK,
+            "xl/_rels/workbook.xml.rels": _XLSX_WORKBOOK_RELS,
+            "xl/worksheets/sheet1.xml": sheet,
+        }
+    )
+    return {
+        "artifact": bytes_artifact(
+            _filename(arguments.get("filename"), "table.xlsx", ".xlsx"),
+            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            payload,
+        )
+    }
+
+
+# --------------------------------------------------------------------------
+# Slide decks: the smallest package python-pptx and PowerPoint both accept
+# --------------------------------------------------------------------------
+
+_PPTX_CONTENT_TYPES_HEAD = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
+    '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
+    '<Default Extension="xml" ContentType="application/xml"/>'
+    '<Override PartName="/ppt/presentation.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml"/>'
+    '<Override PartName="/ppt/slideMasters/slideMaster1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slideMaster+xml"/>'
+    '<Override PartName="/ppt/slideLayouts/slideLayout1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml"/>'
+    '<Override PartName="/ppt/theme/theme1.xml" ContentType="application/vnd.openxmlformats-officedocument.theme+xml"/>'
+)
+
+_PPTX_ROOT_RELS = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="ppt/presentation.xml"/>'
+    "</Relationships>"
+)
+
+_PPTX_THEME = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="distinct">'
+    '<a:themeElements>'
+    '<a:clrScheme name="distinct">'
+    '<a:dk1><a:srgbClr val="203127"/></a:dk1><a:lt1><a:srgbClr val="F7F9F3"/></a:lt1>'
+    '<a:dk2><a:srgbClr val="2E4636"/></a:dk2><a:lt2><a:srgbClr val="EDF1E6"/></a:lt2>'
+    '<a:accent1><a:srgbClr val="4C7A5E"/></a:accent1><a:accent2><a:srgbClr val="6E9A7F"/></a:accent2>'
+    '<a:accent3><a:srgbClr val="A5C1AE"/></a:accent3><a:accent4><a:srgbClr val="C9D9CC"/></a:accent4>'
+    '<a:accent5><a:srgbClr val="8AA893"/></a:accent5><a:accent6><a:srgbClr val="5C8A6D"/></a:accent6>'
+    '<a:hlink><a:srgbClr val="2E5E43"/></a:hlink><a:folHlink><a:srgbClr val="2E5E43"/></a:folHlink>'
+    "</a:clrScheme>"
+    '<a:fontScheme name="distinct"><a:majorFont><a:latin typeface="Georgia"/><a:ea typeface=""/><a:cs typeface=""/></a:majorFont>'
+    '<a:minorFont><a:latin typeface="Arial"/><a:ea typeface=""/><a:cs typeface=""/></a:minorFont></a:fontScheme>'
+    '<a:fmtScheme name="distinct">'
+    "<a:fillStyleLst><a:solidFill><a:schemeClr val=\"phClr\"/></a:solidFill>"
+    "<a:solidFill><a:schemeClr val=\"phClr\"/></a:solidFill><a:solidFill><a:schemeClr val=\"phClr\"/></a:solidFill></a:fillStyleLst>"
+    '<a:lnStyleLst><a:ln w="6350"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill></a:ln>'
+    '<a:ln w="12700"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill></a:ln>'
+    '<a:ln w="19050"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill></a:ln></a:lnStyleLst>'
+    "<a:effectStyleLst><a:effectStyle><a:effectLst/></a:effectStyle><a:effectStyle><a:effectLst/></a:effectStyle>"
+    "<a:effectStyle><a:effectLst/></a:effectStyle></a:effectStyleLst>"
+    "<a:bgFillStyleLst><a:solidFill><a:schemeClr val=\"phClr\"/></a:solidFill>"
+    "<a:solidFill><a:schemeClr val=\"phClr\"/></a:solidFill><a:solidFill><a:schemeClr val=\"phClr\"/></a:solidFill></a:bgFillStyleLst>"
+    "</a:fmtScheme></a:themeElements></a:theme>"
+)
+
+_PPTX_MASTER = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<p:sldMaster xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" '
+    'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" '
+    'xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main">'
+    '<p:cSld><p:bg><p:bgPr><a:solidFill><a:schemeClr val="lt1"/></a:solidFill><a:effectLst/></p:bgPr></p:bg>'
+    "<p:spTree>"
+    '<p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>'
+    "<p:grpSpPr><a:xfrm><a:off x=\"0\" y=\"0\"/><a:ext cx=\"0\" cy=\"0\"/>"
+    "<a:chOff x=\"0\" y=\"0\"/><a:chExt cx=\"0\" cy=\"0\"/></a:xfrm></p:grpSpPr>"
+    "</p:spTree></p:cSld>"
+    '<p:clrMap bg1="lt1" tx1="dk1" bg2="lt2" tx2="dk2" accent1="accent1" accent2="accent2" '
+    'accent3="accent3" accent4="accent4" accent5="accent5" accent6="accent6" hlink="hlink" folHlink="folHlink"/>'
+    '<p:sldLayoutIdLst><p:sldLayoutId id="2147483649" r:id="rId1"/></p:sldLayoutIdLst>'
+    "</p:sldMaster>"
+)
+
+_PPTX_MASTER_RELS = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout" Target="../slideLayouts/slideLayout1.xml"/>'
+    '<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme" Target="../theme/theme1.xml"/>'
+    "</Relationships>"
+)
+
+_PPTX_LAYOUT = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<p:sldLayout xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" '
+    'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" '
+    'xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main" type="blank">'
+    "<p:cSld><p:spTree>"
+    '<p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>'
+    "<p:grpSpPr><a:xfrm><a:off x=\"0\" y=\"0\"/><a:ext cx=\"0\" cy=\"0\"/>"
+    "<a:chOff x=\"0\" y=\"0\"/><a:chExt cx=\"0\" cy=\"0\"/></a:xfrm></p:grpSpPr>"
+    "</p:spTree></p:cSld>"
+    "</p:sldLayout>"
+)
+
+_PPTX_LAYOUT_RELS = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster" Target="../slideMasters/slideMaster1.xml"/>'
+    "</Relationships>"
+)
+
+_PPTX_SLIDE_RELS = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+    '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout" Target="../slideLayouts/slideLayout1.xml"/>'
+    "</Relationships>"
+)
+
+#: EMU geometry for a 16:9 slide: full width 12192000, height 6858000.
+_PPTX_TITLE_SHAPE = (
+    '<p:sp><p:nvSpPr><p:cNvPr id="2" name="Title"/><p:cNvSpPr><a:spLocks noGrp="1"/></p:cNvSpPr>'
+    "<p:nvPr/></p:nvSpPr>"
+    '<p:spPr><a:xfrm><a:off x="838200" y="838200"/><a:ext cx="10515600" cy="1325563"/></a:xfrm>'
+    '<a:prstGeom prst="rect"><a:avLst/></a:prstGeom></p:spPr>'
+    "<p:txBody><a:bodyPr/><a:lstStyle/>"
+    '<a:p><a:pPr/><a:r><a:rPr lang="en" sz="3600" b="1"><a:solidFill><a:schemeClr val="dk1"/></a:solidFill></a:rPr>'
+    "<a:t>{title}</a:t></a:r></a:p></p:txBody></p:sp>"
+)
+
+_PPTX_BODY_SHAPE_HEAD = (
+    '<p:sp><p:nvSpPr><p:cNvPr id="3" name="Body"/><p:cNvSpPr><a:spLocks noGrp="1"/></p:cNvSpPr>'
+    "<p:nvPr/></p:nvSpPr>"
+    '<p:spPr><a:xfrm><a:off x="838200" y="2438400"/><a:ext cx="10515600" cy="3581400"/></a:xfrm>'
+    '<a:prstGeom prst="rect"><a:avLst/></a:prstGeom></p:spPr>'
+    "<p:txBody><a:bodyPr/><a:lstStyle/>"
+)
+
+
+def _pptx_slide(title: str, points: Sequence[str]) -> str:
+    paragraphs = []
+    for point in points:
+        paragraphs.append(
+            '<a:p><a:pPr marL="285750" indent="-285750"><a:buChar char="&#8226;"/></a:pPr>'
+            f'<a:r><a:rPr lang="en" sz="2000"><a:solidFill><a:schemeClr val="dk2"/></a:solidFill></a:rPr>'
+            f"<a:t>{_xml_escape(point)}</a:t></a:r></a:p>"
+        )
+    if not paragraphs:
+        paragraphs.append("<a:p><a:endParaRPr lang=\"en\"/></a:p>")
+    body = _PPTX_BODY_SHAPE_HEAD + "".join(paragraphs) + "</p:txBody></p:sp>"
+    return (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        '<p:sld xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" '
+        'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" '
+        'xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main">'
+        "<p:cSld><p:spTree>"
+        '<p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>'
+        "<p:grpSpPr><a:xfrm><a:off x=\"0\" y=\"0\"/><a:ext cx=\"0\" cy=\"0\"/>"
+        "<a:chOff x=\"0\" y=\"0\"/><a:chExt cx=\"0\" cy=\"0\"/></a:xfrm></p:grpSpPr>"
+        + _PPTX_TITLE_SHAPE.replace("{title}", _xml_escape(title))
+        + body
+        + "</p:spTree></p:cSld></p:sld>"
+    )
+
+
+def deck_pptx(arguments: Mapping[str, object], skill: SkillDefinition) -> dict[str, object]:
+    """A real ``.pptx``: one slide per input line.
+
+    A line is ``Title :: point; point; point``. The double colon separates
+    the title from its points; the points split on semicolons. One line, one
+    slide, so the model never has to reason about the package format at all.
+    """
+
+    del skill
+    _known(arguments, frozenset({"slides", "filename"}))
+    text = _multiline(arguments, "slides", limit=6000)
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    if not lines:
+        raise SkillInputError("slides needs at least one line")
+    if len(lines) > 30:
+        raise SkillInputError("a deck here is at most 30 slides")
+
+    slides: list[str] = []
+    for line in lines:
+        title, _, tail = line.partition("::")
+        points = [point.strip() for point in tail.split(";") if point.strip()]
+        slides.append(_pptx_slide(title.strip() or "Untitled", points[:10]))
+
+    parts: dict[str, str] = {}
+    overrides = []
+    slide_ids = []
+    slide_rels = []
+    for index, slide in enumerate(slides, start=1):
+        parts[f"ppt/slides/slide{index}.xml"] = slide
+        parts[f"ppt/slides/_rels/slide{index}.xml.rels"] = _PPTX_SLIDE_RELS
+        overrides.append(
+            f'<Override PartName="/ppt/slides/slide{index}.xml" '
+            'ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml"/>'
+        )
+        slide_ids.append(f'<p:sldId id="{255 + index}" r:id="rId{2 + index}"/>')
+        slide_rels.append(
+            f'<Relationship Id="rId{2 + index}" '
+            'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide" '
+            f'Target="slides/slide{index}.xml"/>'
+        )
+
+    parts["[Content_Types].xml"] = _PPTX_CONTENT_TYPES_HEAD + "".join(overrides) + "</Types>"
+    parts["_rels/.rels"] = _PPTX_ROOT_RELS
+    parts["ppt/theme/theme1.xml"] = _PPTX_THEME
+    parts["ppt/slideMasters/slideMaster1.xml"] = _PPTX_MASTER
+    parts["ppt/slideMasters/_rels/slideMaster1.xml.rels"] = _PPTX_MASTER_RELS
+    parts["ppt/slideLayouts/slideLayout1.xml"] = _PPTX_LAYOUT
+    parts["ppt/slideLayouts/_rels/slideLayout1.xml.rels"] = _PPTX_LAYOUT_RELS
+    parts["ppt/presentation.xml"] = (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        '<p:presentation xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" '
+        'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" '
+        'xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main">'
+        '<p:sldMasterIdLst><p:sldMasterId id="2147483648" r:id="rId1"/></p:sldMasterIdLst>'
+        "<p:sldIdLst>" + "".join(slide_ids) + "</p:sldIdLst>"
+        '<p:sldSz cx="12192000" cy="6858000"/><p:notesSz cx="6858000" cy="9144000"/>'
+        "</p:presentation>"
+    )
+    parts["ppt/_rels/presentation.xml.rels"] = (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+        '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster" Target="slideMasters/slideMaster1.xml"/>'
+        '<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme" Target="theme/theme1.xml"/>'
+        + "".join(slide_rels)
+        + "</Relationships>"
+    )
+
+    payload = _zip_bytes(parts)
+    return {
+        "artifact": bytes_artifact(
+            _filename(arguments.get("filename"), "deck.pptx", ".pptx"),
+            "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+            payload,
+        )
+    }
+
+
+# --------------------------------------------------------------------------
+# Web pages, themes and tailored guides
+# --------------------------------------------------------------------------
+
+
+def web_page(arguments: Mapping[str, object], skill: SkillDefinition) -> dict[str, object]:
+    """One clean, self-contained HTML page from a title and sections.
+
+    A section is ``Heading :: body text`` per line. The page carries its own
+    small stylesheet, no scripts and no external requests, so what the user
+    downloads is complete and inert.
+    """
+
+    del skill
+    _known(arguments, frozenset({"title", "sections", "accent", "filename"}))
+    title = _line(arguments, "title", limit=120)
+    text = _multiline(arguments, "sections", limit=6000)
+    accent = str(arguments.get("accent") or "#2E5E43").strip()
+    if not re.fullmatch(r"#[0-9A-Fa-f]{6}", accent):
+        raise SkillInputError("accent must be a #rrggbb colour")
+    blocks = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        heading, _, body = line.partition("::")
+        blocks.append(
+            f"<section><h2>{_xml_escape(heading.strip())}</h2>"
+            f"<p>{_xml_escape(body.strip())}</p></section>"
+        )
+    if not blocks:
+        raise SkillInputError("sections needs at least one 'Heading :: body' line")
+    page = (
+        "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\">"
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        f"<title>{_xml_escape(title)}</title><style>"
+        ":root{--accent:" + accent + ";}"
+        "body{margin:0;font:17px/1.6 Georgia,serif;color:#26302a;background:#faf9f5;}"
+        "main{max-width:680px;margin:0 auto;padding:64px 24px;}"
+        "h1{font-size:2.4rem;line-height:1.15;margin:0 0 8px;}"
+        "h1::after{content:'';display:block;width:56px;height:4px;background:var(--accent);margin-top:16px;}"
+        "h2{font-size:1.15rem;margin:40px 0 6px;color:var(--accent);"
+        "font-family:Arial,sans-serif;letter-spacing:.02em;}"
+        "p{margin:0;}"
+        "</style></head><body><main>"
+        f"<h1>{_xml_escape(title)}</h1>" + "".join(blocks) + "</main></body></html>"
+    )
+    return {
+        "artifact": text_artifact(
+            _filename(arguments.get("filename"), "page.html", ".html"), "text/html", page
+        )
+    }
+
+
+def theme_css(arguments: Mapping[str, object], skill: SkillDefinition) -> dict[str, object]:
+    """A CSS custom-property sheet from a named palette.
+
+    The output is variables plus a few base rules, because a theme that ships
+    opinionated component CSS stops being a theme and starts being a fork of
+    whatever it lands in.
+    """
+
+    del skill
+    _known(arguments, frozenset({"name", "colors", "heading_font", "body_font", "filename"}))
+    theme_name = _line(arguments, "name", limit=60)
+    colors_text = _multiline(arguments, "colors", limit=1200)
+    heading = str(arguments.get("heading_font") or "Georgia, serif").strip()[:80]
+    body_font = str(arguments.get("body_font") or "Arial, sans-serif").strip()[:80]
+    variables = []
+    for line in colors_text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        key, _, value = line.partition(":")
+        key = key.strip().lower()
+        value = value.strip()
+        if not re.fullmatch(r"[a-z][a-z0-9-]{0,30}", key):
+            raise SkillInputError(f"colour name {key!r} must be lowercase-with-hyphens")
+        if not re.fullmatch(r"#[0-9A-Fa-f]{3,8}", value):
+            raise SkillInputError(f"colour {key!r} needs a #hex value, got {value!r}")
+        variables.append(f"  --{key}: {value};")
+    if not variables:
+        raise SkillInputError("colors needs at least one 'name: #hex' line")
+    sheet = (
+        f"/* Theme: {theme_name} — generated by distinct */\n"
+        ":root {\n" + "\n".join(variables) + "\n"
+        f"  --font-heading: {heading};\n"
+        f"  --font-body: {body_font};\n"
+        "}\n\n"
+        "body { font-family: var(--font-body); }\n"
+        "h1, h2, h3, h4 { font-family: var(--font-heading); }\n"
+    )
+    return {
+        "artifact": text_artifact(
+            _filename(arguments.get("filename"), "theme.css", ".css"), "text/css", sheet
+        )
+    }
+
+
+def tailored_guide(arguments: Mapping[str, object], skill: SkillDefinition) -> dict[str, object]:
+    """The skill's own guide, applied to the user's situation.
+
+    The knowledge lives in the skill directory as ``assets/guide.md`` — data,
+    reviewed with the skill — and this handler fills its placeholders. One
+    handler therefore serves every adapted guidance skill, which is how a
+    library of upstream skills stays reviewable: each contributes text, none
+    contributes code.
+    """
+
+    _known(arguments, frozenset({"subject", "context", "filename"}))
+    subject = _line(arguments, "subject", limit=200)
+    context = str(arguments.get("context") or "").strip()[:4000]
+    template = skill.resource("assets/guide.md")
+    text = render(
+        template,
+        {
+            "subject": subject,
+            "context": context or "No further context was given.",
+            "skill": skill.name,
+        },
+    )
+    default_name = f"{skill.name}.md"
+    return {
+        "artifact": text_artifact(
+            _filename(arguments.get("filename"), default_name, ".md"),
+            "text/markdown",
+            text,
+        )
+    }
+
+
 #: The fixed handler table. A skill directory may name one of these and
 #: nothing else.
 HANDLERS: Mapping[str, object] = {
@@ -370,6 +1001,12 @@ HANDLERS: Mapping[str, object] = {
     "skill_scaffold": skill_scaffold,
     "review_checklist": review_checklist,
     "csv_table": csv_table,
+    "document_docx": document_docx,
+    "spreadsheet_xlsx": spreadsheet_xlsx,
+    "deck_pptx": deck_pptx,
+    "web_page": web_page,
+    "theme_css": theme_css,
+    "tailored_guide": tailored_guide,
 }
 
 HANDLER_NAMES = frozenset(HANDLERS)

distinct_skills/manifest.py

@@ -44,18 +44,37 @@ PACKAGED_ROOT = Path(__file__).resolve().parent / "skills"
 #: expect the review to ask why the digest changed.
 PINNED_DIGESTS: Mapping[str, str] = MappingProxyType(
     {
+        "academy-guide": "489ddd4c963552d243d68aa71af3e9f86ea58b6eb15fa77676eb21297d20e683",
+        "algorithmic-art": "a20eeb2e787e8f01f66fefc61fa34d84c7046015ba39728952f97ebe29709822",
+        "brand-guidelines": "bf9abe6506aa7785d36b027fd90f5a5552b40a36f1201ee09b3a680bbfff74d3",
+        "canvas-design": "776e112543645c5b22515c6e503ab572cde35c4633e0fd09e2d7c53ed912cde0",
+        "claude-api": "7f41a0e79797eb14c67e8a7fbfbabdb02da229829997496d719af141a597d0ce",
+        "create-deck": "e7c9a709f4609af0e5560544ecd8b05cb32fe5e52c147a23690f700700ec5b88",
+        "create-docx": "b1e950ab46f324bca84f6aade1d6772f13090e1fb1cb57df761c41bcb4764b7d",
+        "create-xlsx": "73325b2bd0d99ec781610ed9da1af59fef2655fb6e7b3766a29e2915d5ec449d",
         "csv-table": "ff87a44fe03901f0cfb61f46209b6cc7138acf07d87279c936cd8711b0a5e455",
+        "discernment-nudge": "1901fbb6a6a0980fe3c8fc5297d492c39ef02f1c46bbcd77223cf7622cabcd5b",
+        "frontend-design": "283205e755626aae7c517f6a3b0f9b8d16b2d30f32d24822080b58393eae689a",
+        "mcp-builder": "fafc5acb2b8e408182ed8f2be49e9c1dcf41827ceca7bba6aacaccce3393b37b",
         "review-checklist": "98af818e3e4c178021bb87bcf355934b5effca7240b738f48ee344f7c6b6686f",
         "skill-scaffold": "158d1d1ff1ff3ad83865537708cd4464cdd114f420912136917b9c143c32e18e",
+        "slack-gif-creator": "854f079d2843b80cbf3bd261c099f187c07ad0edf69646ca122eee7e77007ae9",
         "status-update": "48b7b1914de88b70e0ff9d19262987aca01696f6ebce061d0793543cbacc309e",
+        "theme-factory": "1b5d9800d869e902757d1b1733f98f3936319ee090035ffe9a82603662ccebe8",
+        "web-artifacts-builder": "4d0576368ca16dea4d5dea809b4766146d49ef84354269289843f55e76f9615e",
+        "webapp-testing": "cde6767ba5c2fd1cca6e86007010b228cb9296ffe3764485122ade9dd88c52fd",
     }
 )
 
 #: A bound on the repository itself, not on any one skill. Every member is a
 #: line in the tool menu a small model has to choose from, and selection error
 #: is the dominant failure below 7B, so growing the repository is a decision
-#: with a measurable cost rather than free shelf space.
-MAX_REPOSITORY_SKILLS = 16
+#: with a measurable cost rather than free shelf space. The bound was raised
+#: from 16 when the adapted Anthropic skills arrived, because the cost moved:
+#: a run's model only ever sees the members chosen for that run in the
+#: composer, so the shelf can be larger than any one menu. The menu a model
+#: reads is still the thing to keep small, per run, by choosing deliberately.
+MAX_REPOSITORY_SKILLS = 24
 
 _SLUG_RE = re.compile(r"[^a-z0-9_-]+")
 

distinct_skills/skills/academy-guide/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: academy-guide
+description: "Build a structured learning path for a topic: modules, order, exercises and checkpoints, delivered as a course outline. Arguments: subject (the topic), context (learner's starting point, time available, goal) and an optional filename. Adapted from Anthropic's academy-guide skill."
+license: Apache-2.0. Adapted for distinct from the Anthropic skills repository.
+source: https://github.com/anthropics/skills
+---
+
+# Academy guide
+
+## What this produces
+
+One markdown document: the method below, applied to the subject the
+caller names. The knowledge lives in `assets/guide.md` beside this
+file; the handler substitutes the subject and context and nothing
+else. Data, never code.

distinct_skills/skills/academy-guide/assets/guide.md

@@ -0,0 +1,23 @@
+# Learning path: {{subject}}
+
+{{context}}
+
+## Method — adapted from Anthropic's academy-guide skill
+
+1. **Start from the learner, not the syllabus.** State what they can already
+   do and the one capability the path exists to add.
+2. **Modules of one idea each.** Five to eight modules, each answering a
+   single question, ordered so every module uses only what came before.
+3. **Exercise before explanation length.** Each module gets one exercise a
+   learner completes in under thirty minutes; the explanation is only as
+   long as the exercise needs.
+4. **Checkpoints that prove capability.** After every second module, a task
+   with no scaffolding. Passing it is the syllabus; the modules are merely
+   the route.
+5. **A finishing project.** One realistic piece of work using the whole
+   path. Define what done looks like on day one.
+
+## Produce
+
+Write the module list with a one-line goal, a resource and an exercise for
+each, the checkpoints, and the finishing project for the subject.

distinct_skills/skills/academy-guide/tool.json

@@ -0,0 +1,28 @@
+{
+  "version": "1",
+  "handler": "tailored_guide",
+  "input_schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "subject": {
+        "type": "string",
+        "maxLength": 200,
+        "description": "what the guide should be applied to, in a few words"
+      },
+      "context": {
+        "type": "string",
+        "maxLength": 4000,
+        "description": "anything already known: audience, constraints, drafts, goals"
+      },
+      "filename": {
+        "type": "string",
+        "maxLength": 80,
+        "description": "optional file name for the result"
+      }
+    },
+    "required": [
+      "subject"
+    ]
+  }
+}

distinct_skills/skills/algorithmic-art/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: algorithmic-art
+description: "Plan a piece of algorithmic art: a named philosophy, a seeded system and the p5.js sketch structure, delivered as a document. Arguments: subject (theme or feeling), context (palette, constraints, interactivity wanted) and an optional filename. Adapted from Anthropic's algorithmic-art skill."
+license: Apache-2.0. Adapted for distinct from the Anthropic skills repository.
+source: https://github.com/anthropics/skills
+---
+
+# Algorithmic art
+
+## What this produces
+
+One markdown document: the method below, applied to the subject the
+caller names. The knowledge lives in `assets/guide.md` beside this
+file; the handler substitutes the subject and context and nothing
+else. Data, never code.

distinct_skills/skills/algorithmic-art/assets/guide.md

@@ -0,0 +1,24 @@
+# Algorithmic art plan: {{subject}}
+
+{{context}}
+
+## Method — adapted from Anthropic's algorithmic-art skill
+
+1. **Philosophy before pixels.** Write three sentences naming the idea the
+   piece explores — growth, erosion, interference, flocking — and the
+   feeling it should leave. Every later choice answers to these sentences.
+2. **Seeded randomness.** One integer seed drives every random draw, so a
+   piece can be reproduced, varied and signed. State the seed in the corner
+   of the canvas.
+3. **One system, explored.** Choose a single generative system (flow field,
+   subdivision, particle trails, reaction-diffusion) and push its
+   parameters, rather than layering three systems thinly.
+4. **Parameter map.** Name 3-5 parameters, their ranges, and what each does
+   visually. These become the piece's interactive controls.
+5. **Craft.** Margins, a considered palette of few colours, and density
+   tuned so the eye rests somewhere. Generative is not an excuse for noise.
+
+## Produce
+
+Write the philosophy, the seed, the system, the parameter map and the p5.js
+sketch outline (setup, draw, the data structure) for the subject.

distinct_skills/skills/algorithmic-art/tool.json

@@ -0,0 +1,28 @@
+{
+  "version": "1",
+  "handler": "tailored_guide",
+  "input_schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "subject": {
+        "type": "string",
+        "maxLength": 200,
+        "description": "what the guide should be applied to, in a few words"
+      },
+      "context": {
+        "type": "string",
+        "maxLength": 4000,
+        "description": "anything already known: audience, constraints, drafts, goals"
+      },
+      "filename": {
+        "type": "string",
+        "maxLength": 80,
+        "description": "optional file name for the result"
+      }
+    },
+    "required": [
+      "subject"
+    ]
+  }
+}

distinct_skills/skills/brand-guidelines/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: brand-guidelines
+description: "Apply a written brand system to whatever is being made: colours, type and usage rules as a one-page reference. Arguments: subject (what the brand should be applied to), context (the brand's colours, fonts and rules if known) and an optional filename. Adapted from Anthropic's brand-guidelines skill."
+license: Apache-2.0. Adapted for distinct from the Anthropic skills repository.
+source: https://github.com/anthropics/skills
+---
+
+# Brand guidelines
+
+## What this produces
+
+One markdown document: the method below, applied to the subject the
+caller names. The knowledge lives in `assets/guide.md` beside this
+file; the handler substitutes the subject and context and nothing
+else. Data, never code.

distinct_skills/skills/brand-guidelines/assets/guide.md

@@ -0,0 +1,17 @@
+# Brand application: {{subject}}
+
+{{context}}
+
+## Method — adapted from Anthropic's brand-guidelines skill
+
+1. **Palette.** Name the core colours with hex values and one line each on
+   where they belong (background, text, accent, warning). If the brand names
+   no palette, propose one and mark it proposed.
+2. **Typography.** One heading face, one body face, and the fallback stack.
+   State where each is used and the smallest size allowed.
+3. **Voice.** Three adjectives the writing should earn, with one sentence of
+   what each rules out.
+4. **Usage rules.** The five rules that stop the brand drifting: contrast
+   minimums, logo clearance, what never sits on what.
+5. **Applied to the subject.** For the subject named above, list the exact
+   colours, faces and rules that apply, ready to hand to whoever builds it.

distinct_skills/skills/brand-guidelines/tool.json

@@ -0,0 +1,28 @@
+{
+  "version": "1",
+  "handler": "tailored_guide",
+  "input_schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "subject": {
+        "type": "string",
+        "maxLength": 200,
+        "description": "what the guide should be applied to, in a few words"
+      },
+      "context": {
+        "type": "string",
+        "maxLength": 4000,
+        "description": "anything already known: audience, constraints, drafts, goals"
+      },
+      "filename": {
+        "type": "string",
+        "maxLength": 80,
+        "description": "optional file name for the result"
+      }
+    },
+    "required": [
+      "subject"
+    ]
+  }
+}

distinct_skills/skills/canvas-design/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: canvas-design
+description: "Plan a poster or static visual design: philosophy, composition, palette and type, delivered as a design document. Arguments: subject (what the piece is for), context (format, audience, mood, copy) and an optional filename. Adapted from Anthropic's canvas-design skill."
+license: Apache-2.0. Adapted for distinct from the Anthropic skills repository.
+source: https://github.com/anthropics/skills
+---
+
+# Canvas design
+
+## What this produces
+
+One markdown document: the method below, applied to the subject the
+caller names. The knowledge lives in `assets/guide.md` beside this
+file; the handler substitutes the subject and context and nothing
+else. Data, never code.

distinct_skills/skills/canvas-design/assets/guide.md

@@ -0,0 +1,24 @@
+# Design plan: {{subject}}
+
+{{context}}
+
+## Method — adapted from Anthropic's canvas-design skill
+
+1. **A visual philosophy in three sentences.** What the piece believes —
+   restraint, tension, warmth — written before any element is placed. If a
+   choice cannot be defended from these sentences, it goes.
+2. **One focal point.** Decide what the eye lands on first and make every
+   other element quieter than it. Two focal points are none.
+3. **Grid and margins.** Choose the canvas size, a simple grid, and margins
+   generous enough to be a design element themselves.
+4. **Palette of few.** Two or three colours plus a neutral. Name the exact
+   values and what each is for.
+5. **Type as hierarchy.** One display face, one text face, three sizes.
+   The headline earns its size; everything else steps down.
+6. **The subtle reference.** One quiet nod to the subject — a shape, a
+   texture, an angle — that rewards a second look without shouting.
+
+## Produce
+
+Write the philosophy and then the concrete spec: canvas, grid, palette,
+faces, sizes, and the placement of each element, ready to execute.