rsc-universal 0.1.1

package/skills/observability/references/instrumentation-recipes.md

@@ -0,0 +1,115 @@
+# Instrumentation recipes — per stack
+
+Stack-specific snippets offloaded from `SKILL.md`. Reach for these only after zero-code auto-instrumentation is flowing; manual code is for business logic the auto layer can't see. APIs target **OpenTelemetry JS SDK 2.0+** and current Python/Go SDKs.
+
+## Node / JS — manual SDK init
+
+Use this only if you need programmatic control beyond the `--require` register hook (custom processors, multiple exporters, sampler tuning). Otherwise prefer the zero-code path in `SKILL.md`.
+
+```javascript
+// instrument.js — load FIRST, before any other require (node -r ./instrument.js app.js)
+const { NodeSDK } = require('@opentelemetry/sdk-node');
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
+const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
+const { resourceFromAttributes } = require('@opentelemetry/resources');
+
+const sdk = new NodeSDK({
+  resource: resourceFromAttributes({
+    'service.name': 'checkout-api',
+    'service.version': '1.4.2',
+    'deployment.environment': 'prod',
+  }),
+  traceExporter: new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+sdk.start();
+process.on('SIGTERM', () => sdk.shutdown());  // flush buffered spans on shutdown
+```
+
+## Python — launcher + manual span
+
+`opentelemetry-instrument` patches known libraries on import. Add manual spans only around your own logic.
+
+```python
+from opentelemetry import trace
+tracer = trace.get_tracer("checkout")
+
+def settle_order(order_id):
+    with tracer.start_as_current_span("settle_order") as span:
+        span.set_attribute("order.id", order_id)
+        try:
+            do_settlement(order_id)
+            span.set_status(trace.StatusCode.OK)
+        except Exception as err:
+            span.record_exception(err)
+            span.set_status(trace.StatusCode.ERROR, str(err))
+            raise
+```
+
+## Go — SDK init
+
+Go has no zero-code agent; init the provider in `main` and use `otelhttp`/`otelgrpc` middleware for transport-level spans.
+
+```go
+import (
+    "go.opentelemetry.io/otel"
+    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+    "go.opentelemetry.io/otel/sdk/resource"
+    sdktrace "go.opentelemetry.io/otel/sdk/trace"
+    semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
+)
+
+func initTracer(ctx context.Context) (*sdktrace.TracerProvider, error) {
+    exp, err := otlptracehttp.New(ctx) // reads OTEL_EXPORTER_OTLP_ENDPOINT
+    if err != nil { return nil, err }
+    res, _ := resource.New(ctx, resource.WithAttributes(
+        semconv.ServiceName("checkout-api"),
+        semconv.ServiceVersion("1.4.2"),
+        semconv.DeploymentEnvironment("prod"),
+    ))
+    tp := sdktrace.NewTracerProvider(
+        sdktrace.WithBatcher(exp),
+        sdktrace.WithResource(res),
+    )
+    otel.SetTracerProvider(tp)
+    return tp, nil // defer tp.Shutdown(ctx) in main
+}
+```
+
+## Context propagation across boundaries
+
+A trace only spans services if the `traceparent` (W3C Trace Context) is carried across each hop. Auto-instrumentation handles HTTP for you; you must do it by hand across **message queues**, which have no built-in carrier.
+
+```javascript
+// Producer — inject the active context into message headers.
+const { propagation, context } = require('@opentelemetry/api');
+const headers = {};
+propagation.inject(context.active(), headers);
+await queue.send({ body, headers });          // ship headers alongside the payload
+
+// Consumer — extract it, then run work inside the parent context.
+const parentCtx = propagation.extract(context.active(), msg.headers);
+context.with(parentCtx, () => {
+  tracer.startActiveSpan('process_message', (span) => { /* ... */ span.end(); });
+});
+```
+
+Without this, the consumer starts a brand-new root trace and you lose the causal link from producer to consumer.
+
+## GenAI / LLM span template
+
+Use `gen_ai.*` semantic conventions (client spans exited experimental, early 2026). Span name convention is `{operation} {model}`. These token attributes are the bridge that `../cost-tracking/SKILL.md` consumes to compute spend.
+
+```python
+with tracer.start_as_current_span("chat gpt-4o") as span:
+    span.set_attribute("gen_ai.system", "openai")
+    span.set_attribute("gen_ai.operation.name", "chat")
+    span.set_attribute("gen_ai.request.model", "gpt-4o")
+    span.set_attribute("gen_ai.request.temperature", 0.2)
+    resp = client.chat.completions.create(model="gpt-4o", messages=msgs, temperature=0.2)
+    span.set_attribute("gen_ai.response.model", resp.model)
+    span.set_attribute("gen_ai.usage.input_tokens", resp.usage.prompt_tokens)
+    span.set_attribute("gen_ai.usage.output_tokens", resp.usage.completion_tokens)
+```
+
+Do not put the prompt or completion *text* on the span by default — it is high-cardinality and frequently PII. Capture it only behind an explicit, redacted, opt-in content-capture flag.

package/skills/observability/scripts/verify.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+#
+# verify.sh - lint an emitted OpenTelemetry observability setup.
+#
+# Usage:
+#   cd <dir containing the Collector config + SDK init>
+#   ./verify.sh [path-to-collector-config.yaml]
+#
+# Read-only: never mutates anything. Checks the wiring, not just presence:
+#   1. a Collector config exists (a *.yaml/*.yml with receivers: and service:)
+#   2. it is valid: `otelcol validate` if the binary is on PATH, else
+#      a required-keys check for receivers / exporters / service.pipelines
+#   3. every exporter declared under exporters: is referenced in some
+#      pipeline (the classic "exporter defined but never enabled" footgun)
+#   4. SDK init sets the service name (OTEL_SERVICE_NAME /
+#      OTEL_RESOURCE_ATTRIBUTES / a service.name resource attribute) -> warn
+#   5. heuristic cardinality check: warn if user_id|request_id|email|session_id
+#      is used as a metric label/attribute key
+#
+# Emits [ ok ]/[warn]/[fail] per check, then PASS or FAIL.
+# Exits 0 on a clean setup AND when nothing relevant is found (no false failure).
+# Exits 1 only on hard failures: no config, invalid config, unused exporter.
+#
+# Portable: stock macOS bash 3.2 + grep + awk. No associative arrays, no mapfile.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+
+failed=0
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+
+# --- 1. locate a Collector config -------------------------------------------
+cfg="${1:-}"
+if [ -z "$cfg" ]; then
+  # any yaml/yml that looks like a Collector config (has receivers: and service:)
+  while IFS= read -r f; do
+    if grep -Eq '^[[:space:]]*receivers[[:space:]]*:' "$f" \
+       && grep -Eq '^[[:space:]]*service[[:space:]]*:' "$f"; then
+      cfg="$f"; break
+    fi
+  done < <(find . -maxdepth 3 -type f \( -name '*.yaml' -o -name '*.yml' \) 2>/dev/null)
+fi
+
+if [ -z "$cfg" ] || [ ! -f "$cfg" ]; then
+  skip "no OTel Collector config found (a *.yaml with receivers: + service:) - nothing to verify."
+  exit 0
+fi
+
+printf -- '----- linting %s\n' "$cfg"
+
+# --- 2. validity ------------------------------------------------------------
+if command -v otelcol >/dev/null 2>&1; then
+  if otelcol validate --config "$cfg" >/dev/null 2>&1; then
+    ok "otelcol validate passed"
+  else
+    fail "otelcol validate rejected the config"
+  fi
+elif command -v otelcol-contrib >/dev/null 2>&1; then
+  if otelcol-contrib validate --config "$cfg" >/dev/null 2>&1; then
+    ok "otelcol-contrib validate passed"
+  else
+    fail "otelcol-contrib validate rejected the config"
+  fi
+else
+  # no binary: required top-level/section keys must be present
+  miss=""
+  grep -Eq '^[[:space:]]*receivers[[:space:]]*:'  "$cfg" || miss="$miss receivers"
+  grep -Eq '^[[:space:]]*exporters[[:space:]]*:'  "$cfg" || miss="$miss exporters"
+  grep -Eq '^[[:space:]]*service[[:space:]]*:'    "$cfg" || miss="$miss service"
+  grep -Eq '^[[:space:]]*pipelines[[:space:]]*:'  "$cfg" || miss="$miss service.pipelines"
+  if [ -z "$miss" ]; then
+    ok "required sections present (receivers, exporters, service.pipelines) [otelcol not on PATH; key-check only]"
+  else
+    fail "config missing required section(s):$miss"
+  fi
+fi
+
+# --- 3. every declared exporter is referenced in a pipeline -----------------
+# Collect exporter ids: indented one level under the top-level `exporters:` block,
+# keys ending in ':' (e.g. "otlphttp/traces:"). Then confirm each id's bare name
+# appears somewhere after a "service:"/"pipelines:" context.
+exp_ids="$(awk '
+  /^exporters[[:space:]]*:/        { in_exp=1; ind=-1; next }
+  /^[a-zA-Z0-9_]+[[:space:]]*:/    { if (in_exp) in_exp=0 }   # next top-level block ends it
+  in_exp {
+    if ($0 ~ /^[[:space:]]+[A-Za-z0-9_\/.-]+[[:space:]]*:/) {
+      line=$0
+      sub(/:.*/, "", line); gsub(/[[:space:]]/, "", line)
+      # only the first indentation level (exporter ids), skip deeper config keys
+      lead=match($0, /[^ ]/)-1
+      if (ind==-1) ind=lead
+      if (lead==ind && line!="") print line
+    }
+  }
+' "$cfg" 2>/dev/null || true)"
+
+if [ -z "$exp_ids" ]; then
+  skip "no exporter ids parsed under exporters: - skipping unused-exporter check"
+else
+  # body after the first `service:` line is where pipelines reference exporters
+  svc_body="$(awk '/^service[[:space:]]*:/{s=1} s{print}' "$cfg")"
+  unused=""
+  for e in $exp_ids; do
+    if printf '%s\n' "$svc_body" | grep -Fq "$e"; then
+      :
+    else
+      unused="$unused $e"
+    fi
+  done
+  if [ -z "$unused" ]; then
+    ok "every declared exporter is wired into a pipeline"
+  else
+    fail "exporter(s) declared but never used in any pipeline:$unused (inert until added to service.pipelines)"
+  fi
+fi
+
+# --- 4. service.name is set somewhere in the setup --------------------------
+# Look across the whole dir's likely SDK-init files, not just the yaml.
+sdk_hit=0
+if grep -Rqs -E 'OTEL_SERVICE_NAME|OTEL_RESOURCE_ATTRIBUTES|service[._-]?name|ServiceName' . 2>/dev/null; then
+  sdk_hit=1
+fi
+if [ "$sdk_hit" -eq 1 ]; then
+  ok "service.name is set (OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES / resource attr found)"
+else
+  warn "no service.name found - telemetry will land as 'unknown_service'. Set OTEL_SERVICE_NAME or a service.name resource attribute."
+fi
+
+# --- 5. high-cardinality metric label heuristic -----------------------------
+# Warn (don't fail) if an unbounded id is used as a metric label/attribute key.
+card_hit="$(grep -RnsE '(user_id|request_id|session_id|email)[[:space:]]*[:=]' . 2>/dev/null \
+            | grep -Ei 'label|attribute|metric|tags?|dimension' || true)"
+if [ -n "$card_hit" ]; then
+  warn "possible high-cardinality metric label(s) - keep these off metrics, put them on spans/logs:"
+  printf '%s\n' "$card_hit" | sed 's/^/        /'
+else
+  ok "no obvious high-cardinality metric label (user_id/request_id/session_id/email)"
+fi
+
+# --- verdict ----------------------------------------------------------------
+echo
+if [ "$failed" -eq 0 ]; then
+  printf '%sPASS%s - observability setup is wired.\n' "$GREEN" "$RESET"
+  exit 0
+else
+  printf '%sFAIL%s - fix the items above.\n' "$RED" "$RESET"
+  exit 1
+fi

package/skills/ollama/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: ollama
+description: "Use when running open-weight LLMs locally with Ollama — pulling/tagging models, calling the local API, picking a quant/GGUF, writing Modelfiles, or sizing VRAM/RAM for the box you're on. Triggers: 'run Llama/Qwen/gpt-oss/Gemma locally', 'self-host an LLM, no API keys, offline', 'model requires more memory than is available', 'why does my 70B OOM at long context', 'point the OpenAI SDK at localhost:11434', 'ollama ps / pull / create', 'ejecutar un LLM en local sin API key', 'quin model i quina quantització caben a la meva GPU de 12GB'. NOT remote/managed GPU serving or autoscaling (that is runpod), NOT downloading raw weights/datasets (that is huggingface), NOT retrieval pipeline design (that is rag)."
+tags: [ollama, local-llm, gguf, quantization, self-hosted-inference]
+recommends: [huggingface, runpod, modal, llm-pipeline, rag]
+origin: risco
+---
+
+# Ollama — run open-weight LLMs on one box
+
+Ollama serves GGUF models from a local daemon at `http://localhost:11434`, exposing both a native
+HTTP API and an OpenAI-compatible layer. Your job: reach for the right command, the right endpoint,
+and the right quant **for the hardware in front of you** — and recognize when the model does not fit
+and the work belongs on a remote GPU instead.
+
+This skill owns: install/serve, pull/tag, the local API (native + OpenAI-compat), Modelfiles,
+quantization choice, and VRAM/RAM sizing on a single machine.
+
+## When to use / when not
+
+**Use when** the model runs on *this* machine: pulling/running a model, fixing an OOM, choosing
+Q4 vs Q8, authoring a Modelfile, or wiring an app to `localhost:11434`.
+
+**Go elsewhere when:**
+
+- Hosting behind a managed/remote GPU, autoscaling, or serverless inference → `runpod`, `modal`,
+  `replicate`, `together-fireworks`, `fal`. Ollama is local, single-box, no autoscale.
+- Downloading raw weights, datasets, `hf`/`transformers`, repo management → `huggingface`.
+- Designing chunking / retrieval / reranking around a model → `rag` or `embeddings-search`.
+- Orchestrating multi-step calls, routing, pipeline evals → `llm-pipeline` / `agent-eval`.
+- Writing the prompt/system-message *content* itself → `prompt-engineering`.
+
+(Those siblings live in the catalog by id; link them only once their `SKILL.md` exists on disk.)
+
+## Quickstart
+
+```bash
+ollama serve                 # start the daemon (a desktop install already runs it)
+ollama pull qwen3:8b         # download a model + tag; :8b is explicit — avoid bare :latest
+ollama run qwen3:8b          # interactive REPL, or: ollama run qwen3:8b "summarize this"
+ollama ps                    # what is LOADED in VRAM right now + when it unloads (keep_alive)
+ollama list                  # what is on disk (pulled), not what is loaded
+ollama show qwen3:8b         # template, params, context length, quant of a model
+ollama rm qwen3:8b           # free disk; ollama stop qwen3:8b unloads from memory
+```
+
+`ps` vs `list` is the OOM-debug split: `list` is disk, `ps` is memory. A model only eats VRAM once a
+request loads it; it unloads after `keep_alive` (default 5m).
+
+## Pick a model + quant
+
+Quantization trades VRAM for quality. The everyday default is **Q4_K_M**: roughly half the memory of
+fp16 for ~3–5% quality loss. **Q8_0** is near-lossless at ~1 byte/param. **fp16** is the unquantized
+ceiling at 2 bytes/param.
+
+Sizing formula (weights only) — a **rule of thumb**, not a per-model spec sheet:
+
+```text
+weights_GB ≈ params(B) × bytes_per_param × 1.2   # ×1.2 = runtime overhead
+bytes_per_param:  Q4_K_M ≈ 0.5   Q8_0 ≈ 1.0   fp16 = 2.0
+# then ADD the KV cache (see below) — it is NOT in this number.
+```
+
+These bytes/param are conservative round-downs of the measured k-quant rates: llama.cpp's quantize
+benchmark reports Q4_K_M ≈ 4.89 bits/weight (~0.6 byte/param) and Q8_0 ≈ 8.5 bits/weight (~1.06
+byte/param) on Llama-3.1-8B ([llama.cpp quantize README](https://github.com/ggml-org/llama.cpp/blob/master/tools/quantize/README.md),
+accessed 2026-06-02). Rounding to 0.5 / 1.0 keeps the estimate on the safe side; the per-row GB figures
+in the table below are derived from this formula, not vendor-published numbers — verify with `ollama show`.
+
+| VRAM / unified mem | Comfortable choice (Q4_K_M) | Notes |
+| --- | --- | --- |
+| 8 GB | 7–8B Q4_K_M (~5–6 GB) | leave headroom for KV cache + the OS |
+| 12 GB | up to ~14B Q4_K_M (~9–10 GB) | 7–8B at Q8_0 also fits |
+| 16 GB | 14B Q4_K_M comfortably; 32B is tight | 32B Q4_K_M ≈ 20 GB — won't fit |
+| 24 GB | 32B Q4_K_M (~20 GB) | 70B does **not** fit at any usable quant |
+| 48 GB+ / 2×24 GB | 70B Q4_K_M (~40–48 GB) | needs the full budget; long context pushes over |
+| Mac unified (e.g. 64 GB) | weights share RAM with everything else | budget against total unified memory |
+
+**KV cache is the trap.** It grows ~linearly with `num_ctx` and lives in VRAM *on top of* the weights.
+At long context (e.g. 128K) a 70B can add tens of GB of cache — often more than people budget for. If
+you are tight: cap `num_ctx`, or shrink the cache with `OLLAMA_KV_CACHE_TYPE=q8_0` (or `q4_0`). See
+[references/hardware-sizing.md](references/hardware-sizing.md) for the KV math and a per-context table.
+
+Ollama runs a llama.cpp-backed engine (GGUF) by default, with a scheduler that reduces OOM crashes and
+improves multi-GPU placement. On Apple Silicon it can use an **MLX** backend (shipped in Ollama 0.19,
+per [ollama.com/blog/mlx](https://ollama.com/blog/mlx), 2026-03-30), but **only on Macs with >32 GB of
+unified memory** — below that gate it stays on the llama.cpp engine. None of this invents memory you
+don't have: when the box can't hold the model, that's a `runpod`/`modal` job, not a quant downgrade.
+
+## The API
+
+Two surfaces, same daemon. Use **native `/api/chat`** when you want Ollama-specific fields
+(`keep_alive`, `format` as a JSON schema, `think`); use the **OpenAI-compat `/v1`** layer to reuse an
+existing OpenAI SDK unchanged.
+
+Native chat (`/api/chat`), non-streaming:
+
+```bash
+curl http://localhost:11434/api/chat -d '{
+  "model": "qwen3:8b",
+  "messages": [{"role": "user", "content": "Name three primes."}],
+  "stream": false,
+  "options": {"temperature": 0.2, "num_ctx": 8192},
+  "keep_alive": "10m"
+}'
+```
+
+`stream` defaults to **true** (NDJSON, one object per line, final object has `done: true` + timing
+stats). `options.num_ctx` sets the context window *for this request* — it does not persist; bake it
+into a Modelfile if you want it permanent.
+
+OpenAI-compatible — point any OpenAI SDK at `localhost:11434/v1` with a dummy key:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")  # key is ignored
+resp = client.chat.completions.create(
+    model="qwen3:8b",
+    messages=[{"role": "user", "content": "Name three primes."}],
+    temperature=0.2,
+)
+print(resp.choices[0].message.content)
+```
+
+Structured output — pass a JSON schema as `format` (native) so the model is constrained to valid JSON:
+
+```bash
+curl http://localhost:11434/api/chat -d '{
+  "model": "qwen3:8b",
+  "messages": [{"role": "user", "content": "Extract name and age from: Ana is 30."}],
+  "stream": false,
+  "format": {
+    "type": "object",
+    "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
+    "required": ["name", "age"]
+  }
+}'
+```
+
+Tool calling (`tools`), multimodal (`images` as base64), embeddings (`/api/embed`), and the full field
+tables live in [references/api.md](references/api.md). Endpoint map at a glance: `/api/generate`,
+`/api/chat`, `/api/embed`, `/api/create`, `/api/pull`, `/api/show`, `/api/ps`, `/api/tags`.
+
+## Modelfiles
+
+A Modelfile bakes a base model + system prompt + parameters into a new named model. Build with
+`ollama create`.
+
+```dockerfile
+FROM qwen3:8b
+SYSTEM "You are a terse senior code reviewer. Answer in bullet points."
+PARAMETER num_ctx 16384
+PARAMETER temperature 0.2
+PARAMETER stop "<|im_end|>"
+```
+
+```bash
+ollama create reviewer -f Modelfile     # now: ollama run reviewer
+```
+
+- `FROM` is required — a model tag or a local file (`FROM ./model.gguf` to import a raw GGUF).
+- `PARAMETER num_ctx` makes the context window permanent (vs the per-request `options.num_ctx`).
+- `SYSTEM`, `TEMPLATE`, `LICENSE`, `ADAPTER` (LoRA) round out the instruction set.
+
+Quantize on create from an fp16/fp32 source:
+
+```bash
+ollama create reviewer --quantize q4_K_M -f Modelfile   # FROM must be an fp16/fp32 model
+```
+
+`--quantize` only works when the `FROM` source is full-precision; you cannot re-quantize an
+already-Q4 model. To go from Hugging Face weights to a GGUF in the first place, that conversion is a
+`huggingface` job — Ollama imports the result.
+
+## When to leave the box
+
+If the comfortable-choice row for your VRAM can't hold the model you actually need (e.g. you need 70B
+quality on a 12 GB laptop), stop downgrading quant — quality collapses below Q4 and you'll still OOM at
+real context. Move it to a remote GPU: `runpod` (rent a GPU), `modal` (serverless container + GPU
+autoscale), or a hosted endpoint (`replicate`, `together-fireworks`, `fal`). Ollama is the right tool
+*until the weights + KV cache exceed the single box*.
+
+## Anti-patterns
+
+| Bad | Good | Why |
+| --- | --- | --- |
+| Pull fp16 on a box that only fits Q4 | Pull Q4_K_M (or Q8_0 if it fits) | fp16 is 4× the VRAM of Q4 for ~3–5% quality; you'll OOM for nothing |
+| `num_ctx: 128000` on a 12 GB GPU | Cap `num_ctx` to what fits; `OLLAMA_KV_CACHE_TYPE=q8_0` | KV cache scales with context and sits on top of weights — long context dwarfs the model |
+| `/api/generate` for a chat with history | `/api/chat` with a `messages` array | `generate` is single-turn; you'd hand-concatenate history and break the chat template |
+| `ollama pull mistral:latest`, assume it's small | Pin an explicit tag (`:7b`, a quant tag) and `ollama show` it | `:latest` size/quant drifts release to release; sizing breaks silently |
+| Treat Ollama as a multi-tenant prod server | Use it local/single-box; scale → `runpod`/`modal` | one daemon, limited parallelism (`OLLAMA_NUM_PARALLEL`); not built for fleet serving |
+| Hardcode `api.openai.com` when target is local | `base_url="http://localhost:11434/v1"`, dummy key | the OpenAI SDK works unchanged against the compat layer; no remote calls, no key leak |
+| Downgrade to Q2 to force a 70B onto 12 GB | Pick a model that fits, or move to a remote GPU | sub-Q4 quality drops sharply *and* it still won't fit at real context |
+| Assume `ollama list` means it's loaded | `ollama ps` for memory, `list` for disk | a pulled model uses 0 VRAM until a request loads it |
+
+## Verify
+
+Run `scripts/verify.sh [TARGET]` from your project root (or a dir holding a `Modelfile`). Static by
+default — it needs neither Ollama installed nor a running daemon. It lints a `Modelfile` (FAIL if no
+`FROM`; WARN on unknown instructions or a `num_ctx` so high it will OOM consumer GPUs), notes whether
+app code points at the local `localhost:11434` / `/v1` endpoint vs only-remote hosts, and — only if
+`ollama` is on PATH — best-effort confirms a model is present (WARN, not FAIL). It exits non-zero
+**only** on a real FAIL; an empty/clean target passes.
+
+## References
+
+- [references/api.md](references/api.md) — full endpoint catalog, request/response field tables,
+  OpenAI-compat path mapping, structured output, tool calling, streaming, embeddings (curl + Python).
+- [references/hardware-sizing.md](references/hardware-sizing.md) — the full quant ladder, VRAM formula
+  derivation, KV-cache math + per-context table, per-model chart, Apple Silicon unified-memory notes,
+  and the env knobs (`OLLAMA_KV_CACHE_TYPE`, `OLLAMA_FLASH_ATTENTION`, `OLLAMA_NUM_PARALLEL`,
+  `OLLAMA_MAX_LOADED_MODELS`) for fitting tight boxes.

package/skills/ollama/evals/README.md

@@ -0,0 +1,9 @@
+# Evals for the `ollama` skill
+
+`cases.yaml` is a routing + capability fixture, not an automated test harness. Run it by hand (or feed
+it to whatever router you use to dispatch skills): for each `should_trigger` prompt, confirm the router
+selects `ollama`; for each `should_not_trigger` prompt, confirm it routes to the named sibling
+(`runpod`, `modal`, `huggingface`, `rag`, `prompt-engineering`) and not here. For the `capability`
+case, have the skill answer the scenario and check the response covers every bullet in `must_include`.
+No models, GPUs, or external services are required — this is purely about whether the skill fires in
+the right situations and produces a complete, correct local-Ollama answer.

package/skills/ollama/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: ollama
+
+should_trigger:
+  - prompt: "How do I run Llama 3.3 70B locally with Ollama?"
+    why: Core local-serve request — pull/run a named model on this machine.
+  - prompt: "My Ollama model keeps OOMing once the conversation gets long — how do I fix it?"
+    why: Non-obvious — the cause is KV-cache growth with context; fix is num_ctx cap / OLLAMA_KV_CACHE_TYPE / smaller model, all owned here.
+  - prompt: "Write a Modelfile that gives qwen3 an 8k context and a terse system prompt."
+    why: Modelfile authoring (FROM + SYSTEM + PARAMETER num_ctx) plus ollama create.
+  - prompt: "Point my OpenAI Python SDK at a local model instead of api.openai.com."
+    why: OpenAI-compat layer at localhost:11434/v1 with a dummy key — a non-obvious 'it just works' path.
+  - prompt: "Quina quantització (Q4 o Q8) i quin model caben a la meva RTX 3060 de 12GB?"
+    why: Catalan; quant choice + VRAM sizing for a specific GPU, the heart of the skill.
+  - prompt: "Convert this GGUF file into an Ollama model and quantize it to Q4_K_M."
+    why: FROM ./model.gguf import plus ollama create --quantize q4_K_M.
+  - prompt: "ejecutar un LLM en local sin API key, totalmente offline"
+    why: Spanish; the local/offline/no-key framing that defines Ollama's niche.
+
+should_not_trigger:
+  - prompt: "Deploy this model on a serverless GPU endpoint that autoscales with traffic."
+    route_to: modal
+    why: Managed/serverless autoscaled serving — Ollama is single-box, no autoscale.
+  - prompt: "Rent a GPU in the cloud to serve a 70B model behind an HTTP endpoint."
+    route_to: runpod
+    why: Remote/managed GPU rental and serving, not local inference.
+  - prompt: "Download the Llama weights and a fine-tuning dataset from the Hub with the hf CLI."
+    route_to: huggingface
+    why: Weights/dataset/repo management — Ollama imports a result, it doesn't manage the Hub.
+  - prompt: "Build a retrieval pipeline that chunks PDFs and reranks before calling the model."
+    route_to: rag
+    why: Retrieval/chunking/reranking design; the model is the downstream consumer.
+  - prompt: "Help me write a better system prompt for tone and refusal behavior."
+    route_to: prompt-engineering
+    why: Prompt content authoring, not model serving or hardware.
+
+capability:
+  - scenario: "I have an RTX 4070 with 12GB VRAM. I want a coding assistant running locally via Ollama, called from a Python app, with a custom 16k-context system prompt."
+    must_include:
+      - Recommends a model size + quant that fits ~12 GB (e.g. 7B–14B at Q4_K_M) with the sizing reasoning (weights ≈ params × bytes/param × 1.2).
+      - Warns that a 16k context adds KV cache on top of weights; suggests PARAMETER num_ctx 16384 and OLLAMA_KV_CACHE_TYPE=q8_0 if tight.
+      - Gives a Modelfile (FROM + SYSTEM + PARAMETER num_ctx 16384) and the ollama create command.
+      - Shows calling it from Python — native /api/chat or the OpenAI-compat /v1 with base_url http://localhost:11434/v1 and a dummy key.
+      - Names the boundary — if it doesn't fit or needs scale, move to runpod/modal.