tribunal-kit 9.2.3 → 9.2.4

package/.agent/skills/huggingface-zerogpu/references/concurrency.md

@@ -0,0 +1,79 @@
+# Concurrency Safety
+
+Gradio handlers run **in parallel by default on ZeroGPU**. Code that works fine in single-user testing can silently corrupt or leak data in production. Always assume handlers execute concurrently.
+
+## No mutable global state
+
+Per-request or per-user data must not live in module-level mutable variables. Concurrent requests will overwrite each other.
+
+```python
+# BAD — concurrent requests overwrite each other
+results = {}
+
+def process(text):
+    results["output"] = expensive_compute(text)  # race condition
+    return results["output"]
+```
+
+```python
+# GOOD — pure function, no shared mutable state
+def process(text):
+    return expensive_compute(text)
+```
+
+For state that must persist within a single user session, use `gr.State`:
+
+```python
+with gr.Blocks() as demo:
+    history = gr.State(value=[])
+
+    def add_message(msg, hist):
+        hist.append(msg)
+        return hist, hist
+
+    btn.click(fn=add_message, inputs=[msg, history], outputs=[chatbot, history])
+```
+
+Note that on ZeroGPU, `gr.State` is pickled across the worker boundary on every yield — see "Process Isolation and Pickle" in SKILL.md for the implications.
+
+## No fixed file paths for outputs
+
+Hardcoded output filenames cause concurrent requests to overwrite each other's files. This corrupts outputs and, worse, can leak one user's data to another.
+
+```python
+# BAD — concurrent calls clobber the same file
+def generate_image(prompt):
+    image = pipe(prompt).images[0]
+    image.save("output.png")
+    return "output.png"
+```
+
+```python
+# GOOD — unique path per invocation
+import tempfile
+
+def generate_image(prompt):
+    image = pipe(prompt).images[0]
+    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
+        image.save(f.name)
+        return f.name
+```
+
+The same applies to any intermediate files (audio, video, CSV exports). Always generate a unique path per invocation.
+
+## Read-only globals are safe
+
+Model objects, tokenizers, and configs loaded once at startup and only read during requests are safe and encouraged. This is the standard ZeroGPU pattern: load at module scope, read inside `@spaces.GPU` handlers.
+
+```python
+# SAFE — loaded once at module scope, read-only during requests
+model = load_model().to("cuda")
+tokenizer = load_tokenizer()
+
+@spaces.GPU
+def predict(text):
+    tokens = tokenizer(text, return_tensors="pt").to("cuda")
+    return model.generate(**tokens)
+```
+
+The "no mutable global state" rule targets *writes* from handlers, not reads. A handler that only reads from a global is concurrency-safe.

package/.agent/skills/huggingface-zerogpu/references/cuda-and-deps.md

@@ -0,0 +1,66 @@
+# CUDA Dependencies on ZeroGPU
+
+Detailed guidance for installing CUDA-dependent packages on ZeroGPU. SKILL.md establishes the bottom line — wheels are the recommended path because the ZeroGPU build phase has no `nvcc`. This document covers wheel filename tag reading, the kernels-community fallback, and torch-family side-car drift.
+
+## When no wheel is available on PyPI
+
+Common workarounds, in preference order:
+
+1. **Pre-built wheel via direct URL.** For `flash-attn`, the upstream project ships a fairly complete matrix at https://github.com/Dao-AILab/flash-attention/releases — check there first and pin the matching wheel URL.
+2. **Build the wheel yourself and host it** (e.g. on a public HF Hub repo) when no upstream wheel matches the Space environment.
+3. **Use a kernels-community kernel** (see below) — handles ABI matching for you, no version pinning needed.
+
+## Reading a CUDA wheel filename
+
+A wheel filename like
+
+```
+flash_attn-2.8.0.post2+cu12torch2.8cxx11abiFALSE-cp312-cp312-linux_x86_64.whl
+```
+
+encodes four build-time choices:
+
+| Tag | Meaning |
+|-----|---------|
+| `cu12` | CUDA major version |
+| `torch2.8` | torch major.minor the wheel was compiled against |
+| `cxx11abiFALSE` | C++ stdlib ABI choice (`TRUE` or `FALSE`) |
+| `cp312-cp312` | CPython version (3.12) |
+
+The wheel's compiled C-extension will `ImportError` on ABI/symbol mismatches if any of these drift at install time.
+
+If you hand pip a wheel URL without pinning the surrounding environment, pip may resolve `torch` to a version different from the wheel's build target, and the Space will fail on first import. Therefore:
+
+- Pin `torch==X.Y.Z` in `requirements.txt` to match the wheel's `torch2.X` tag.
+- Set `python_version:` in the Space frontmatter to match the `cp3XX` tag.
+- Check the runtime's cxx11-ABI choice against the wheel; if unsure, try the opposite ABI wheel.
+
+## Prefer kernels-community when unsure
+
+If you are not sure about the ZeroGPU runtime's torch / Python / ABI combination, prefer a [kernels-community](https://huggingface.co/kernels-community) kernel (e.g. `kernels-community/flash-attn2`) instead of a raw wheel URL. The kernels runtime handles ABI matching on your behalf, so no version pinning is required in your Space.
+
+## torch-family side-car drift
+
+`torchvision`, `torchaudio`, `torchcodec`, and similar side-car packages are built against a specific `torch` major.minor (and CUDA major). On ZeroGPU, the runtime's supported `torch` list lags behind PyPI, so projects often pin a non-latest `torch` — and a bare `uv add <side-car>` can silently resolve to a newer release that targets a different `torch` / CUDA, producing ABI/import failures even though `uv lock` succeeded without warnings.
+
+Concretely observed (2026-04) with `torch==2.9.1` pinned:
+
+- `torchaudio` resolves to `2.11.0`, which targets torch 2.11 / CUDA 13. The `2.11.0` release **dropped the `Requires-Dist: torch==X.Y.Z` line** that every earlier release had, so uv sees no constraint and picks it.
+- `torchcodec` resolves to a release targeting torch 2.11. No torchcodec release on PyPI declares a `torch` dependency at all; the compatibility table lives only in the project README.
+- `torchvision` happens to resolve correctly because torchvision still declares `Requires-Dist: torch==X.Y.Z`. Which side-cars are affected changes over time — treat every torch-family package as suspect, not just these.
+
+### Verify at add/upgrade time
+
+After any `uv add <torch-side-car>` or `uv lock --upgrade`, verify the resolved version targets the same `torch` major.minor as pinned. Two-step fallback because PyPI metadata is not always sufficient:
+
+1. Query PyPI for the resolved version's `requires_dist`:
+   ```bash
+   curl -s https://pypi.org/pypi/<pkg>/<version>/json \
+     | python3 -c "import json,sys,re; rd=json.load(sys.stdin)['info'].get('requires_dist') or []; print('\n'.join(x for x in rd if re.match(r'^torch(?![a-z])', x)) or '(no torch constraint declared)')"
+   ```
+   If a `torch==X.Y.Z` line appears and matches the pinned torch, good. If it appears and does NOT match, the side-car is wrong — pin it down explicitly.
+2. If the query prints `(no torch constraint declared)`, PyPI metadata is silent and cannot be trusted. Fall back to the project's own compatibility table (GitHub README / docs site) — torchcodec, for example, maintains one at https://github.com/pytorch/torchcodec. Pick the side-car version the table maps to the pinned torch major.minor, and pin it explicitly.
+
+### Preventive pin
+
+Once the correct side-car version is known, pin it in `pyproject.toml` alongside torch so uv cannot drift on future `uv lock --upgrade`. The side-car version numbers for a given torch major.minor change each release; always re-verify, do not copy a mapping from an older project.

package/.agent/skills/huggingface-zerogpu/references/how-quota-works.md

@@ -0,0 +1,74 @@
+# How ZeroGPU duration and quota are checked
+
+Mechanism for `duration` validation and quota pre-checks. Useful when choosing `duration` values, debugging `illegal duration` vs `quota exceeded` errors, and understanding why the default 60s is pessimistic for short tasks.
+
+For per-tier numerical thresholds (free vs Pro vs Team vs Enterprise quota minutes), the daily quota window length, runs-per-day limits, and pay-as-you-go pricing, see [the ZeroGPU docs](https://huggingface.co/docs/hub/spaces-zerogpu) — those values change over time and are deliberately kept out of this skill.
+
+## What `duration` actually requests
+
+Whatever value is passed to `@spaces.GPU(duration=N)` (or the default 60s when unspecified) becomes the `requested duration` the platform checks against. For `xlarge`, the request is doubled internally:
+
+```
+requested = N * 2 if size == "xlarge" else N
+```
+
+So `@spaces.GPU(duration=60, size="xlarge")` is internally a 120-second request — both for the tier-max check and the quota pre-check below.
+
+## Two distinct error modes
+
+Two failure messages can come back from the scheduler before the call runs:
+
+| Error | Trigger | What helps |
+|---|---|---|
+| **`ZeroGPU illegal duration`** | `requested duration > visitor's tier per-call cap` | Lower `duration`. Sign in / upgrade tier. **Waiting does not help.** |
+| **`ZeroGPU quota exceeded`** | `remaining quota < requested duration`, OR runs-per-day cap reached | Wait for the quota window to reset. For Pro / Team / Enterprise, pay-as-you-go credits cover the overflow. |
+
+The error wording for `quota exceeded` includes the explicit numbers, e.g.:
+
+```
+You have exceeded your Pro ZeroGPU quota
+(60s requested vs. 30s left). Try again in 1:23:45.
+```
+
+The comparison is **`requested` vs `remaining`** — not `actual run time` vs `remaining`. A 10-second task left at the default 60s requests 60s of quota; once `remaining < 60s` the call fails even though the actual work would have fit.
+
+## Why the default 60s is pessimistic for short tasks
+
+`DEFAULT_SCHEDULE_DURATION` in the `spaces` package is **60 seconds**. So an undecorated `@spaces.GPU` (or `@spaces.GPU()` with no `duration=`) requests 60s of quota.
+
+For a task that actually takes ~10 seconds:
+
+- The user's 60s quota gets reserved up front.
+- Once their remaining quota drops below 60s, your Space fails for them — even though they could have run many more 10s tasks if the request matched reality.
+- Your call also ranks lower in the queue than equivalent calls declaring smaller durations.
+
+The fix is to declare the realistic duration explicitly:
+
+```python
+@spaces.GPU(duration=15)
+def fast_task(...):
+    ...
+```
+
+For workloads where runtime depends on inputs, use a callable (per-request estimator):
+
+```python
+def estimate_duration(prompt, steps):
+    return int(steps * 3.5)
+
+@spaces.GPU(duration=estimate_duration)
+def variable_task(prompt, steps):
+    ...
+```
+
+This preserves quota for light inputs and reserves more only when needed.
+
+## Quota window: 24h fixed from first use
+
+The quota window's TTL is set when the first call of a fresh window lands and counts down unconditionally — it is not a sliding window, not a calendar-day reset, and not extended by subsequent use. A user who runs a call at 14:00 sees their next reset at 14:00 the following day, regardless of how heavily or lightly they use the Space in between.
+
+For exact tier thresholds, runs-per-day caps, and pay-as-you-go billing rates, see the [ZeroGPU docs](https://huggingface.co/docs/hub/spaces-zerogpu).
+
+## Queue priority
+
+The queue is **node-level** — requests from every Space scheduled on the same physical node compete for that node's GPU slots. Among queued requests, **shorter declared `duration` ranks higher**. So tight per-request `duration` estimates serve two goals at once: they preserve the user's quota and move the request up the queue.

package/.agent/skills/huggingface-zerogpu/references/how-zerogpu-works.md

@@ -0,0 +1,50 @@
+# How ZeroGPU works (mechanism)
+
+Conceptual lifecycle of model weights, processes, and worker reuse on ZeroGPU. Useful when reasoning about cold-starts, why module-scope warmup does not carry over to requests, why returning CUDA tensors hangs the call, or why `gr.State` mutations do not persist across the worker boundary.
+
+For numerical limits (concurrency slots per Space, queue priority by tier, etc.), see [the ZeroGPU docs](https://huggingface.co/docs/hub/spaces-zerogpu) — those values change over time and are deliberately kept out of this skill.
+
+## Two processes, two lifetimes
+
+A ZeroGPU Space runs as **two separate processes**:
+
+- **Main web process** — long-lived. Imports `app.py`, launches Gradio, stays up for the life of the Space. Holds no VRAM and, after the startup "pack" step, holds no model weights in RAM either.
+- **GPU worker processes** — short-lived. Forked per `@spaces.GPU` request (or reused if warm). Run the task and are eventually killed by the ZeroGPU scheduler when another Space needs the GPU slot. Your Space code never kills its own worker.
+
+## Module-scope `.to("cuda")` is captured to disk
+
+When `import spaces` is active, `model.to("cuda")` at module scope is intercepted. The call is rewritten to `to("cpu")`, so the tensor data physically lives in main process RAM at this point. A "fake" CUDA-presenting tensor is registered alongside the original CPU tensor.
+
+At a startup "pack" step, the backend writes those original CPU tensors to disk via direct I/O (`O_DIRECT`), then frees the corresponding RAM. After pack, the main process holds no model weights anywhere — the data lives only on disk.
+
+This is why module-scope `pipe(...)` / `model.generate(...)` / `model(...)` calls do not run on a real GPU: there is no GPU attached to the main process, and after pack there are no weights to compute against either. Such calls either fail or silently fall back to CPU on the fake tensors.
+
+## Worker init: disk → pinned memory → VRAM
+
+When a `@spaces.GPU` call lands, the scheduler routes it to a worker:
+
+1. **Cold worker** — forked from the main process. The patched torch is unpatched, real CUDA is initialized, and weights are read from the disk offload directory into pinned host memory and streamed onto VRAM through a double-buffered pipeline (essentially `pin_memory().cuda(non_blocking=True)` per batch). This is the "cold-start" cost.
+2. **Warm worker (reused)** — an alive worker bound to the same GPU slot is reused if the scheduler reports it idle. Init is skipped; weights stay on VRAM from the previous call. Subsequent requests within a burst hit this path.
+
+A warm worker is eventually killed by the scheduler when another Space needs the GPU slot. The next call after that point pays the disk → VRAM cost again. Occasional cold-starts on a low-traffic Space are normal.
+
+## Why module-scope warmup does not help
+
+A common instinct is to call `pipe("warmup")` at module scope to "prepare" the model. This does not work on ZeroGPU:
+
+- At module scope, no real GPU is attached. The fake CUDA tensors do not have data after pack, so `pipe(...)` either fails or silently runs on something other than a real GPU.
+- Even if you wrap the warmup in `@spaces.GPU`, the worker that ran the warmup will eventually be killed before the first real user request lands — leaving them with a cold worker anyway.
+
+The right answer is to load eagerly at module scope (`pipe = pipeline(..., device="cuda")`) and accept that the first user request after a quiet period will be a cold worker. Cold-start is fast on ZeroGPU because of the pinned-memory disk pipeline; it is not free, but it is not "minutes of model download" either.
+
+## Why returning CUDA tensors hangs the call
+
+The main process never has a CUDA context — it has no GPU attached and its torch never initialized CUDA. When a worker returns a CUDA tensor, unpickling it in the main process triggers `torch.cuda._lazy_init()`, which would attempt to initialize CUDA in the main process. ZeroGPU blocks this, and the call hangs.
+
+The fix is purely client-side: convert to CPU before returning (`.cpu()`, `.cpu().numpy()`, etc.). See "Process Isolation and Pickle" in SKILL.md.
+
+## Why `gr.State` does not share by reference across the boundary
+
+Worker processes are forked separately and exchange data with the main process via pickle. `gr.State` values cross this boundary on every yield, so mutations inside a `@spaces.GPU` generator are local to the worker until the mutated state is explicitly yielded back. The main process gets a fresh deserialized copy each time — `id()` differs, in-place mutations are invisible across the boundary.
+
+See "Process Isolation and Pickle" in SKILL.md for the practical implications and `references/concurrency.md` for related parallel-handler concerns.

package/.agent/skills/human-gate-negotiation/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: human-gate-negotiation
+description: "Use when preparing concise impact reports before approval requests for high-risk, non-idempotent actions."
+version: 1.0.0
+last-updated: 2026-09-25
+skills:
+  - fabel-protocol
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/harness_manager.js
+---
+
+# Human Gate Negotiation
+
+## Context
+When an agent attempts a high-risk operation (deploying to production, running `rm -rf`, running a database migration), it MUST be paused, and explicit approval must be sought from the Human Gate. 
+
+## The Impact Report Format
+Never just ask "Can I run this?". You must provide a structured report outlining the consequences of the action so the human can make an informed decision.
+
+**Mandatory Report Structure:**
+1. **Proposed Action**: The exact command or script to be executed.
+2. **Purpose**: Why this is necessary.
+3. **Files/Resources Affected**: Which systems will be mutated.
+4. **Expected Side Effects**: Downtime, data loss, irreversible state changes.
+5. **Verification Status**: Proof that tests passed before reaching this gate.
+6. **Rollback Instructions**: How to undo this action if it fails in production.
+
+## Agent Behavior
+Once the report is generated, the agent must enter a sleep/wait state and CANNOT proceed until the human explicitly provides an approval token.

package/.agent/skills/intelligent-routing/SKILL.md

@@ -49,10 +49,10 @@ scripts-binding:
                     └────┬─────┘  Load co-requires automatically
                          │
                     ┌────▼─────┐
-                    │ PHASE 3  │  Agent Activation
-                    │ Dispatch │  Route to specialist agent
-                    └──────────┘  Announce & load skills
-```
+                    │ PHASE 3  │  Agent Activation & Dynamic Topologies
+                    │ Dispatch │  Route to dynamic micro-teams (Team Mode)
+                    └──────────┘  based on AST impact.
+                                  (e.g., Frontend + Security parallel wave)
 
 ---
 
@@ -196,3 +196,9 @@ When keywords belong to multiple domains, use these explicit rules:
 ## 6. Regenerating the Index
 
 When new skills are added or existing frontmatter is modified, the index regenerates automatically.
+
+
+## 7. Dynamic Sub-Agent Delegation (Team Mode)
+
+The router MUST NOT dump files into a static 3-wave pipeline. Instead, it must selectively route tasks to micro-teams (Team Mode) based on file impact and topological graph dependencies. 
+- Example: If the AST diff impacts `db/schema.prisma` and `src/components/User.tsx`, the router spawns a `database-architect` sub-agent and a `frontend-specialist` sub-agent in a parallel DAG wave, instead of running the entire 28-reviewer gauntlet on both files.

package/.agent/skills/semantic-filesystem-navigation/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: semantic-filesystem-navigation
+description: "Use when navigating complex codebases, preferring exact file operations but falling back to semantic vector search when paths are unknown."
+version: 1.0.0
+last-updated: 2026-09-25
+skills:
+  - context-engineering-pro
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/context_compiler.js
+---
+
+# Semantic Filesystem Navigation
+
+## The Rule of Exact Paths
+When an agent knows the exact file path (e.g., `src/index.js`), it MUST use standard file read operations to fetch it. Exact lookups are O(1), cheap, and guarantee zero hallucination.
+
+## Semantic Fallback
+When an agent is asked a fuzzy question (e.g., "Where is the user authentication middleware defined?"), it should invoke the Semantic Search tools. 
+The system will run a local embedding match against the `routing_index.json` or pre-compiled TF-IDF maps to locate the file.
+
+## Guardrails
+- **Do not guess file names**: Never write `fs.readFileSync('auth.js')` unless you have verified `auth.js` exists in the current working directory.
+- **Limit Context Hits**: Semantic search should return file *paths*, not full file *contents*, to avoid context window explosion. The agent must then selectively `view_file` the most relevant hit.

package/.agent/skills/session-log-interrogation/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: session-log-interrogation
+description: "Use when teaching selective access to session history to prevent context window bloat during long-running sessions."
+version: 1.0.0
+last-updated: 2026-09-25
+skills:
+  - context-engineering-pro
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/session_logger.js
+---
+
+# Session Log Interrogation
+
+## The Context Problem
+Long-running agent workflows generate thousands of events (Syscalls, Model turns, Tool Responses). Injecting the full session history into a prompt degrades reasoning, wastes tokens, and eventually hits hard limits.
+
+## The Solution: Selective Interrogation
+The agent must filter and request specific event ranges rather than loading the entire file.
+
+## Tactics
+1. **Time-Bounded Queries**: Request events only since the last major Checkpoint (e.g., "Give me all events since Wave 2 started").
+2. **Error-Focused Scans**: Query specifically for `ToolFailed` or `SessionFailed` events to understand what went wrong, ignoring the happy-path `ToolCompleted` events.
+3. **Provenance Validation**: When referencing past actions, cite the exact `eventId`.
+4. **Context Budgets**: Never load more than 50 events into context at once. If the query yields more, aggregate them into a summary locally before passing to the model.
+
+## Anti-Patterns
+- ❌ Reading the raw `.agent_session.json` line-by-line using `cat`.
+- ✅ Using the `session_logger.js` or `harness_manager.js` to fetch structured, filtered logs.

package/.agent/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: subagent-driven-development
+description: "Use when decomposing tasks, delegating to subagents, executing code in isolation, and reviewing AI-generated output. Integrates tightly with Tribunal OS governance."
+version: 1.0.0
+last-updated: 2026-09-25
+skills:
+  - tdd-workflow
+  - verification-before-completion
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/swarm_dispatcher.js
+---
+
+# Subagent-Driven Development (SDD)
+
+## Core Philosophy
+Monolithic tasks must be broken down into atomic, testable units, delegated to specialized agents, and executed in bounded isolation. No single agent should both write code and approve it for production.
+
+## The SDD Lifecycle
+1. **Decomposition**: Break the Epic down into sub-tasks (Waves). No sub-task should touch more than 5 files.
+2. **Delegation**: Assign each sub-task to the agent with the most appropriate profile (e.g., `frontend-specialist`, `database-architect`).
+3. **Execution (Hands)**: The subagent implements the required changes in a localized context.
+4. **Verification**: The subagent runs tests. If tests fail, it iterates.
+5. **Review (Tribunal)**: The code changes are subjected to parallel static analysis reviewers (`/tribunal-full`).
+6. **Handoff**: The subagent reports back to the Orchestrator with concrete proof of verification.
+
+## Mandatory Guardrails
+- **Zero-Trust Delegation**: Never assume a subagent succeeded just because it didn't throw an error. Demand terminal output proof.
+- **Context Isolation**: Do NOT pass the entire conversation history to a subagent. Pass only the required `.md` instructions and relevant file paths.
+
+## Failure Handling
+If a subagent fails 3 times, the Orchestrator must abort the wave, clean up any uncommitted side-effects, and flag the issue for the Human Gate.

package/.agent/skills/systematic-debugging/SKILL.md

@@ -122,3 +122,8 @@ Do not skim. Stack traces tell the exact sequence of destruction.
 1. **Top line:** The final fatal blow (e.g., `TypeError: Cannot read properties of undefined (reading 'map')`).
 2. **First Application Function:** Scroll down past `node_modules` and framework internals. Find the absolute top-most function call that YOU wrote (e.g., `at UserList (src/components/UserList.tsx:45)`).
 3. **The Parameter Conclusion:** Therefore, line 45 invoked `.map` on a variable that was `undefined`. Why did the parent layer pass `undefined` instead of `[]`?
+
+
+## Integration with Durable Session Log
+
+When debugging fails, the agent MUST read the `.agent/.tribunal/session.jsonl` durable log to understand exactly where the previous wave crashed. Do not guess; read the event trace to see the exact sequence of tool calls and errors that led to the crash. You can grep this file or parse it to extract the latest `ErrorEncountered` or failed `ToolCompleted` events.

package/.agent/skills/train-sentence-transformers/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: train-sentence-transformers
+description: Train or fine-tune sentence-transformers models across `SentenceTransformer` (bi-encoder, dense or static embedding model for retrieval, similarity, clustering, classification, paraphrase mining, dedup, multimodal), `CrossEncoder` (reranker, pair scoring for two-stage retrieval / pair classification), `SparseEncoder` (SPLADE, sparse embedding model for learned-sparse retrieval), and `MultiVectorEncoder` (ColBERT / late-interaction, per-token embeddings scored with MaxSim). Covers loss selection, hard-negative mining, evaluators, distillation, LoRA, Matryoshka, and Hugging Face Hub publishing. Use for any sentence-transformers training task.
+---
+
+# Train a sentence-transformers Model
+
+**This SKILL.md is a router, not a manual.** It tells you which references and example scripts to load for your task. The actual content (recommended losses, evaluators, training-script structure, model selection, training-arg knobs, troubleshooting) lives in `references/` and `scripts/`.
+
+**Do not synthesize a training script from this file alone.** Open the per-type production template (`scripts/train_<type>_example.py`) and copy it as your starting point. The templates contain load-bearing scaffolding (autocast helper, model-card class, logger silencing list, `force=True`, `seed`, TF32, version-compatible imports, named-evaluator metric handling) that prior agent runs have repeatedly missed when rolling their own from a synthesized snippet.
+
+## 1. Identify the model type
+
+| Tag | Class | What it does | When to pick |
+|---|---|---|---|
+| **[SentenceTransformer]** | `SentenceTransformer` (bi-encoder) | Maps each input to a fixed-dim dense vector | Retrieval, similarity, clustering, classification, paraphrase mining, dedup |
+| **[CrossEncoder]** | `CrossEncoder` (reranker) | Scores `(query, passage)` pairs jointly | Two-stage retrieval (rerank top-100 from bi-encoder), pair classification |
+| **[SparseEncoder]** | `SparseEncoder` (SPLADE) | Sparse vectors over the vocabulary | Learned-sparse retrieval, inverted-index backends (Elasticsearch / OpenSearch / Lucene) |
+| **[MultiVectorEncoder]** | `MultiVectorEncoder` (ColBERT) | One embedding per token, scored with MaxSim | Late-interaction retrieval, recall gains over bi-encoders at higher storage cost, multimodal (ColPali / ColQwen2) |
+
+Tiebreakers when the request is ambiguous: "embedding model" / "vector search" / "similarity" → **[SentenceTransformer]**. "rerank" / "ranker" / "two-stage" → **[CrossEncoder]**. "SPLADE" / "sparse" / "inverted index" → **[SparseEncoder]**. "ColBERT" / "late interaction" / "multi-vector" / "MaxSim" / "ColPali" / "ColQwen" → **[MultiVectorEncoder]**. If still unclear, ask.
+
+## 2. Required reading
+
+**Read these in full before writing any code. Do not triage by perceived relevance.**
+
+### Per-type: always required
+
+**[SentenceTransformer]**
+- `references/losses_sentence_transformer.md`: loss-to-data-shape mapping, `BatchSamplers.NO_DUPLICATES` requirement for MNRL-family, `Cached*` ↔ `gradient_checkpointing` incompatibility.
+- `references/evaluators_sentence_transformer.md`: evaluator-to-task mapping, `metric_for_best_model` key construction (named vs unnamed), per-evaluator `primary_metric` values.
+- `references/model_architectures.md`: encoder vs decoder vs static vs Router pipelines, pooling rules (mean / cls / lasttoken), auto-mean-pooling behavior for fresh-start MLM bases.
+- `scripts/train_sentence_transformer_example.py`: production template. Copy this as your starting point.
+
+**[CrossEncoder]**
+- `references/losses_cross_encoder.md`: pointwise / pairwise / listwise / distillation, `pos_weight` derivation, `activation_fn=Identity()` mandatory for non-BCE losses (silent eval-rank collapse otherwise).
+- `references/evaluators_cross_encoder.md`: `CrossEncoderRerankingEvaluator` recipe, named-evaluator key format `eval_{name}_{primary_metric}`.
+- `scripts/train_cross_encoder_example.py`: production template. Copy this as your starting point.
+
+**[SparseEncoder]**
+- `references/losses_sparse_encoder.md`: `SpladeLoss` wrapper requirement, FLOPS regularizer weights, smoke-test active-dim ramp behavior.
+- `references/evaluators_sparse_encoder.md`: `SparseNanoBEIREvaluator` (English-only) and the in-domain alternative, `eval_{name}_{primary_metric}` key format.
+- `scripts/train_sparse_encoder_example.py`: production template. Copy this as your starting point.
+
+**[MultiVectorEncoder]**
+- `references/losses_multi_vector_encoder.md`: MaxSim scoring, scale choice per scoring mode (`scale=1.0` for MaxSim, roughly the average query length for MeanMaxSim), MNRL / CachedMNRL / MarginMSE / DistillKLDiv, XTR-vs-ColBERT scoring, CachedMNRL ↔ `gradient_checkpointing` incompatibility.
+- `references/evaluators_multi_vector_encoder.md`: `MultiVectorNanoBEIREvaluator` (English-only) and the in-domain alternative, `eval_NanoBEIR_mean_maxsim_ndcg@10` key format, distillation-eval spearman variant.
+- `scripts/train_multi_vector_encoder_example.py`: production template. Copy this as your starting point.
+
+### Cross-cutting: always required (regardless of task)
+
+- `references/training_args.md`: `TrainingArguments` knobs, precision rules (load fp32 + autocast bf16/fp16, never `torch_dtype=bfloat16`), `warmup_steps` (float) vs deprecated `warmup_ratio`, `save_steps` must be a multiple of `eval_steps` for `load_best_model_at_end`, schedulers, HPO, tracker, resume, hub-push variants.
+- `references/dataset_formats.md`: column-matching rules (label name auto-detection, column-order-not-name), reshaping recipes, hard-negative mining options.
+- `references/base_model_selection.md`: discovery commands, per-type model namespaces, ModernBERT-family `max_seq_length=8192` trap, `datasets >= 4` script-loader rejection, non-English starting-point shortcuts.
+- `references/troubleshooting.md`: symptom-indexed failure recipes. Skim the section headings on every run, even a healthy one. The "Metrics don't improve" and "Hub push fails" entries cover bugs that bite frequently and are cheaper to recognize before they fire than to debug after.
+
+### Cross-cutting: load when applicable
+
+- `references/hardware_guide.md`: VRAM sizing, multi-GPU, FSDP / DeepSpeed, HF Jobs flavors. Required for >24GB models, multi-GPU, or HF Jobs runs.
+- `references/hf_jobs_execution.md`: required when running on HF Jobs.
+- `references/prompts_and_instructions.md`: required when using prompt-tuned bases (E5, BGE, GTE, Qwen3-Embedding, Instructor, Nomic, etc.) or adding `query: ` / `passage: ` style prefixes.
+
+### Variant scripts (open when the task matches)
+- **[SentenceTransformer]** `scripts/train_sentence_transformer_<matryoshka|multi_dataset|with_lora|distillation|make_multilingual|static_embedding>_example.py`.
+- **[CrossEncoder]** `scripts/train_cross_encoder_<distillation|listwise>_example.py`.
+- **[SparseEncoder]** `scripts/train_sparse_encoder_distillation_example.py`.
+- Hard-negative mining CLI: `scripts/mine_hard_negatives.py`.
+
+## 3. Defaults
+
+Override only if the user specifies otherwise:
+- **Local execution.** Pitch HF Jobs only if local hardware can't fit the job.
+- **Single run.** After it completes, propose experimentation if the user would benefit (weak/marginal verdict, "see how high you can push it" framing, etc.). Iteration rules in `references/training_args.md` (Experimentation section).
+- **Public Hub push at end-of-run, wrapped in try-except.** On HF Jobs (ephemeral env) ALSO enable in-trainer push (`push_to_hub=True` + `hub_strategy="every_save"`). Details in `references/hf_jobs_execution.md`.
+
+## 4. Constraints the produced script must satisfy
+
+These are non-negotiable contracts. Implementation lives in the production templates and references. Do not reinvent.
+
+- Capture the pre-training evaluator score as `baseline_eval` **before** `trainer.train()`.
+- Emit a single end-of-run line: `VERDICT: WIN|MARGINAL|REGRESSION | score=... | baseline=... | delta=...`. A monitor scrapes for this.
+- Silence `httpx`, `httpcore`, `huggingface_hub`, `urllib3`, `filelock`, `fsspec` to WARNING (otherwise HF download URLs flood the agent's context).
+- Tee logs to `logs/{RUN_NAME}.log`.
+- End with `model.push_to_hub(...)` wrapped in `try/except`.
+- Smoke-test before any long run (`max_steps=1` + tiny dataset slice). The production templates show one common pattern (`SMOKE_TEST` env var).
+- **[CrossEncoder]** Include `EarlyStoppingCallback(patience>=3)`. CE rerankers often peak mid-training and regress.
+- **[SparseEncoder]** Log `query_active_dims` / `corpus_active_dims` on the verdict line. High nDCG with collapsed sparsity is not a win. The keys come back name-prefixed (e.g. `..._query_active_dims`). Use suffix matching to pluck them. See the SPARSE production template for the exact pattern.
+- **[MultiVectorEncoder]** Match `scale` to the scoring mode on any MNRL-family loss: near `1.0` for unnormalized MaxSim (do not copy `scale=20.0` from bi-encoder MNRL), roughly the average query length with length-normalized MeanMaxSim, since each score is divided by its query's token count. `XTRScores` is a train-only `similarity_fct`: the evaluators reject it, so evaluation always scores with MaxSim, including for XTR-trained models.
+
+## 5. Workflow
+
+1. Identify the model type (§1). Ask if ambiguous.
+2. Load the §2 required-reading files for that type.
+3. Open `scripts/train_<type>_example.py` and copy it as your starting point.
+4. Replace `MODEL_NAME`, `DATASET_NAME`, `RUN_NAME`, the loss, and the evaluator with the user's task. Cross-check loss/data-shape match against `references/losses_<type>.md`. Cross-check the `metric_for_best_model` key against `references/evaluators_<type>.md` (named evaluators format the key as `eval_{name}_{primary_metric}`).
+5. Smoke-test (`max_steps=1`).
+6. Run.
+7. After the run, append to `logs/experiments.md` and propose iteration if the verdict is weak/marginal.
+
+## Prerequisites
+
+```bash
+pip install "sentence-transformers[train]>=5.0"        # add [train,image] / [audio] / [video] for [SentenceTransformer] multimodal
+                                                       # [MultiVectorEncoder] requires >=6.0
+pip install trackio                                    # optional tracker (or wandb / tensorboard / mlflow)
+hf auth login                                          # or set HF_TOKEN with write scope (for Hub push)
+```
+
+GPU strongly recommended. CPU works only for demos and `[SentenceTransformer]` `StaticEmbedding`.

package/.agent/skills/train-sentence-transformers/references/base_model_selection.md

@@ -0,0 +1,79 @@
+# Base Model Selection
+
+Leaderboards rotate every few months. Don't trust any hardcoded "best" pick. Discover current options live. Run **both** sort orders since most-downloaded surfaces proven options and trending surfaces recent SOTA that may not have download volume yet.
+
+## Discovery commands
+
+**[BI]**:
+```bash
+hf models list --filter sentence-transformers --sort downloads --limit 20
+hf models list --filter sentence-transformers --sort trending  --limit 20
+```
+
+**[CE]**:
+```bash
+hf models list --filter sentence-transformers --filter text-ranking --sort downloads --limit 20
+hf models list --filter sentence-transformers --filter text-ranking --sort trending  --limit 20
+```
+
+**[SPARSE]**:
+```bash
+hf models list --filter sentence-transformers --filter sparse-encoder --sort downloads --limit 20
+hf models list --filter sentence-transformers --filter sparse-encoder --sort trending  --limit 20
+```
+
+Optional language narrowing (any type): add `--filter <language-code>`. Not all multilingual models tag each language, so missing matches doesn't mean the model can't handle that language. Re-run without the filter to compare.
+
+```bash
+hf models card <id> --text                        # confirm dimensions, max_seq_length, license, languages
+```
+
+Cross-check the [MTEB leaderboard](https://huggingface.co/spaces/mteb/leaderboard) (pick the relevant tab) before committing to a multi-hour run.
+
+## [BI] Bi-Encoder
+
+Continue from an existing retriever beats fresh-start + 100k-500k pairs. Common namespaces as of 2026-Q2 (verify against discovery commands, since the field rotates):
+
+- **English encoder retrievers**: `sentence-transformers/all-*` (MiniLM-L6-v2, mpnet-base-v2 still the most-downloaded models on the Hub), `BAAI/bge-*-en-v1.5`, `nomic-ai/nomic-embed-text-v1.5`, `mixedbread-ai/mxbai-embed-large-v1`, `Alibaba-NLP/gte-*`, `Snowflake/snowflake-arctic-embed-*`, `jinaai/jina-embeddings-v5-text-small` / `-nano`, `microsoft/harrier-oss-v1-270m` / `-0.6b`.
+- **Multilingual encoder retrievers**: `sentence-transformers/paraphrase-multilingual-*`, `intfloat/multilingual-e5-*`, `ibm-granite/granite-embedding-*-multilingual-r2`, `google/embeddinggemma-300m`, `voyageai/voyage-4-nano`.
+- **Long documents (8k+)**: `nomic-ai/modernbert-embed-*`, `answerdotai/ModernBERT-large`.
+- **Decoder LLM retrievers** (multilingual, **need last-token pooling**): `Qwen/Qwen3-Embedding-*` (0.6B / 4B / 8B), `Qwen/Qwen3-VL-Embedding-*` (multimodal), `codefuse-ai/F2LLM-v2-*`.
+- **Fresh-start English** (≥500k pairs + domain-fit reason): `microsoft/mpnet-base`, `answerdotai/ModernBERT-base`, `google-bert/bert-base-uncased`, `jhu-clsp/ettin-encoder-*` (17m / 32m / 68m / 150m / 400m / 1b, paired ModernBERT encoder family).
+- **Fresh-start multilingual**: `FacebookAI/xlm-roberta-base` (MLM-only, needs contrastive training), `microsoft/mdeberta-v3-base`, `jhu-clsp/mmBERT-base` / `-small`.
+- **CPU / small footprint** (`StaticEmbedding`): `StaticEmbedding(tokenizer, embedding_dim=...)`. **Model size = `vocab_size × dim × 4 bytes`**. Pick a small-vocab tokenizer or you get a giant model: 30k-vocab `bert-base-uncased` × 128 dim ≈ 15 MB, **250k-vocab `paraphrase-multilingual-MiniLM-L12-v2` × 256 dim ≈ 256 MB**. Random init needs 1M+ pairs. Warm-start (`StaticEmbedding.from_distillation(...)`) helps under ~100k pairs.
+
+Architecture variants (encoder / decoder / static / Router), pooling rules, and decoder-vs-encoder setup paths: `model_architectures.md`.
+
+**ModernBERT-family bases default to `max_seq_length=8192`.** That allocates activation memory for 8192-token sequences regardless of your data length and silently drives Windows VRAM into "shared memory" spillover. After loading any ModernBERT / mmBERT / Ettin / gte-modernbert / nomic-modernbert base, **explicitly set `model.max_seq_length = 256` (or 512 for documents)** unless you actually need long context.
+
+## [CE] Cross-Encoder
+
+Continue from an existing reranker beats fresh-start + 100k-500k pairs in most domains. Default to this unless you have a strong reason otherwise. Common namespaces as of 2026-Q2:
+
+- **English encoder rerankers**: `cross-encoder/ms-marco-*`, `BAAI/bge-reranker-*`, `mixedbread-ai/mxbai-rerank-*-v1` / `-v2`, `Alibaba-NLP/gte-reranker-modernbert-*`, `ibm-granite/granite-embedding-reranker-english-*`.
+- **Multilingual encoder rerankers**: `cross-encoder/mmarco-*`, `BAAI/bge-reranker-v2-m3`, `Alibaba-NLP/gte-multilingual-reranker-*`, `ibm-granite/granite-embedding-reranker-multilingual-*`.
+- **Decoder LLM rerankers** (multilingual, `num_labels=1` last-token-style scoring): `Qwen/Qwen3-Reranker-*` (0.6B / 4B / 8B), `Qwen/Qwen3-VL-Reranker-*` (multimodal).
+- **Fresh-start**: `microsoft/MiniLM-L12-H384-uncased`, `answerdotai/ModernBERT-base` / `-large`, `jhu-clsp/ettin-encoder-*`, `FacebookAI/xlm-roberta-base` (multilingual), `microsoft/mdeberta-v3-base` (multilingual), `jhu-clsp/mmBERT-base` / `-small` (multilingual). Pass `num_labels >= 2` for classification cross-encoders.
+
+Encoder-only bases are still the latency-efficient default (bidirectional attention is well-suited to the reranking use case at small parameter counts), but decoder LLM rerankers are now competitive at the top of MTEB Reranking when latency / memory budget allows.
+
+**Minimum dataset:** 500k+ labeled `(query, passage, label)` tuples for production. 10k-100k labeled pairs for continue-training on domain data. Low-resource languages may have less than 10k labeled pairs. In that case, lean on a multilingual base's pretraining and accept a noisier signal.
+
+**"Small" multilingual is ~100M+ params**, not 17M-50M like the English small models. mMiniLMv2-L12-H384 (~117M) is roughly the small-end for usable multilingual rerankers.
+
+## [SPARSE] Sparse Encoder (SPLADE)
+
+SPLADE requires a fill-mask / `AutoModelForMaskedLM`-compatible checkpoint. Encoder-only MLM models work out of the box. **Decoder LLMs do not**.
+
+- **Continue from existing SPLADE (English)**: `naver/splade-*` (the canonical family), `opensearch-project/opensearch-neural-sparse-encoding-*` (incl. `-doc-v2-distill`, `-doc-v3-distill` / `-doc-v3-gte`), `prithivida/Splade_PP_en_v*`, `ibm-granite/granite-embedding-30m-sparse`.
+- **Continue from existing SPLADE (multilingual)**: `opensearch-project/opensearch-neural-sparse-encoding-multilingual-v1`.
+- **Fresh-start English** (≥500k pairs): any encoder with an MLM head (`distilbert/distilbert-base-uncased`, `google-bert/bert-base-uncased`). Pure `AutoModel` checkpoints without MLM won't work. Discover MLM bases: `hf models list --filter fill-mask --sort downloads --limit 20`.
+- **Fresh-start multilingual**: `FacebookAI/xlm-roberta-base` (has MLM head). For other multilingual MLM bases: add `--filter <language-code>`.
+
+**Minimum dataset:** 500k+ triplets (with mined hard negatives) for a competitive SPLADE. 50k+ triplets for domain adaptation on existing SPLADE.
+
+## Cross-cutting tips
+
+- **Non-English retrieval starting points** (when language tag returns 0 results): check `intfloat/multilingual_e5_train_data` for parallel pair data, MIRACL via the `sentence-transformers/miracl` mirror for multilingual retrieval, mMARCO via `unicamp-dl/mmarco` (14 languages, parquet-backed).
+- **Avoid script-based dataset loaders.** `datasets >= 4` rejects them with `RuntimeError: Dataset scripts are no longer supported`. Look for parquet-backed mirrors (e.g. `sentence-transformers/miracl` instead of `miracl/miracl`).
+- **`hf datasets sql` requires DuckDB** (`pip install duckdb`). Without it, fall back to `python -c "from datasets import load_dataset; ds = load_dataset('<id>', ...); print(ds.column_names, ds[0])"`.