opencode-skills-collection 4.0.44 → 4.0.46

package/bundled-skills/unsloth-finetuning/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: unsloth-finetuning
+description: "Fine-tune and post-train LLMs with Unsloth Core on a single consumer GPU: VRAM sizing, LoRA/QLoRA, GRPO/DPO, chat-template correctness, and GGUF export."
+category: ai-ml
+risk: critical
+source: community
+source_repo: unslothai/unsloth
+source_type: community
+date_added: "2026-08-27"
+author: A-ryanVAT-S
+tags: [unsloth, fine-tuning, lora, qlora, grpo, gguf, vram]
+tools: [claude, cursor, gemini]
+license: "Apache-2.0"
+license_source: "https://github.com/unslothai/unsloth/blob/main/LICENSE"
+---
+
+# Unsloth Fine-Tuning
+
+## Overview
+
+Unsloth trains LLMs with custom kernels that cut VRAM use and step time without changing the
+math, which makes single-GPU fine-tuning practical on hardware that would otherwise OOM.
+This skill covers **Unsloth Core** — the Python API — because that is what an agent can drive
+programmatically; the Desktop app and Studio web UI are interactive and out of scope.
+
+The hard parts of an Unsloth run are not the training call. They are sizing the job against
+available VRAM, getting the chat template and loss masking right, and choosing an export
+format the target runtime can actually load. This skill covers those three.
+
+## When to Use This Skill
+
+- Use when fine-tuning an LLM on one GPU and VRAM is the binding constraint.
+- Use when a training run OOMs and needs to be resized rather than rewritten.
+- Use when doing preference or RL post-training (GRPO, DPO) on consumer hardware.
+- Use when a fine-tuned model must be exported to GGUF, vLLM, or merged 16-bit weights.
+- Use when a fine-tune "ran fine" but the model's output format is wrong — usually a chat
+  template or loss-masking bug, not a hyperparameter one.
+
+### Do not use this skill when
+
+- The training is multi-node or large-scale multi-GPU. Use plain TRL with Accelerate/DeepSpeed.
+- The architecture is unsupported by Unsloth. Fall back to TRL; do not force it.
+- The user wants managed cloud training. That is Hugging Face Jobs, not local Unsloth.
+- The user wants the Desktop or Studio GUI. Point them at the installer, not this skill.
+
+## How It Works
+
+### Step 1: Size the run before writing code
+
+VRAM is the constraint that decides everything else. Estimate weights first, then leave room
+for activations and optimizer state:
+
+| Load mode | Weight cost | 8B model | Use when |
+| :--- | :--- | :--- | :--- |
+| `load_in_4bit` (QLoRA) | ~0.55 GB per 1B params | ~4.5 GB | Default. Under 16 GB VRAM. |
+| `load_in_8bit` | ~1.1 GB per 1B params | ~9 GB | Quality-sensitive, 16-24 GB. |
+| `load_in_16bit` | ~2 GB per 1B params | ~16 GB | LoRA at full precision, 24 GB+. |
+| `full_finetuning=True` | ~2 GB weights + ~12 GB optimizer | ~112 GB | Rarely justified. Prefer LoRA. |
+
+Add roughly 2-6 GB for activations, scaling with `max_seq_length` and batch size. Treat these
+as planning figures and confirm against `nvidia-smi` on the first run — they vary by
+architecture, attention implementation and vocabulary size.
+
+If the estimate does not fit, reduce in this order: `max_seq_length`, then batch size (raising
+`gradient_accumulation_steps` to hold the effective batch constant), then LoRA rank, then model
+size. Cutting rank before sequence length usually costs more quality than it saves memory.
+
+### Step 2: Load the model
+
+`import unsloth` must come **before** `transformers`, `trl` or `peft`. Unsloth patches those
+libraries at import time; importing them first silently disables the optimizations.
+
+```python
+import unsloth  # must be first
+from unsloth import FastLanguageModel
+
+model, tokenizer = FastLanguageModel.from_pretrained(
+    model_name = "unsloth/Qwen3-8B",
+    max_seq_length = 2048,
+    load_in_4bit = True,
+    dtype = None,  # auto-detects bf16 where supported
+)
+```
+
+Pick the loader that matches the modality: `FastLanguageModel` for text-only causal LMs,
+`FastVisionModel` for vision-language models, `FastModel` when the modality is decided at runtime.
+
+The `unsloth/` Hub namespace holds pre-quantized copies that download faster and skip a local
+quantization pass. Upstream repos such as `Qwen/` or `meta-llama/` work identically.
+
+### Step 3: Fix the chat template before training
+
+This is the most common silent failure. A run with the wrong template converges cleanly and
+produces a model that ignores its stop tokens or emits prompt scaffolding at inference.
+
+```python
+from unsloth.chat_templates import (
+    get_chat_template,
+    standardize_data_formats,
+    train_on_responses_only,
+)
+
+tokenizer = get_chat_template(tokenizer, chat_template = "qwen3")
+dataset = standardize_data_formats(dataset)  # normalizes ShareGPT/OpenAI column names
+```
+
+Then mask the prompt so loss is computed on assistant turns only. Without this, the model is
+also trained to generate user messages:
+
+```python
+trainer = train_on_responses_only(
+    trainer,
+    instruction_part = "<|im_start|>user\n",
+    response_part = "<|im_start|>assistant\n",
+)
+```
+
+The two part strings must match the template's actual delimiters. Verify by decoding one batch
+and confirming the masked region covers exactly the prompt.
+
+### Step 4: Attach LoRA adapters
+
+```python
+model = FastLanguageModel.get_peft_model(
+    model,
+    r = 16,
+    lora_alpha = 16,
+    lora_dropout = 0.0,
+    target_modules = [
+        "q_proj", "k_proj", "v_proj", "o_proj",
+        "gate_proj", "up_proj", "down_proj",
+    ],
+    use_gradient_checkpointing = "unsloth",  # Unsloth's variant, lower VRAM than True
+    random_state = 3407,
+)
+```
+
+Rank guidance: `r=8-16` for style and format adaptation, `r=32-64` when teaching genuinely new
+capability. Setting `lora_alpha` to 1-2x `r` is a safe default. Keep `lora_dropout = 0.0` —
+Unsloth's fast path is only taken when dropout is zero.
+
+Train all seven projection modules unless VRAM forces otherwise; attention-only LoRA
+underperforms noticeably on instruction data. For MoE models, expert layers are `nn.Parameter`
+rather than `nn.Linear` and need `target_parameters` instead of `target_modules`.
+
+### Step 5: Train
+
+Unsloth returns standard PEFT-wrapped models, so TRL's trainers work unmodified.
+
+```python
+from trl import SFTTrainer, SFTConfig
+
+trainer = SFTTrainer(
+    model = model,
+    tokenizer = tokenizer,
+    train_dataset = dataset,
+    args = SFTConfig(
+        per_device_train_batch_size = 2,
+        gradient_accumulation_steps = 8,  # effective batch 16
+        warmup_steps = 5,
+        num_train_epochs = 1,
+        learning_rate = 2e-4,
+        optim = "adamw_8bit",
+        output_dir = "outputs",
+    ),
+)
+trainer.train()
+```
+
+`2e-4` suits LoRA; full fine-tuning needs roughly 10x lower. One to three epochs is typical —
+LoRA overfits small datasets quickly, so watch eval loss rather than trusting an epoch count.
+
+### Step 6: Export to the target runtime
+
+The right format depends entirely on where the model will run:
+
+| Target | Call | Notes |
+| :--- | :--- | :--- |
+| llama.cpp / Ollama / LM Studio | `model.save_pretrained_gguf(dir, tokenizer, quantization_method="q4_k_m")` | Builds llama.cpp on first use. |
+| vLLM / TGI / Transformers | `model.save_pretrained_merged(dir, tokenizer, save_method="merged_16bit")` | Full-size weights. |
+| Adapter only (swapped at runtime) | `model.save_pretrained_merged(dir, tokenizer, save_method="lora")` | Megabytes, not gigabytes. |
+| Hugging Face Hub | `model.push_to_hub_gguf(...)` / `model.push_to_hub_merged(...)` | Needs a write token. |
+
+`quantization_method` accepts a list, so several GGUF quants can be produced in one conversion
+pass: `["q4_k_m", "q5_k_m", "q8_0"]`. `q4_k_m` is the usual quality/size compromise. The `iq*`
+importance-matrix quants additionally require `imatrix_file=`.
+
+Avoid `save_method="merged_4bit"` for anything redistributed — it bakes in the quantization and
+cannot be cleanly re-quantized afterwards.
+
+## Examples
+
+### Example 1: QLoRA SFT on a 16 GB GPU
+
+```python
+import unsloth
+from unsloth import FastLanguageModel
+from unsloth.chat_templates import get_chat_template, train_on_responses_only
+from datasets import load_dataset
+from trl import SFTTrainer, SFTConfig
+
+model, tokenizer = FastLanguageModel.from_pretrained(
+    model_name = "unsloth/Qwen3-8B",
+    max_seq_length = 2048,
+    load_in_4bit = True,
+)
+model = FastLanguageModel.get_peft_model(model, r = 16, lora_alpha = 16)
+
+tokenizer = get_chat_template(tokenizer, chat_template = "qwen3")
+dataset = load_dataset("mlabonne/FineTome-100k", split = "train[:5000]")
+
+trainer = SFTTrainer(
+    model = model,
+    tokenizer = tokenizer,
+    train_dataset = dataset,
+    args = SFTConfig(
+        per_device_train_batch_size = 2,
+        gradient_accumulation_steps = 8,
+        num_train_epochs = 1,
+        learning_rate = 2e-4,
+        optim = "adamw_8bit",
+        output_dir = "outputs",
+    ),
+)
+trainer = train_on_responses_only(
+    trainer,
+    instruction_part = "<|im_start|>user\n",
+    response_part = "<|im_start|>assistant\n",
+)
+trainer.train()
+
+model.save_pretrained_gguf("qwen3-tuned", tokenizer, quantization_method = "q4_k_m")
+```
+
+### Example 2: GRPO with vLLM-backed generation
+
+GRPO samples several completions per prompt at every step, so generation dominates step time.
+Load with `fast_inference=True` to route sampling through vLLM in the same process.
+
+```python
+import unsloth
+from unsloth import FastLanguageModel
+from trl import GRPOTrainer, GRPOConfig
+
+model, tokenizer = FastLanguageModel.from_pretrained(
+    model_name = "unsloth/Qwen3-4B",
+    max_seq_length = 1024,
+    load_in_4bit = True,
+    fast_inference = True,       # vLLM sampling backend
+    max_lora_rank = 32,          # must be >= the r used below
+    gpu_memory_utilization = 0.6,
+)
+model = FastLanguageModel.get_peft_model(model, r = 32, lora_alpha = 32)
+
+def reward_length(completions, **kwargs):
+    """Placeholder. Replace with a task-specific verifier."""
+    return [min(len(c) / 200.0, 1.0) for c in completions]
+
+trainer = GRPOTrainer(
+    model = model,
+    processing_class = tokenizer,
+    reward_funcs = [reward_length],
+    train_dataset = dataset,
+    args = GRPOConfig(
+        num_generations = 8,
+        max_prompt_length = 256,
+        max_completion_length = 512,
+        learning_rate = 5e-6,
+        output_dir = "grpo-outputs",
+    ),
+)
+trainer.train()
+```
+
+`gpu_memory_utilization` splits VRAM between vLLM's KV cache and training. Raise it if
+generation is the bottleneck, lower it if training OOMs. `max_lora_rank` is fixed at load time
+and must be at least the `r` passed later, or adapter loading fails.
+
+GRPO learning rates sit roughly two orders of magnitude below SFT. Reward functions receive
+`completions` plus any dataset columns as keyword arguments, and return one float per completion.
+
+## Best Practices
+
+- ✅ Set `random_state` so a promising run can be reproduced.
+- ✅ Log peak VRAM on the first run and reuse it to size later jobs on the same hardware.
+- ✅ Evaluate the exported artifact, not just the adapter — quantization shifts behaviour.
+- ❌ Don't change `max_seq_length` between training and export; the GGUF inherits it.
+- ❌ Don't tune hyperparameters before the loss mask has been verified once.
+
+## Limitations
+
+- The VRAM figures above are planning heuristics, not benchmarks. Confirm on target hardware.
+- Architecture support changes between releases. Check upstream before assuming a model works.
+- Unsloth's speed and memory claims are the project's own published figures, measured on their
+  own benchmarks; they are not independently verified here.
+- This skill does not replace environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if the GPU, model, dataset format or export target is unknown —
+  every step above depends on those four.
+
+## Security & Safety Notes
+
+- Training commands are long-running and hold the GPU exclusively. Confirm before launching on
+  a shared or remote machine.
+- `push_to_hub_gguf` and `push_to_hub_merged` publish weights to a public Hub repo by default.
+  Confirm intent and pass `private=True` when the model is not meant to be public.
+- Read Hugging Face tokens from the environment (`HF_TOKEN`), never inline in a script. A
+  committed token grants write access to every model the account owns.
+- Fine-tuning reproduces the training data's content and biases in the weights. Confirm the
+  dataset is licensed for training and free of secrets before starting.
+- GGUF export builds llama.cpp from source on first use, compiling third-party code and
+  requiring network access. Expect it to be slow and to need a working toolchain.
+- Unsloth is dual-licensed: the core package is Apache-2.0, while optional components such as
+  the Studio UI are AGPL-3.0. Check a component's license before redistributing it.
+
+## Common Pitfalls
+
+- **Problem:** Trained model ignores stop tokens or echoes the prompt format.
+  **Solution:** Wrong chat template, or `train_on_responses_only` was never applied. Verify the
+  mask on a decoded batch before blaming hyperparameters.
+
+- **Problem:** CUDA OOM partway through the first epoch rather than at step 0.
+  **Solution:** A long sample exceeded the activation budget. Lower `max_seq_length` or filter
+  outliers — peak memory tracks the longest sequence, not the mean.
+
+- **Problem:** Training runs, but at ordinary unaccelerated speed.
+  **Solution:** `transformers` or `trl` was imported before `unsloth`, so the patches never
+  applied. Move `import unsloth` to the top of the file.
+
+- **Problem:** `save_pretrained_gguf` appears to hang on first call.
+  **Solution:** It is building llama.cpp. Ensure a compiler and network access are available, or
+  export `merged_16bit` and convert separately.
+
+- **Problem:** GRPO fails with a LoRA rank mismatch.
+  **Solution:** `max_lora_rank` at `from_pretrained` is below the `r` given to `get_peft_model`.
+  Raise it to match.
+
+- **Problem:** Loss collapses to near zero within a few hundred steps.
+  **Solution:** Overfitting a small dataset, or the loss mask is leaking the answer into the
+  prompt. Check dataset size against epoch count, then re-verify masking.
+
+## Related Skills
+
+- `@trl-training` - Use for the TRL CLI, multi-GPU runs, or architectures Unsloth lacks.
+- `@hugging-face-model-trainer` - Use for managed training on Hugging Face Jobs instead of local hardware.
+- `@local-llm-expert` - Use to serve the exported GGUF via Ollama, llama.cpp or vLLM.
+
+## Additional Resources
+
+- [Unsloth documentation](https://unsloth.ai/docs)
+- [Reinforcement learning guide (GRPO, DPO)](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide)
+- [Saving to GGUF](https://unsloth.ai/docs/basics/inference-and-deployment/saving-to-gguf)
+- [unslothai/unsloth on GitHub](https://github.com/unslothai/unsloth)

package/bundled-skills/vibe-delegate/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: vibe-delegate
+description: Delegate coding tasks to the Mistral Vibe CLI (`vibe`) only when the
+  user explicitly requests it, while the orchestrator retains review and landing responsibility.
+risk: safe
+category: agent-orchestration
+source: https://github.com/amElnagdy/delegate-skills
+source_repo: amElnagdy/delegate-skills
+source_type: community
+date_added: '2026-08-26'
+license: MIT
+license_source: https://github.com/amElnagdy/delegate-skills/blob/master/LICENSE
+metadata:
+  version: 0.5.0
+---
+# Vibe Delegate
+
+## When to Use
+
+- You want to delegate a bounded coding task to a separate `vibe` implementer (`Mistral Vibe`) and then review its diff yourself.
+- The user explicitly asked for delegation to this implementer.
+
+You are the **orchestrator**. Hand a bounded coding task to a separate **implementer** — the Mistral
+Vibe CLI (`vibe`) — then review what it produced and land it yourself. You write the brief and own
+the judgment; Vibe does the typing in its own session; you verify and commit.
+
+The loop needs only a shell command and file access, so any comparable orchestrator can drive it.
+
+## When NOT to use this
+
+- The task is small enough to do inline; delegation overhead is not worth it.
+- The `vibe` CLI is not installed or authenticated.
+
+## Prerequisites (check once)
+
+1. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then Mistral Vibe:
+   - `uv tool install mistral-vibe`
+2. Configure your API key with `vibe --setup`, or set `MISTRAL_API_KEY` in the environment.
+3. Confirm `vibe --version` succeeds.
+4. Work in, or point `--cd` at, the target git repository.
+
+## The loop
+
+Run these five steps per task. Steps 1, 4, and 5 require judgment; 2 and 3 are mechanical.
+
+### 1. Write the brief
+
+Vibe sees only the text you send plus what it can inspect in the workspace — no chat history or shared
+context. Include the goal, current state, what to change, what to leave untouched, the project's
+**actual** gates, and a report contract. Tell Vibe not to commit. Keep one task per brief. See
+[references/writing-the-brief.md](references/writing-the-brief.md).
+
+Default mode cannot approve most shell commands headlessly, so the orchestrator runs the gates. Ask
+Vibe to run them only when the human explicitly authorized `--full-access`.
+
+### 2. Dispatch
+
+Use the bundled helper. It wraps Vibe's headless `--prompt` mode, captures the structured event
+stream, and writes `result.json`. (`<skill-dir>` is the installed folder containing this `SKILL.md`.)
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+# limit turns for cost control:           add --max-turns <n>
+# indicative price threshold/token cap:  add --max-price <usd> --max-tokens <n>
+# planning/read-only:                     add --plan-only
+# unrestricted shell and tools:           add --full-access (explicit authorization required)
+# resume the most recent session:         add --resume-last  (delta brief only)
+# resume a specific session:              add --session <id> (delta brief only)
+# see all options:                        node .../relay.mjs --help
+```
+
+The child process's cwd pins the workspace. The relay writes artifacts under the system temp dir by
+default and never commits. See [references/dispatch-and-poll.md](references/dispatch-and-poll.md).
+
+### 3. Wait for completion
+
+The helper blocks until Vibe finishes. Run it with the orchestrator's background-command facility, or
+background it in the shell and poll for `result.json`. A pre-run usage error exits 2 and writes no
+result; a missing `vibe` exits 127 and writes `status: "vibe_unavailable"`.
+The watchdog writes `status: "timeout"`; terminating the relay on POSIX writes `status: "aborted"`
+after stopping Vibe's process tree.
+
+Trust process state and the working tree over a progress display. Completion means the process exited
+and `result.json` exists.
+
+### 4. Review — do not trust the self-report
+
+Treat Vibe's final message and gate claims as claims:
+
+- Re-run the project's gates yourself.
+- Read the diff against the brief, starting with `touchedFiles`.
+- Run relevant guard skills if installed.
+- Round-trip migrations and grep for dangling references after removals or renames.
+
+See [references/review-and-land.md](references/review-and-land.md).
+
+### 5. Land it
+
+The implementer edits the working tree; **the orchestrator commits.** Commit only after the gates pass
+and the diff holds. If rework is needed, send a delta brief with `--resume-last` or `--session <id>`,
+then review again.
+
+## Autonomy and permissions
+
+In `--prompt` mode the relay always sets the agent profile explicitly:
+
+| Relay flag | What Vibe gets | Use when |
+| --- | --- | --- |
+| *(default)* | `--agent accept-edits` | Normal implementation — built-in file edits are approved |
+| `--plan-only` | `--agent plan` | Read-only review, exploration, or planning |
+| `--full-access` | `--agent auto-approve` | Explicitly authorized runs that need arbitrary shell/tools |
+
+Default mode lets Vibe edit files inside the target worktree. Approval-gated shell commands,
+including most project gates, are denied headlessly; the orchestrator runs the gates.
+`--full-access` disables Vibe's tool approvals and permits arbitrary shell/tool execution under the
+user account; use it only with explicit human authorization. Always inspect `touchedFiles` and the
+diff after a run.
+
+`--trust` is always passed to prevent interactive directory-trust prompts in headless runs. It is
+not a sandbox and does not grant tool permissions.
+
+## Authorization model
+
+Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing
+verified, gate-passing work is the agreed contract. Two limits remain: **surface, don't absorb**
+(report Vibe's design decisions, defensible-but-unasked turns, and non-blocking nitpicks) and **stop
+for scope changes** (if correct completion needs going beyond the brief, ask instead of expanding the
+mandate). See [references/review-and-land.md](references/review-and-land.md).
+
+## References
+
+- [references/writing-the-brief.md](references/writing-the-brief.md) — structure, report contract,
+  real gates, argv delivery, and delta briefs.
+- [references/dispatch-and-poll.md](references/dispatch-and-poll.md) — flags, artifacts,
+  `result.json`, polling, and failure recovery.
+- [references/review-and-land.md](references/review-and-land.md) — review checklist, commit boundary,
+  and rework through Vibe sessions.
+- [references/multi-task-queues.md](references/multi-task-queues.md) — sequential queues, constraint
+  carry-forward, progress tracking, and the final coherence pass.
+
+
+## Limitations
+
+- Docs-only import — executable `scripts/relay.mjs` not included; see upstream for full runtime. Requires `vibe` CLI, Node 18+, git.
+- Relay never commits — it only returns structured result JSON; you review and land the commit.
+
+> Adapted from [amElnagdy/delegate-skills](https://github.com/amElnagdy/delegate-skills) (MIT) — docs-only, runtime not bundled.

package/bundled-skills/vibe-delegate/references/dispatch-and-poll.md

@@ -0,0 +1,144 @@
+# Dispatch and poll
+
+`scripts/relay.mjs` wraps Vibe's headless `--prompt` mode, captures its structured stream, and writes
+a `result.json`. Run one command, then read one file.
+
+## Before the first run
+
+```bash
+command -v vibe
+vibe --version
+```
+
+Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then install Vibe with
+`uv tool install mistral-vibe`. Configure your API key:
+
+```bash
+vibe --setup                    # interactive setup
+export MISTRAL_API_KEY="..."    # or set it in the environment
+```
+
+Upstream Vibe works on Windows but officially supports and targets UNIX. This repository has not
+smoke-tested the relay's native Windows launch; consult the
+[official Mistral Vibe documentation](https://github.com/mistralai/mistral-vibe) for Windows guidance.
+
+## Dispatching
+
+```bash
+node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
+```
+
+`<skill-dir>` is the installed folder containing this skill's `SKILL.md`.
+
+| Flag | Effect |
+| --- | --- |
+| `--brief <file>` | Brief path. Omit it to read the brief from stdin. |
+| `--cd <dir>` | Working root and child process cwd (default: current directory). |
+| `--lane <name>` | Fleet lane from `delegate-setup` config. Applies that lane's dials; fails if the lane's `implementer` is not this relay. Explicit dial flags win. |
+| `--max-turns <n>` | Maximum number of Vibe agent turns (`--max-turns`). Useful for cost control. |
+| `--max-price <usd>` | Positive, indicative cost threshold in USD; not a hard budget (`--max-price`). |
+| `--max-tokens <n>` | Positive maximum cumulative session tokens (`--max-tokens`). |
+| `--session <id>` | Resume a specific Vibe session (`--resume SESSION_ID`); send only the delta brief. |
+| `--resume-last` | Resume the most recent Vibe session (`--continue`); send only the delta brief. |
+| `--plan-only` | Use Vibe's read-only `plan` agent. |
+| `--full-access` | Use Vibe's `auto-approve` agent; arbitrary shell/tools run under the user account. |
+| `--enabled-tools <tool>` | Enable only this tool (`--enabled-tools`). Repeatable. |
+| `--disabled-tools <tool>` | Disable this tool (`--disabled-tools`). Repeatable. |
+| `--timeout <dur>` | Relay watchdog (default: `30m`; h/m/s strings). Vibe has no timeout flag. |
+| `--out-dir <dir>` | Artifact directory (default: a fresh directory under the system temp dir). |
+| `-h`, `--help` | Print the relay's header help. |
+
+`--session` and `--resume-last` are mutually exclusive, as are `--plan-only` and `--full-access`.
+The relay always passes `--trust` so headless runs do not prompt for directory trust. That flag is not
+a sandbox or tool permission.
+
+Default mode uses `accept-edits`: Vibe's built-in file edits are approved, while approval-gated shell
+commands — including most project gates — are denied headlessly rather than hanging. The orchestrator
+runs the gates. Use `--full-access` only with explicit human authorization; it selects
+`auto-approve`, which approves all tool executions. Inspect `touchedFiles` and the diff after every run.
+
+## Artifacts and result fields
+
+Artifacts live outside the repo by default, so they do not appear in `touchedFiles`; an `--out-dir`
+inside the worktree can make the artifacts appear there:
+
+- `brief.txt` — the exact brief.
+- `events.jsonl` — raw Vibe stdout in streaming JSON format.
+- `final.txt` — the last non-empty assistant message; absent if none was emitted.
+- `stderr.txt` — complete stderr.
+- `result.json` — the stable `delegate-relay.result.v1` contract.
+
+`result.json` fields:
+
+- `schema`, `tool` (`"vibe"`), `status` (`completed` | `failed` | `timeout` | `aborted` |
+  `vibe_unavailable`), `exitCode`, and `signal` (`null` unless the child died on a signal).
+- `workdir`, `agent` (`"accept-edits"`, `"plan"`, or `"auto-approve"`), `maxTurns`, `maxPrice`,
+  `maxTokens`, `resumed`, `vibeVersion`, `sessionId`, `startedAt`, and `finishedAt`.
+- `briefPath`, `finalPath`, `eventsPath`, and `stderrPath`.
+- `finalMessage` — the last non-empty assistant content string; tool calls and tool results are excluded.
+- `touchedFiles` — `git status --porcelain` lines for the **final working tree under `--cd`**. Not
+  an attribution of Vibe's edits: anything already dirty before dispatch shows up too. Dispatch from
+  a clean tree when you want the list to read as "what Vibe changed". `null` means git could not
+  report; `[]` means git ran and the tree is clean.
+- `stderrTail` — the last 20 non-empty stderr lines on a run that did not complete.
+- `error` — present for launch failures, `timeout`, and `aborted`.
+
+Vibe's streaming output does not expose its session id, so `sessionId` is always `null` for schema
+compatibility. Use `--resume-last`; retain `--session <id>` only for an id obtained outside the relay.
+
+## Waiting for completion
+
+The helper blocks. Use the orchestrator's background-command facility, or background it in a shell and
+poll for `result.json`. The run is done only when the process exits and the file contains a `status`.
+
+A pre-run usage error exits 2 and writes no result. A missing `vibe` exits 127 and writes
+`status: "vibe_unavailable"`.
+
+## When a run misbehaves
+
+- **`status: "vibe_unavailable"` (exit 127):** `vibe` isn't on PATH. Install
+  [`uv`](https://docs.astral.sh/uv/getting-started/installation/), run
+  `uv tool install mistral-vibe`, and configure `MISTRAL_API_KEY`, then re-dispatch.
+- **`status: "failed"`:** read `stderrTail`, `stderrPath`, and the tail of `events.jsonl`. Common
+  causes: an unconfigured or expired API key, an invalid model, or a trust-folder prompt that was
+  not suppressed (the relay passes `--trust`, but check that the binary supports it).
+- **`status: "aborted"`:** the relay itself was killed and terminated Vibe's process tree. Inspect the
+  working tree before re-dispatching. Native Windows has no catchable `SIGTERM`; a relay that vanishes
+  there without `result.json` is an aborted run, so inspect the tree and `events.jsonl` directly.
+- **`status: "failed"` with `signal: "SIGKILL"`:** the host killed the process, commonly through the
+  OOM killer or a supervisor timeout. This is not a Vibe error; check host memory and re-dispatch, or
+  split the task into smaller briefs.
+- **`status: "timeout"`:** `error` reads
+  `vibe did not finish within --timeout <dur>; killed by the relay watchdog`. Increase `--timeout` or
+  split the task. The relay sends SIGTERM, waits 10 seconds, then sends SIGKILL if needed.
+- **Empty `finalMessage`:** inspect `touchedFiles` and the diff. Add a
+  `<structured_output_contract>` to the next brief to require a closing report. The streaming events
+  in `events.jsonl` are the source of truth for diagnosing missing messages.
+
+## Recovering lost work
+
+`events.jsonl` records every message Vibe streamed. If finished work is lost — the run ended late or
+the tree was damaged afterward — read it before re-dispatching to scope which files and tools were
+involved. It may not contain the edit contents, so treat reconstruction as unverified until it matches
+a working-tree diff; when the tree still holds the work, preserve the tree rather than replaying the log.
+
+## What the relay runs
+
+The argv is equivalent to:
+
+```bash
+vibe --output streaming --agent <accept-edits|plan|auto-approve> --trust \
+  [--max-turns <n>] [--max-price <usd>] [--max-tokens <n>] \
+  [--resume SESSION_ID | --continue] \
+  [--enabled-tools TOOL ...] [--disabled-tools TOOL ...] \
+  --prompt=<brief>
+```
+
+The prompt rides argv and is visible in the host process list. The relay rejects briefs over 120 KB
+on POSIX or 12 KB on Windows before launch because the platforms cap command arguments. It spawns the
+native `vibe` binary directly with `--cd` as cwd; no shell or Vibe timeout flag is involved.
+
+## The commit boundary
+
+The relay never commits. Vibe edits the working tree; the orchestrator reviews, re-runs the gates, and
+commits. See [review-and-land.md](review-and-land.md).