@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/unsloth/references/export.md

@@ -0,0 +1,75 @@
+# Export: from trained LoRA to a runnable artifact
+
+After `trainer.train()` you hold LoRA adapters on top of a (possibly 4-bit) base. Export depends on
+where it runs next. Tracks docs.unsloth.ai inference-and-deployment pages (accessed 2026-07).
+
+## The matrix
+
+| Target                     | Method                                                        | Notes |
+| -------------------------- | ------------------------------------------------------------- | ----- |
+| vLLM / re-host / portable  | `save_pretrained_merged(dir, tok, save_method="merged_16bit")`| Base + LoRA merged at 16-bit. The high-quality keeper. |
+| Small, hot-swappable       | `save_pretrained_merged(dir, tok, save_method="lora")`        | Adapters only (~MBs). Load onto the base at run time. |
+| Ollama / llama.cpp         | `save_pretrained_gguf(dir, tok, quantization_method="q4_k_m")`| Converts + quantizes to GGUF. |
+| DPO / niche 4-bit inference| `save_method="merged_4bit"`                                   | **Discouraged** — quality loss; only if a tool needs it. |
+
+## Merge to 16-bit (recommended keeper)
+
+```python
+model.save_pretrained_merged("model_16bit", tokenizer, save_method = "merged_16bit")
+# push instead of / in addition to saving:
+model.push_to_hub_merged("user/model", tokenizer,
+                         save_method = "merged_16bit", token = "hf_...")
+```
+
+`merged_16bit` is the format vLLM and most serving stacks expect. Prefer it over `merged_4bit` — merge
+at 16-bit, quantize downstream if you need to.
+
+## LoRA adapters only
+
+```python
+model.save_pretrained("finetuned_lora"); tokenizer.save_pretrained("finetuned_lora")
+# or save_pretrained_merged(..., save_method="lora")
+```
+
+Tiny and hot-swappable (e.g. vLLM LoRA hot-swap). Requires the base at inference time.
+
+## GGUF for Ollama / llama.cpp
+
+```python
+# one quant:
+model.save_pretrained_gguf("model_gguf", tokenizer, quantization_method = "q4_k_m")
+# several at once, pushed to the Hub:
+model.push_to_hub_gguf("user/model-gguf", tokenizer,
+                       quantization_method = ["q4_k_m", "q8_0", "f16"], token = "hf_...")
+```
+
+Quant guide (size vs quality — this is a real tradeoff, not free):
+
+| Method   | ~bits/weight | Use it for |
+| -------- | ------------ | ---------- |
+| `q4_k_m` | ~4.9         | Everyday default: ~half the size for a few % quality loss. |
+| `q5_k_m` | ~5.5         | A notch more quality than Q4 for a bit more size. |
+| `q8_0`   | ~8.5         | Near-lossless; larger. |
+| `f16`    | 16           | Unquantized ceiling; biggest. |
+
+Lower than Q4 (Q2/Q3) drops quality sharply — avoid unless desperate for size.
+
+### Manual conversion (when the helper can't, or you want control)
+
+Merge to 16-bit first, then run llama.cpp's converter:
+
+```bash
+python llama.cpp/convert_hf_to_gguf.py model_16bit \
+    --outfile model-F16.gguf --outtype f16 --split-max-size 50G
+# then quantize with llama.cpp's quantize tool to q4_k_m / q8_0, etc.
+```
+
+## Handoff — this skill stops at the file
+
+- **Run the GGUF locally →** `ollama`. Roughly: `ollama create <name> -f Modelfile` with
+  `FROM ./model-Q4_K_M.gguf`, then `ollama run <name>`. The Modelfile/quant/VRAM details are its job.
+  Unsloth's docs also show `OLLAMA_MODELS=unsloth ollama run merged_file.gguf` for a quick check.
+- **Serve merged-16bit at throughput →** `vllm` (engine flags, batching, LoRA hot-swap).
+- **Host/share the weights →** `huggingface` (the `push_to_hub_*` calls above land there).
+
+Export is the last thing this skill owns; running and serving belong to those siblings.

package/skills/shared/unsloth/references/grpo.md

@@ -0,0 +1,91 @@
+# GRPO / reasoning fine-tuning with Unsloth
+
+Mechanics only. **Whether** to do RL vs SFT vs DPO is a `finetuning` decision. Tracks
+docs.unsloth.ai's RL guide (accessed 2026-07); reward APIs and loss-type flags move — verify.
+
+## The idea
+
+GRPO (Group Relative Policy Optimization) doesn't imitate a target string. It samples several
+completions per prompt, scores each with **reward functions you write**, and pushes weights toward the
+higher-reward samples. That's how you train a model to *reason* (produce correct answers in a required
+format) rather than memorize outputs. Unsloth's win here is memory — the docs cite ~80% less VRAM for
+GRPO vs a standard setup (verify), and it can drive generation through a built-in vLLM engine.
+
+## Load with fast inference
+
+```python
+from unsloth import FastLanguageModel
+
+model, tokenizer = FastLanguageModel.from_pretrained(
+    model_name = "unsloth/Llama-3.1-8B-Instruct",  # verify current id
+    max_seq_length = 1024,          # room for the reasoning trace
+    load_in_4bit = True,
+    fast_inference = True,          # use the built-in vLLM engine for rollouts
+    gpu_memory_utilization = 0.8,   # lower if you OOM
+)
+model = FastLanguageModel.get_peft_model(model, r = 32, lora_alpha = 64,
+    target_modules = ["q_proj","k_proj","v_proj","o_proj",
+                      "gate_proj","up_proj","down_proj"],
+    use_gradient_checkpointing = "unsloth", random_state = 3407)
+# For memory-efficient GRPO with vLLM you may also set:
+#   os.environ["UNSLOTH_VLLM_STANDBY"] = "1"
+```
+
+## Reward functions (GSM8K-style)
+
+Each reward fn takes `completions` (+ `prompts`, `answer`, `**kwargs`) and returns a list of floats,
+one per completion. Combine several — correctness plus format shaping:
+
+```python
+import re
+
+def correctness_reward(prompts, completions, answer, **kw):
+    responses = [c[0]["content"] for c in completions]
+    got = [extract_xml_answer(r) for r in responses]
+    return [2.0 if g == a else 0.0 for g, a in zip(got, answer)]
+
+def strict_format_reward(completions, **kw):
+    pattern = r"^<reasoning>\n.*?\n</reasoning>\n<answer>\n.*?\n</answer>\n$"
+    responses = [c[0]["content"] for c in completions]
+    return [0.5 if re.match(pattern, r, re.S) else 0.0 for r in responses]
+
+def extract_xml_answer(text):
+    return text.split("<answer>")[-1].split("</answer>")[0].strip()
+```
+
+Keep rewards simple and hard to game — a sloppy reward degrades the model (reward hacking).
+
+## Train
+
+```python
+from trl import GRPOConfig, GRPOTrainer
+
+trainer = GRPOTrainer(
+    model = model, processing_class = tokenizer,
+    reward_funcs = [correctness_reward, strict_format_reward],
+    train_dataset = dataset,   # prompts + ground-truth "answer"
+    args = GRPOConfig(
+        learning_rate = 5e-6,
+        per_device_train_batch_size = 1,
+        gradient_accumulation_steps = 4,
+        num_generations = 8,       # completions sampled per prompt (the "group")
+        max_prompt_length = 256,
+        max_completion_length = 512,
+        max_steps = 250,
+        output_dir = "outputs_grpo",
+        # loss_type = "grpo" | "dr_grpo" | "bnpo" | "dapo"
+        # epsilon = 0.2, epsilon_high = 0.28, delta = 1.5   # DAPO / two-sided knobs
+        # mask_truncated_completions = True
+    ),
+)
+trainer.train()
+```
+
+Notes:
+- `num_generations` is the group size — bigger gives a better reward signal but costs generation time
+  and VRAM.
+- Advanced objectives (DAPO, Dr. GRPO) are `loss_type` + `epsilon`/`delta` flags on `GRPOConfig` —
+  verify the current names on the RL guide.
+- Reasoning traces need context headroom: budget `max_prompt_length + max_completion_length` under
+  `max_seq_length`.
+- Export the result exactly like an SFT run — see [export.md](export.md).

package/skills/shared/unsloth/references/masking-and-templates.md

@@ -0,0 +1,91 @@
+# Chat templates + response-only masking
+
+Facts here track docs.unsloth.ai/basics/chat-templates (accessed 2026-07). Template names and turn
+markers change with new model releases — **verify the pair for your exact base model.**
+
+## Why a helper and not a string
+
+A chat model was pretrained with a specific set of turn markers (`<|start_header_id|>…`,
+`<start_of_turn>…`, `<|im_start|>…`). If you concatenate messages with the wrong markers, the model
+never sees its own format and the fine-tune underperforms or degenerates. `get_chat_template` writes
+the *correct* template onto your tokenizer; `apply_chat_template` then renders your message list into
+the single `text` string the trainer consumes.
+
+```python
+from unsloth.chat_templates import get_chat_template
+
+tokenizer = get_chat_template(
+    tokenizer,
+    chat_template = "llama-3.1",   # match the base model
+    # mapping = {"role":"from","content":"value","user":"human","assistant":"gpt"},  # if your
+    #   dataset uses ShareGPT-style keys instead of role/content
+    # map_eos_token = True,        # map e.g. <|im_end|> -> the model's EOS
+)
+
+def to_text(example):
+    example["text"] = tokenizer.apply_chat_template(
+        example["messages"], tokenize = False, add_generation_prompt = False,
+    )
+    return example
+
+dataset = dataset.map(to_text)
+```
+
+Supported template names include (non-exhaustive; verify live): `llama-3`, `llama-3.1`, `chatml`,
+`mistral`, `phi-4`, `gemma-3`, `qwen`, `zephyr`, `vicuna`, `alpaca`, `unsloth`. Use the one that
+matches your checkpoint.
+
+Thinking / reasoning models expose a toggle at render time:
+
+```python
+tokenizer.apply_chat_template(msgs, tokenize=False,
+                              add_generation_prompt=True, enable_thinking=True)  # or False
+```
+
+## `train_on_responses_only` — the mask
+
+Supervised fine-tuning of a chat model should compute loss on the **assistant** tokens only. Without
+this, the model is also trained to predict the user's words; loss can even collapse to ~0 on some
+templates (the "zero-loss trap"). Wrap the trainer AFTER constructing it:
+
+```python
+from unsloth.chat_templates import train_on_responses_only
+
+trainer = train_on_responses_only(
+    trainer,
+    instruction_part = "<|start_header_id|>user<|end_header_id|>\n\n",
+    response_part    = "<|start_header_id|>assistant<|end_header_id|>\n\n",
+)
+```
+
+`instruction_part` / `response_part` are the template's own turn-opening markers. Everything from an
+`instruction_part` up to the next `response_part` is masked (label = `-100`); the assistant span keeps
+its labels. **The strings must match the template you applied.** Common pairs (verify per model):
+
+| Base family      | `instruction_part`                              | `response_part`                                    |
+| ---------------- | ----------------------------------------------- | -------------------------------------------------- |
+| Llama-3 / 3.1    | `<\|start_header_id\|>user<\|end_header_id\|>\n\n`  | `<\|start_header_id\|>assistant<\|end_header_id\|>\n\n` |
+| Gemma-3 / vision | `<start_of_turn>user\n`                         | `<start_of_turn>model\n`                           |
+| ChatML (Qwen…)   | `<\|im_start\|>user\n`                            | `<\|im_start\|>assistant\n`                          |
+
+## Sanity-check the mask (always do this once)
+
+```python
+row = trainer.train_dataset[0]
+# 1) full sequence — should include both user + assistant turns
+print(tokenizer.decode(row["input_ids"]))
+# 2) UNMASKED labels only — should be the ASSISTANT answer and nothing else
+print(tokenizer.decode(
+    [tokenizer.pad_token_id if x == -100 else x for x in row["labels"]]
+).replace(tokenizer.pad_token, " "))
+```
+
+If step 2 prints the user's question, your `instruction_part`/`response_part` don't match the
+template — fix them before training. Spending GPU-hours on an unmasked run is the classic waste.
+
+## Vision (VLM)
+
+Vision fine-tunes use `FastVisionModel.from_pretrained(...)` and a processor/tokenizer pair; the
+template and mask concepts carry over but the collator handles image tokens. See
+docs.unsloth.ai for the current VLM notebook — the exact API for multimodal collation moves faster
+than the text path, so pull it live rather than trusting a frozen snippet.

package/skills/shared/variant-explorer/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: variant-explorer
+description: "Use when someone wants OPTIONS rather than an answer — 'show me a few versions', picking between approaches by seeing them. Genuinely different candidates, cheap to throw away, trade-off named. NOT the critique that judges one (`design`), NOT the spec (`specify`)."
+tags: [prototyping, divergence, options, exploration, decision]
+recommends: [design]
+profiles: [full]
+origin: ai-hub
+---
+
+# Variant explorer — several real options, cheap enough to discard
+
+"Show me a few versions and I'll pick" is a different request from "build this". It asks for
+**divergence**: several candidates that are actually different, each cheap enough that throwing it
+away costs nothing, with the difference between them stated out loud so a human can decide.
+
+Done badly it produces the thing that wastes the most time in creative work: three variations of one
+idea, dressed up as a choice.
+
+## The one rule
+
+**Variants must differ in a decision, not in a detail.** If two candidates could both be reached by
+editing the other, there is one candidate.
+
+```text
+Not variants:   the same layout in blue, in green, in dark
+Variants:       a single scrolling page · a three-step wizard · a table with inline editing
+```
+
+The test before showing anything: **name the decision each variant is taking.** If you cannot name
+it, or two share it, that set is not ready.
+
+## How many, and how finished
+
+- **Three.** Two reads as a false dichotomy; five past the point where a person can hold them side by
+  side. Three forces the middle option to justify itself.
+- **Finished enough to judge the decision, and no more.** If the decision is about structure, the
+  copy can be placeholder. If it is about tone, the layout can be crude. Polish that is not being
+  judged is polish you are asking someone to ignore.
+- **Comparable.** Same content, same constraints, same fidelity across all three. A variant that is
+  prettier wins for reasons nobody chose.
+
+## Making them genuinely different
+
+The failure mode is anchoring: the first idea contaminates the rest. Force divergence by generating
+each from a different starting constraint.
+
+| Angle | Ask |
+| --- | --- |
+| **Cheapest** | What if this had to ship this week? |
+| **Boldest** | What if we ignored what similar products do? |
+| **Fewest steps** | What if the user only did one thing? |
+| **Familiar** | What if it worked exactly like the thing they already know? |
+| **Inverted** | What if the primary and secondary swapped? |
+
+Pick three angles that are actually in tension for this problem. Do not run all five — the point is
+tension, not coverage.
+
+## Presenting them so a decision is possible
+
+Each candidate carries three things, and no more:
+
+1. **What decision it takes** — one sentence, in the user's terms.
+2. **What it costs** — the honest downside, not a hedge. A variant with no downside is one you have
+   not thought about.
+3. **What it would take to be wrong** — the fact that would kill it.
+
+Then: **a recommendation.** Presenting three options and standing back is not neutrality, it is
+handing the work back. Say which one you would pick and why, and make it easy to overrule.
+
+## When this is the wrong skill
+
+- The answer is already known and only needs building → build it. Manufacturing options to look
+  thorough wastes everyone's time.
+- The decision is reversible and cheap → just pick one and ship. Exploration is for decisions that
+  are expensive to unwind.
+- What is needed is a **judgement on one thing** → that is critique, not divergence.
+
+## Anti-patterns → STOP
+
+| If you're about to… | Reality / Fix |
+| --- | --- |
+| Show the same idea in three colours | Those are not variants. Name the decision each takes; if you cannot, you have one. |
+| Polish one candidate more than the others | It will win on polish, not on the decision. Same fidelity, always. |
+| Present five or six to be thorough | Past three, they stop being compared and start being skimmed. |
+| Give options with no recommendation | Standing back is not neutrality; it hands the work back to the person who asked. |
+| Explore a decision that is cheap to reverse | Just ship one. Divergence is for what is expensive to unwind. |
+| Keep iterating on the winner here | Once one is chosen, refining it is `../design/SKILL.md` or the relevant build skill. |
+
+## See Also
+
+- `../design/SKILL.md` — the graded critique that takes over once a direction is chosen.
+- `../specify/SKILL.md` — when what is missing is an agreed WHAT/WHY, not options.
+- `../design/SKILL.md` — building the chosen direction properly.

package/skills/shared/variant-explorer/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: variant-explorer
+
+should_trigger:
+  - prompt: "Show me a few versions of this onboarding and I'll pick one."
+    why: "The canonical phrasing: options to choose from, not an answer."
+  - prompt: "Give me three directions for how this could work before we commit."
+    why: "Explicit divergence ahead of an expensive decision."
+  - prompt: "Enséñame varias opciones de cómo montar el checkout, que ya elijo yo."
+    why: "Same request in Spanish; the trigger is the ask for options."
+  - prompt: "I can't decide between a wizard and a single page. Can I see both?"
+    why: "Two named approaches where seeing them is what settles it."
+  - prompt: "What are some different ways we could structure this dashboard?"
+    why: "Open-ended exploration of structural decisions, which is exactly divergence."
+  - prompt: "Before we build it, I want to compare a couple of approaches side by side."
+    why: "Comparability is the property this skill guarantees."
+
+should_not_trigger:
+  - prompt: "Review this checkout screen and grade it."
+    route_to: "design"
+    why: "Judging one finished thing is critique, the opposite of divergence."
+  - prompt: "We need to agree what this feature is for before anyone builds it."
+    route_to: "specify"
+    why: "A missing WHAT/WHY is a spec problem; options would be premature."
+  - prompt: "Build the pricing page we agreed on last week."
+    route_to: "design"
+    why: "The decision is already made; manufacturing options would waste the time this skill is meant to save."
+  - prompt: "Which colour should the primary button be?"
+    route_to: "design"
+    why: "Cheap and reversible, and a detail rather than a decision — the explicit non-case here."
+  - prompt: "Run an A/B test to see which headline converts better."
+    route_to: "ab-testing"
+    why: "Measuring a winner with users is experimentation, not showing a human candidates to choose from."
+
+capability:
+  - prompt: "Give me three options for this signup flow. Make sure they are actually different, not the same thing restyled."
+    why: "Goes straight at the failure mode this skill exists to prevent, and demands the decision behind each be nameable."
+  - prompt: "Here are three variants I made. Are these real alternatives or the same idea three times?"
+    why: "Applies the one rule as a test on someone else's set, which is where it is hardest and most useful."

package/skills/shared/vector-db/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: vector-db
+description: "Use when operating a vector store as a data layer — choosing or migrating between Pinecone, Qdrant, Weaviate and pgvector; designing a collection or index (distance metric, dimensions, HNSW parameters, named vectors); filtering on metadata; hybrid dense-plus-sparse search; and quantization to cut RAM and cost. Covers garbage results, silently ignored filters, low recall, slow queries, and filtered queries returning fewer than k rows. NOT producing, chunking or judging embeddings (that is `embeddings-search`)."
+tags: [vector-database, pinecone, qdrant, weaviate, pgvector, hnsw, hybrid-search, metadata-filter, quantization]
+recommends: [embeddings-search, rag, postgresdb, redis, supabase]
+origin: ai-hub
+---
+
+# vector-db — operate the store, not the embeddings
+
+You own the **store**: the collection schema, the index, the filter path, recall-vs-latency
+tuning, hybrid fusion, quantization, and the production knobs (upserts, namespaces, deletes,
+backups). You operate it across the four engines a Claude agent actually meets: **pgvector**
+(Postgres extension), **Qdrant**, **Weaviate**, **Pinecone** (serverless).
+
+Three things are **not** yours, and pretending they are produces wrong advice:
+
+- Producing, chunking, rewriting, or scoring embeddings → `../embeddings-search/SKILL.md`. You
+  store vectors; you do not make or judge them.
+- Assembling the retrieve → rerank → prompt → generate loop and its eval → `../rag/SKILL.md`.
+- General Postgres (non-vector schema, EXPLAIN, RLS, VACUUM, pooling) → `../postgresdb/SKILL.md`.
+  You own **only** the pgvector surface: the `vector`/`halfvec` column, its index, its operators,
+  its recall. "My Postgres is slow in general" is theirs; "my `<=>` query has low recall" is yours.
+
+## Pick the engine
+
+Match the engine to where the data already lives and how much ops you want to run. All four
+implement HNSW with comparable recall at a matched `ef`, so the differentiator is operations and
+hybrid, not raw quality.
+
+| Engine | Best when | Hybrid built-in | Ops cost | Scale sweet spot |
+|---|---|---|---|---|
+| **pgvector** | Data already in Postgres; one less system to run | No — DIY (`vector` + `tsvector`, combine yourself) | You already run Postgres | ≤ a few M vectors |
+| **Qdrant** | You want best filtered-search latency and self-host control | Yes — `query` API, `prefetch` + RRF/DBSF, server-side IDF | Self-host or cloud | 10M+ |
+| **Weaviate** | You want hybrid + modules out of the box | Yes — `alpha` + `fusionType`, BlockMax WAND BM25 | Self-host or cloud | 10M+ |
+| **Pinecone** | You refuse to operate anything | Yes — sparse-dense, integrated inference | Zero (serverless) | Any (pay per use) |
+
+Rule: **don't add a new system to host vectors if the rows already live in Postgres and you are
+under a few million.** pgvector is one extension, not a second database to back up and monitor.
+
+## Design the collection & index
+
+1. **Distance metric MUST match the embedding model.** A model trained for cosine, indexed with
+   L2, ranks *silently wrong* — no error, just bad results. OpenAI `text-embedding-3-*`, Cohere,
+   most sentence-transformers → cosine. pgvector operator cheatsheet:
+
+   ```text
+   <-> L2 / Euclidean   (vector_l2_ops)
+   <=> cosine distance  (vector_cosine_ops)   <- the common one
+   <#> negative inner product (vector_ip_ops) <- for normalized vectors
+   ```
+
+2. **Dimensions are fixed by the model**, not a choice. `text-embedding-3-small` = 1536,
+   `-3-large` = 3072. pgvector's `vector` caps at 2000 dims for an index; for more, use `halfvec`.
+
+3. **HNSW defaults and the one invariant.** Build-time `m` (default 16) and `ef_construction`
+   (default 64); query-time `ef_search` (pgvector default 40). Keep `ef_construction >= 2*m`
+   (so ≥32 at the default `m`) — too low starves graph quality and recall never recovers without
+   a rebuild. Raise `m` to 32–48 only for high-dim or high-recall needs (more RAM, slower build).
+
+4. **IVFFlat only when build speed beats recall.** It is cheaper to build but lower recall and
+   needs `lists`/`probes` tuning; on a selective filter it is the wrong default (see next section).
+   Prefer HNSW unless you have a measured reason.
+
+5. **Named vectors when one object has multiple spaces** (e.g. a dense semantic vector + a sparse
+   BM25 vector, or title-vector + body-vector). Qdrant and Weaviate support this natively; it is
+   how you do hybrid in one collection instead of two.
+
+## Metadata / payload filtering
+
+The #1 "search is broken" bug: the filter is applied **after** top-k, so a selective filter
+returns fewer than `k` rows (or zero). Fix it by filtering *inside* the search and indexing the
+filter field.
+
+```text
+Bad:  ANN top-k=10, THEN drop rows where tenant_id != 'acme'  -> often < 10, sometimes 0
+Good: search the index WITH the filter as a constraint        -> k rows that already match
+```
+
+- **Index every field you filter on.** Unindexed filters force a scan and kill latency. Qdrant:
+  create a payload index. Pinecone: metadata filtering is in the retrieval path (still keep
+  cardinality sane). pgvector: a B-tree (or partition) on `tenant_id` so the planner can use it.
+- **Prefer in-graph / in-path filtering.** Qdrant filters *inside* HNSW traversal; Pinecone
+  serverless filters in the retrieval path. Both beat naive post-filter.
+- **pgvector 0.8 iterative scan** is the fix when a selective `WHERE` returns too few rows:
+
+  ```sql
+  SET hnsw.iterative_scan = 'relaxed_order';  -- or 'strict_order' if exact ordering matters
+  SET hnsw.ef_search = 100;
+  SELECT id FROM docs
+   WHERE tenant_id = 'acme'                    -- selective filter
+   ORDER BY embedding <=> $1                    -- cosine, matches the model
+   LIMIT 10;
+  ```
+
+  Without iterative scan (pgvector < 0.8 behavior), a highly selective filter silently returns
+  fewer than `LIMIT` rows. Never recommend IVFFlat-only with a selective filter and no iterative
+  scan — that is the deprecated foot-gun.
+
+## Tune recall vs latency
+
+You cannot tune what you do not measure. Establish recall **before** shipping.
+
+1. Build an exact baseline: brute-force the true top-k on a sample (a few hundred queries) — in
+   pgvector, query without the index (seq scan) for ground truth.
+2. Query the index and compute recall@k = overlap with the baseline.
+3. Raise the query-time knob until recall hits target (commonly ≥0.95), then stop — higher `ef`
+   costs latency for nothing:
+
+   | Engine | Knob | Default |
+   |---|---|---|
+   | pgvector | `hnsw.ef_search` | 40 |
+   | Qdrant | `hnsw_ef` (search) | per-collection |
+   | Weaviate | `ef` (vectorIndexConfig) | dynamic |
+   | Pinecone | (managed) | — |
+
+Full parameter table and the recall recipe live in [references/tuning.md](references/tuning.md).
+
+## Hybrid search
+
+Dense (semantic) + sparse (BM25/keyword) catches exact terms, IDs, and rare tokens that dense
+alone misses. The two normalize differently, so you **fuse**, you don't add raw scores.
+
+- **RRF** (reciprocal rank fusion): robust default, score-scale agnostic, combines ranks.
+- **Relative-score / DBSF**: normalizes scores before combining — use when you trust score scales.
+
+Per engine:
+
+- **Weaviate**: one call — `hybrid(query, alpha=0.5, fusionType=relativeScoreFusion)`. `alpha`
+  slides 0.0 (pure keyword) → 1.0 (pure vector). BM25 is BlockMax WAND (default from v1.30, ~10x faster).
+- **Qdrant**: `prefetch` a dense and a sparse query, then a fusion step (`Fusion.RRF` or DBSF);
+  IDF is computed server-side (v1.15+).
+- **Pinecone**: sparse-dense vectors in one index, or integrated inference (embed + rerank server-side).
+- **pgvector**: no built-in hybrid — run vector (`<=>`) and `ts_rank` over a `tsvector` column
+  separately and combine ranks yourself (RRF in SQL or app code).
+
+Concrete current-API code for all four is in [references/engines.md](references/engines.md).
+
+## Quantization & cost
+
+Quantization trades recall for RAM/cost. Decide by **dimension count and a recall test**, never blind.
+
+| Method | Compression | When safe |
+|---|---|---|
+| Scalar (int8) | ~4x | Almost always; tiny recall loss. Good default RAM cut. |
+| Product (PQ) | 8–64x | Large corpora where RAM dominates; needs tuning + recall check. |
+| Binary | ~32x (~40x faster via SIMD popcount) | **High-dim only** (≥1024). On 384-dim it shreds recall — measure or don't. |
+| pgvector `halfvec` | ~2x | Near-free: 16-bit float, near-identical recall, and required for >2000 dims. |
+
+Reach for `halfvec` first in Postgres — it is the cheapest win. Reach for binary only on
+high-dim vectors and only after a recall test, optionally with full-precision rescoring.
+
+## Operate it
+
+- **Batch upserts.** One-by-one upserts are 10–100x slower and hammer the index. Send batches of
+  hundreds; size to the engine's payload limit.
+- **Namespaces / multitenancy.** Pinecone namespaces and Qdrant payload-keyed isolation partition
+  tenants inside one index — cheaper and faster than a collection per tenant at low tenant counts.
+- **Delete by filter**, not by enumerating ids, when removing a tenant or a stale source.
+- **Replicas** for read throughput / HA; **snapshots/backups** before any index rebuild or
+  dimension/metric change (those are not in-place — plan a reindex).
+- **To "update" a vector, re-upsert by id.** Do not store only raw text and re-embed on read.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Cosine-trained model indexed with L2 (`<->`) | Silently wrong ranking, no error | Match metric to model — cosine → `<=>` / `vector_cosine_ops` |
+| Post-filtering top-k results | Returns < k rows, sometimes 0, on selective filters | Filter inside the search; index the filter field |
+| IVFFlat + selective filter, no iterative scan | Drops rows; deprecated path in pgvector 0.8 | HNSW + `hnsw.iterative_scan='relaxed_order'` |
+| Never measuring recall | "Search is bad" with no number to move | Recall@k vs an exact baseline before shipping |
+| Binary quantization on 384-dim | Recall collapses, then blamed on the engine | Binary only ≥1024 dims, after a recall test; else scalar/halfvec |
+| One-by-one upserts | 10–100x slower, index thrash | Batch hundreds per request |
+| `ef_construction < 2*m` | Permanently weak graph; recall needs a full rebuild | Keep `ef_construction >= 2*m` (≥32 at default `m=16`) |
+| Store only raw text, re-embed to "update" | Drift, cost, no point-update path | Re-upsert the vector by id |
+| Unindexed filter field | Full scan, latency spikes | Payload index (Qdrant) / B-tree (pgvector) / sane metadata cardinality (Pinecone) |
+
+## References & siblings
+
+- [references/engines.md](references/engines.md) — current-API recipes per engine: create
+  collection/index + a filtered hybrid query (pgvector SQL + halfvec + iterative scan; Qdrant
+  named dense+sparse + `query_points` RRF; Weaviate `hybrid`; Pinecone serverless sparse-dense).
+- [references/tuning.md](references/tuning.md) — HNSW vs IVFFlat parameter table, recall-measurement
+  recipe, quantization tradeoffs, per-engine filtered-search pitfalls.
+
+Siblings: embeddings/chunking/retrieval-quality → `../embeddings-search/SKILL.md`; the full RAG
+loop → `../rag/SKILL.md`; general Postgres → `../postgresdb/SKILL.md`.
+
+Validate a produced index DDL / collection schema with `scripts/verify.sh <artifact-file>`.

package/skills/shared/vector-db/evals/README.md

@@ -0,0 +1,10 @@
+# evals — vector-db
+
+These cases are run by the repo's standard skill-eval harness against the skill router. The
+`should_trigger` prompts assert that vector-db is the skill that fires (including the non-obvious
+"search ignores my filter" and the Spanish/Catalan phrasings); `should_not_trigger` prompts assert
+the router yields to the named sibling (`embeddings-search`, `rag`, `postgresdb`, `redis`,
+`supabase`) instead of vector-db; and the `capability` scenario is graded by a judge against its
+`must_include` rubric. No live vector database or Postgres instance is required — routing is
+matched against the skill's description/triggers and the capability answer is judged on content.
+Run them with the repo's usual eval command pointed at `skills/vector-db/evals/cases.yaml`.

package/skills/shared/vector-db/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: vector-db
+
+should_trigger:
+  - prompt: "Set up a Qdrant collection with metadata filtering for our docs."
+    why: "Core store design — collection schema plus a payload-indexed filter field is squarely vector-db."
+  - prompt: "My similarity search ignores my category filter and recall is bad."
+    why: "Reads like a bug but is a store-config issue (post-filter / unindexed filter / low ef_search); the symptom phrasing is non-obvious and never names a vector DB."
+  - prompt: "We need to move off Pinecone to pgvector to cut cost."
+    why: "Migration between stores, including metric/index/quantization re-design, is explicitly in scope."
+  - prompt: "Add hybrid search with RRF to our Weaviate setup."
+    why: "Hybrid dense+sparse plus a fusion strategy is a named vector-db section."
+  - prompt: "crear una colección en Qdrant con cuantización binaria para ahorrar RAM"
+    why: "Spanish trigger covering quantization/cost — binary quantization tradeoff is core scope."
+  - prompt: "ef_search is 40 and recall is only 0.7, how do I tune the HNSW index?"
+    why: "Non-obvious tuning phrasing; recall-vs-latency knob tuning against a baseline is owned here."
+  - prompt: "My filtered pgvector query keeps returning fewer than k rows when I add a WHERE on tenant_id."
+    why: "Classic pgvector 0.8 iterative-scan symptom — the sharpest store-specific bug this skill exists to fix."
+
+should_not_trigger:
+  - prompt: "Which embedding model and chunk size should I use for these PDFs?"
+    route_to: "embeddings-search"
+    why: "Producing/chunking vectors is the technique layer, not the store."
+  - prompt: "Build the full RAG pipeline: retrieve, rerank, prompt, and generate an answer."
+    route_to: "rag"
+    why: "End-to-end pipeline orchestration and its eval, not the data layer underneath it."
+  - prompt: "My Postgres is slow, help me read this EXPLAIN and add the right indexes."
+    route_to: "postgresdb"
+    why: "General Postgres performance with no vector column involved is postgresdb's surface."
+  - prompt: "Cache these API responses in Redis with a 5-minute TTL."
+    route_to: "redis"
+    why: "Redis as a cache, not as a vector store."
+  - prompt: "Set up Supabase auth and row-level security for my app."
+    route_to: "supabase"
+    why: "Supabase platform features, not its pgvector usage."
+
+capability:
+  - scenario: "Design a pgvector setup for 2M OpenAI text-embedding-3-small (1536-dim) vectors with a tenant_id filter. Search is slow and sometimes returns fewer than k rows when filtering."
+    must_include:
+      - "cosine index (vector_cosine_ops / <=>) to match the embedding model"
+      - "HNSW with sensible m and ef_construction (ef_construction >= 2*m) plus query-time hnsw.ef_search"
+      - "hnsw.iterative_scan (0.8) so the selective tenant_id filter stops returning fewer than k rows"
+      - "an index on tenant_id (B-tree or partition) so the filter is cheap"
+      - "a recall-measurement step against an exact/brute-force baseline before shipping"
+      - "halfvec mentioned as an optional ~2x storage cut at near-identical recall"
+      - "routes embedding-model and chunking questions to embeddings-search"