@ericrisco/rsc 0.1.49 → 0.1.51

package/skills/rag/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rag
-description: "Use when building grounded Q&A over your own documents — handbook, support tickets, PDFs, policies — and the answers must come only from the corpus with citations; when retrieval surfaces the right document but the answer is still wrong; when the model invents facts that are not in the sources; when you need to measure whether retrieval is any good; when the right document is found but the wrong passage is used. Triggers: 'build a bot that answers from our docs with citations', 'my RAG returns the right document but the answer is wrong', 'how do I stop the model hallucinating facts not in the corpus', 'context recall vs context precision', 'add contextual retrieval / prepend chunk context before embedding', 'hybrid search plus rerank pipeline', 'respuestas con citas sobre nuestros documentos', 'el bot s'inventa coses que no surten als documents'. NOT operating the vector store itself — collection schema, HNSW ef_search, quantization (that is vector-db)."
+description: "Use when building grounded Q&A over your own corpus — chunk, retrieve hybrid, rerank, ground, cite chunk ids, refuse when the sources fall short — or when the right document is retrieved but the answer is still wrong, invented, or unmeasured. NOT operating the store itself — collection schema, HNSW ef_search, quantization (that is `vector-db`)."
 tags: [rag, retrieval-augmented-generation, chunking, hybrid-search, reranking, grounding, citations, faithfulness, contextual-retrieval]
 recommends: [vector-db, embeddings-search, document-processing, chatbot, agent-eval]
 origin: risco
@@ -8,15 +8,14 @@ origin: risco
 
 # rag — own the retrieve → rerank → ground → cite → refuse pipeline
 
-You own the **pipeline** that turns a corpus plus a question into a grounded, cited answer.
-You do **not** own the store underneath it (`../vector-db/SKILL.md`) nor the embedding and
-chunk-sizing science beside it (`embeddings-search`). Your job is the glue: chunk, optionally
-contextualize, index, retrieve hybrid, rerank, assemble a grounded prompt, cite the sources,
-and **refuse** when the context does not contain the answer.
+You own the **pipeline** that turns a corpus plus a question into a grounded, cited answer: chunk,
+optionally contextualize, index, retrieve hybrid, rerank, assemble a grounded prompt, cite the
+sources, and **refuse** when the context does not contain the answer.
 
 You are judged by **retrieval quality and answer faithfulness**, not by raw vector math. If you
-find yourself tuning HNSW parameters, you wandered into `vector-db`. If you are comparing
-embedding models or chunk sizes, that is `embeddings-search`.
+find yourself tuning HNSW parameters, you wandered into the store underneath you
+(`../vector-db/SKILL.md`). If you are comparing embedding models or chunk sizes, that is the
+science beside you (`embeddings-search`).
 
 ## The pipeline, and where each stage hands off
 
@@ -25,19 +24,21 @@ delegate to a sibling skill rather than living here.
 
 | Stage | What you do | Hands off to |
 |---|---|---|
-| Ingest | Get clean text out of PDFs/DOCX/HTML/OCR | `../document-processing/SKILL.md` |
-| Chunk | Heading/semantic-aware splits with overlap, stable ids | chunk-size science → `embeddings-search` |
+| Ingest | Get clean text out of PDFs/DOCX/HTML/OCR | you assume text exists → `../document-processing/SKILL.md` |
+| Chunk | Heading/semantic-aware splits with overlap, stable ids | model, dims + chunk-size science → `embeddings-search` |
 | Contextualize | Prepend an LLM-written context blurb per chunk (optional) | stays here |
-| Index | Embed + write dense vectors and a BM25/keyword index | the store → `../vector-db/SKILL.md` |
+| Index | Embed + write dense vectors and a BM25/keyword index | you upsert, it owns the knobs → `../vector-db/SKILL.md` |
 | Retrieve | Hybrid dense + BM25, fuse with RRF, top ~150 | hybrid query mechanics → `../vector-db/SKILL.md` |
 | Rerank | Cross-encoder over the 150, keep top ~20 | stays here |
 | Ground + cite | System prompt: answer only from context, cite chunk ids | stays here |
 | Refuse | Output "I don't have enough information" on weak context | stays here |
 | Evaluate | Faithfulness, answer relevancy, context precision/recall | general harness → `agent-eval` |
 
-Surfacing this answer inside a chat product (sessions, channels, UI) is `../chatbot/SKILL.md`;
-pulling schema-constrained fields out of text is `structured-extraction`. `rag` is the
-retrieval brain those products call.
+Three neighbors are not stages at all. Surfacing this answer inside a chat product (sessions,
+channels, UI) is `../chatbot/SKILL.md` — it calls you, not the reverse. A multi-step tool loop with
+state, where retrieval is one tool among many, is `../building-agents/SKILL.md`. Pulling
+schema-constrained fields out of text instead of a grounded prose answer is
+`structured-extraction`. `rag` is the retrieval brain those products call.
 
 ## Retrieval is the bottleneck — measure recall before touching the prompt
 
@@ -87,8 +88,8 @@ def chunk_markdown(doc_id, text, target=800, overlap=120):
     return out
 ```
 
-For the deep "what window/overlap maximizes recall for *this* corpus" study, that is
-`embeddings-search`. Here you just need structurally sane chunks that keep their ids.
+The "what window/overlap maximizes recall for *this* corpus" study is `embeddings-search`; here you
+just need structurally sane chunks that keep their ids.
 
 ## Contextual retrieval — prepend context before you embed
 
@@ -107,7 +108,8 @@ document for search retrieval. Answer only with the context, nothing else.
 ```
 
 Embed `context + "\n" + chunk_text` (not the bare chunk). The full implementation — caching the
-document prompt, batching, the BM25 side — lives in `references/pipeline.md`.
+document prompt, batching, the BM25 side, and a runnable retrieve → rerank → answer skeleton —
+lives in `references/pipeline.md`.
 
 ## Hybrid retrieval + RRF + rerank
 
@@ -144,8 +146,8 @@ top = [candidates[r.index] for r in ranked.results]  # each still carries chunk_
 
 Properly grounded RAG reduces hallucination rates by up to ~71%; poorly grounded pipelines still
 hallucinate in up to ~40% of responses *even with the right doc retrieved* (Confident AI / Maxim
-2025, accessed 2026-06-02). The prompt must do three non-negotiable things: bind the answer to
-the context, force inline citations, and provide an explicit refusal path.
+2025, accessed 2026-06-02). The prompt must do three things: bind the answer to the context, force
+inline citations, and provide an explicit refusal path.
 
 ```text
 You answer ONLY using the information inside <context>. Do not use prior knowledge.
@@ -205,22 +207,3 @@ the RAG-specific metrics live here.
 | Embedding the query differently from the corpus | Query and chunks land in different spaces | Same model + same preprocessing both sides |
 | Dense-only, ignoring BM25/keyword | Misses exact codes/names/error strings | Hybrid dense + BM25 fused with RRF |
 | Tuning temperature to fix wrong answers | Generation is rarely the bottleneck | Measure context recall first |
-
-## Wiring map
-
-- **Ingestion (file → text, OCR, tables):** `../document-processing/SKILL.md` — you assume text
-  already exists; send raw PDFs/DOCX/scans there first.
-- **The store (collection, index, hybrid query, quantization):** `../vector-db/SKILL.md` — you
-  call it to upsert and query; it owns the knobs.
-- **Embedding model + chunk-size science:** `embeddings-search` — picking the model, dims,
-  cost, and the semantic-vs-fixed chunking experiments.
-- **Chat product surface (sessions, channels, UI):** `../chatbot/SKILL.md` — wraps the answer
-  you return; it calls you, not the reverse.
-- **Multi-step tool/agent loop with state:** `../building-agents/SKILL.md` — when retrieval is
-  one tool among many in a larger loop.
-- **General eval framework:** `agent-eval` — RAG-specific metrics are here; the harness is there.
-- **Schema-constrained field extraction:** `structured-extraction` — when the goal is fields,
-  not a grounded prose answer.
-
-See `references/pipeline.md` for the full runnable retrieve → rerank → answer skeleton and
-`references/evaluation.md` for the metric formulas, thresholds, and CI gate.

package/skills/suggest/SKILL.md

@@ -4,6 +4,7 @@ description: "Always-on. Use whenever the current user turn would clearly benefi
 tags: [suggest, detect, install, meta, always-on]
 recommends: []
 profiles: [minimal, core, full]
+origin: risco
 ---
 
 # rsc-suggest — the always-on layer

package/skills/tauri/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tauri
-description: "Use when building a lightweight cross-platform desktop (or v2 mobile) app with Tauri — a Rust core plus the OS-native WebView — wiring Rust commands and IPC, streaming data to the frontend, locking down the capabilities/permissions security model, or bundling and auto-updating tiny signed binaries. Triggers: 'build a Tauri app', 'expose a Rust command to my frontend', 'invoke from JS', 'tauri.conf.json', 'capabilities and permissions', 'stream download progress to the WebView', 'my command froze the UI', 'shrink my desktop binary vs Electron', 'set up the Tauri updater', 'crear una app d'escriptori lleugera amb Rust en lloc d'Electron', 'reducir el tamaño del binario de escritorio'. NOT a Chromium+Node desktop app that needs Node APIs in a main process (that is electron)."
+description: "Use when building a lightweight cross-platform desktop (or v2 mobile) app with Tauri — a Rust core plus the OS-native WebView: Rust commands and IPC, streaming to the frontend, the default-deny capabilities/permissions ACL, bundling and signed auto-updates. NOT a Chromium+Node shell needing Node APIs in a main process (that is electron)."
 tags: [tauri, desktop, rust, cross-platform, ipc, webview]
 recommends: [rust, electron, react, secure-coding, github-actions]
 origin: risco
@@ -22,7 +22,8 @@ so the same Rust core can ship to mobile.
 
 This skill owns the **shell**: commands, IPC, the security ACL, the bundler, the updater.
 It does **not** own the Rust language itself (that is the `rust` skill), the web UI inside
-the window (the `react`/`nextjs` skills), or a Chromium+Node shell (`../electron/SKILL.md`).
+the window (the `react`/`nextjs` skills), a Chromium+Node shell (`../electron/SKILL.md`), or
+app-code hardening beyond the IPC boundary (`../secure-coding/SKILL.md`).
 
 ## Pick your starting shape
 
@@ -213,12 +214,6 @@ across three OSes is the `github-actions` skill's job; this skill defines what t
 | Copying a v1 `tauri.conf.json > allowlist` | That key does not exist in v2 | Use `capabilities/*.json` (ACL) |
 | Assuming bundled Chromium | It's the **OS** WebView (WebKit/WebView2) | Test rendering on each OS's engine; avoid Chromium-only CSS/JS |
 
-## Pointers
-
-- `references/security.md` — capabilities/permissions/scope JSON, CSP recipes, isolation setup.
-- `references/bundling-distribution.md` — per-OS signing, updater keypair, sidecar, CI matrix.
-- Siblings: `../electron/SKILL.md` (the Chromium+Node alternative when you need a Node main
-  process), `../secure-coding/SKILL.md` (app-code hardening). The `rust` skill owns the
-  language; `react`/`nextjs` own the frontend UI; `github-actions` owns the release CI matrix.
-- `scripts/verify.sh` — advisory static lint over `src-tauri/` (capabilities present, registered
-  commands exist, no v1 `allowlist`, fallible-looking commands return `Result`).
+`scripts/verify.sh` is an advisory static lint over an `src-tauri/` tree that catches several of
+these: capabilities present, registered commands exist, no v1 `allowlist`, fallible-looking
+commands return `Result`.

package/skills/webhooks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: webhooks
-description: "Use when building the inbound side of a webhook — the HTTP endpoint that receives events a system pushes you, proves they are authentic, refuses to process the same one twice, and acks fast. Covers the mechanics every source shares: raw-body HMAC verification, ~5-min timestamp/replay window, idempotency on a stable event id, fast-ack-then-queue, retry/poison handling. Triggers: 'receive webhooks and process them safely', 'verify an incoming webhook signature', 'my signature verification fails even though the secret is correct', 'provider keeps retrying and we process the same event twice', 'handler times out under load, ack fast and queue', 'recibir webhooks entrantes', 'verificar la firma del webhook entrante', 'evitar procesar el mismo evento dos veces'. NOT the Stripe-Signature scheme (that is stripe), NOT email bounce/suppression hooks (that is email-connector), NOT outbound clients calling a third-party API (that is api-connector-builder), NOT what runs after the event lands (that is automation-flows)."
+description: "Use when building the receiving end of a webhook — a provider-agnostic endpoint that proves pushed events are authentic and never processes one twice: raw-body HMAC, ~5-min replay window, idempotency on the event id, fast-ack-then-queue. NOT the Stripe-Signature scheme (that is stripe), NOT outbound clients you call (that is api-connector-builder)."
 tags: [webhooks, inbound-webhooks, hmac-verification, idempotency, signature-verification, queue, connectors]
 recommends: [stripe, email-connector, api-connector-builder, automation-flows, redis, secure-coding]
 profiles: []
@@ -13,14 +13,9 @@ You are building the side of a webhook that *receives*. Some external system
 pushes an HTTP POST at your endpoint; your job is to prove it is real, refuse to
 act on it twice, and answer fast. That is the whole mandate.
 
-This skill is provider-agnostic. It teaches the mechanics every webhook source
-shares, not any one vendor's event catalog. The deliverable is secret-safe
-server code plus minimal config: a handler that reads the **raw** request body
-for HMAC verification, compares signatures in **constant time**, rejects events
-outside a **timestamp tolerance**, **dedupes** on a stable event id, then
-**persists-or-enqueues before returning `2xx`**.
-
-It ends at "enqueued." What happens to the event afterward is a different job:
+This skill is provider-agnostic — it teaches the mechanics every webhook source
+shares, not any one vendor's event catalog — and it ends at "enqueued." What
+happens to the event afterward is a different job:
 
 - The Stripe-specific scheme (`Stripe-Signature`, `t=,v1=`, `stripe listen`,
   the event model) → `../stripe/SKILL.md`.
@@ -29,8 +24,10 @@ It ends at "enqueued." What happens to the event afterward is a different job:
 - The *outbound* client that calls someone else's API → `api-connector-builder`.
 - Multi-step orchestration after the event lands → `automation-flows`.
 - Broker/queue tuning (BullMQ concurrency, DLQ ops) → `redis`.
+- Constant-time compare, secret handling, supply-chain hygiene →
+  `../secure-coding/SKILL.md`.
 
-## The pipeline — non-negotiable order
+## The pipeline
 
 These five stages run in exactly this order. Each one exists to protect the one
 after it; reorder them and you either trust forged data or waste work.
@@ -43,13 +40,9 @@ after it; reorder them and you either trust forged data or waste work.
 | 4 | **Dedupe** on the event id | At-least-once delivery means duplicates are normal. Mark it seen before doing work, not after. |
 | 5 | **Persist/enqueue → `2xx`** | Hand the event to durable storage, then ack. The ack means "I own this now." |
 
-Two facts make this order non-negotiable:
-
-- **Delivery is at-least-once, never exactly-once.** Every major provider
-  retries on non-2xx or timeout, so duplicate deliveries are normal traffic.
-  Idempotency is required, not a nice-to-have.
-- **The handler must be fast.** Heavy synchronous work inside it causes provider
-  timeouts and a storm of retries. Verify, dedupe, enqueue, ack — then work.
+**Delivery is at-least-once, never exactly-once.** Every major provider retries
+on non-2xx or timeout, so duplicate deliveries are normal traffic and idempotency
+is required, not a nice-to-have.
 
 ## Verify the signature
 
@@ -180,8 +173,10 @@ it?" check and both run. Let the UNIQUE constraint (or `NX`) be the lock.
 
 ## Fast-ack & queue
 
-Return `2xx` as soon as the event is durably stored or enqueued, then do the
-real work in a background worker. The status code is a contract with the sender:
+Heavy synchronous work inside the handler causes provider timeouts and a storm
+of retries. Return `2xx` as soon as the event is durably stored or enqueued,
+then do the real work in a background worker. The status code is a contract with
+the sender:
 
 | You return | Meaning to the provider | Use it when |
 |------------|-------------------------|-------------|
@@ -229,18 +224,6 @@ Capturing the raw body is framework-specific and is the usual culprit behind
 
 `scripts/verify.sh` is a read-only heuristic linter. Run it from the root of the
 project that contains your handler; it scans candidate files and prints
-PASS/WARN/FAIL for each invariant (raw-body verify, constant-time compare,
-timestamp check, secret-from-env, dedupe-on-event-id). It is advisory, not a
-compiler — a WARN means "I could not find evidence," which on a clean/empty tree
-is expected and exits `0`.
-
-## Cross-references
-
-- Stripe's exact scheme and event model → `../stripe/SKILL.md`
-- Email bounce/complaint suppression webhooks → `../email-connector/SKILL.md`
-- The outbound API client (auth, pagination, retries you initiate) →
-  `api-connector-builder`
-- Orchestrating what happens after the event lands → `automation-flows`
-- Queue/broker concurrency and DLQ operations → `redis`
-- Constant-time compare, secret handling, supply-chain hygiene →
-  `../secure-coding/SKILL.md`
+PASS/WARN/FAIL per invariant (raw-body verify, constant-time compare, timestamp
+check, secret-from-env, dedupe-on-event-id). A WARN means "I could not find
+evidence," which on a clean tree is expected and exits `0`.