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

package/skills/shared/runpod/references/serverless-workers.md

@@ -0,0 +1,101 @@
+# Serverless workers — fuller patterns
+
+Depth for the SKILL.md "Serverless worker handler" section. The `runpod` Python SDK drives
+all of this.
+
+## start() options
+
+```python
+import runpod
+
+runpod.serverless.start({
+    "handler": handler,                 # required: sync or async callable
+    "return_aggregate_stream": True,    # generator handlers: also expose joined output via /runsync
+    "concurrency_modifier": adjust,     # callable -> max concurrent jobs this worker takes
+})
+```
+
+## Async handler
+
+Use `async def` when the handler awaits I/O (model server, HTTP, DB). The runtime awaits it.
+
+```python
+import runpod
+
+async def handler(job):
+    job_input = job["input"]
+    result = await run_model(job_input["prompt"])
+    return {"output": result}
+
+runpod.serverless.start({"handler": handler})
+```
+
+## Streaming via async generator
+
+`yield` chunks instead of returning once. Clients read them from the `/stream/<id>` endpoint.
+Set `return_aggregate_stream: True` if you also want the joined result on `/runsync`.
+
+```python
+import runpod
+
+async def handler(job):
+    for token in generate(job["input"]["prompt"]):
+        yield {"token": token}
+
+runpod.serverless.start({"handler": handler, "return_aggregate_stream": True})
+```
+
+## Concurrency modifier
+
+By default a worker takes one job at a time. For lightweight or batched work, let one worker
+hold several concurrent jobs — fewer cold starts, lower bill. Return the max concurrency
+given the current count.
+
+```python
+def adjust_concurrency(current_concurrency):
+    # Cap at 4 concurrent jobs per worker.
+    return min(current_concurrency + 1, 4)
+
+runpod.serverless.start({"handler": handler, "concurrency_modifier": adjust_concurrency})
+```
+
+## Error shape
+
+Raise to fail a job, or return a dict with an `error` key. Failed jobs surface in the
+endpoint status; a worker that errors repeatedly can be refresh-cycled.
+
+```python
+def handler(job):
+    job_input = job["input"]
+    if "prompt" not in job_input:
+        return {"error": "missing 'prompt' in input"}
+    return {"output": run(job_input["prompt"])}
+```
+
+## Local testing
+
+Always exercise the handler locally before building/pushing an image.
+
+- **One-shot:** create `test_input.json`, then `python worker.py`. The SDK detects the file,
+  runs the handler once against its `input`, prints the output, and exits.
+
+  ```json
+  { "input": { "prompt": "hello" } }
+  ```
+
+- **HTTP server:** `python worker.py --rp_serve_api` starts a local server at
+  `http://localhost:8000` emulating the deployed endpoint, so you can POST to `/runsync` and
+  `/run` exactly as the platform would.
+
+## Endpoint HTTP API
+
+Once deployed, an endpoint exposes (auth with your API key as a bearer token):
+
+| Endpoint | Purpose |
+| --- | --- |
+| `POST /run` | Submit an async job, returns a job id immediately. |
+| `POST /runsync` | Submit and block for the result (short jobs, ~90s ceiling). |
+| `GET /stream/<id>` | Pull streamed chunks from a generator handler. |
+| `GET /status/<id>` | Poll an async job's status + output. |
+| `POST /cancel/<id>` | Cancel a queued or running job. |
+| `GET /health` | Worker counts and queue depth for the endpoint. |

package/skills/shared/runpod/scripts/verify.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Usage: bash scripts/verify.sh [TARGET_DIR]   (default: .)
+# Statically lints a RunPod worker directory. Pure grep/parse — no network, no RunPod
+# account, never writes or installs anything. Read-only.
+#
+# Exit 0 = all applicable checks passed (or the target has nothing to check — an empty or
+# non-worker dir is NOT a failure). Non-zero = a real problem found in present files.
+# Portable to stock macOS bash 3.2: no mapfile, arrays guarded under set -u.
+
+TARGET="${1:-.}"
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1 && [ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]; then
+  YELLOW="$(tput setaf 3)"; RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; RESET="$(tput sgr0)"
+else
+  YELLOW=""; RED=""; GREEN=""; RESET=""
+fi
+
+rc=0
+pass() { printf '%s[PASS]%s %s\n' "$GREEN" "$RESET" "$1"; }
+warn() { printf '%s[WARN]%s %s\n' "$YELLOW" "$RESET" "$1" >&2; }
+fail() { printf '%s[FAIL]%s %s\n' "$RED" "$RESET" "$1" >&2; rc=1; }
+
+if [ ! -d "$TARGET" ]; then
+  fail "target dir not found: $TARGET"
+  exit 1
+fi
+
+# Prune patterns as a literal arg array — each token is its own quoted word, so the shell
+# can never word-split them or glob-expand them against the cwd. (Unquoted `$PRUNE` here
+# silently corrupts find when run from a real project root containing node_modules/.git/venv,
+# emptying the file lists so every check — including the hardcoded-key check — passes.)
+PRUNE=( '(' -path '*/node_modules/*' -o -path '*/.venv/*' -o -path '*/venv/*' -o -path '*/.git/*' ')' -prune -o )
+
+# Collect file lists (newline-delimited; bash 3.2 safe — arrays only used as literal argv).
+PY_FILES="$(find "$TARGET" "${PRUNE[@]}" -name '*.py' -print 2>/dev/null || true)"
+DOCKERFILES="$(find "$TARGET" "${PRUNE[@]}" -iname 'Dockerfile*' -print 2>/dev/null || true)"
+CONFIGS="$(find "$TARGET" "${PRUNE[@]}" \( -name '*.json' -o -name '*.yaml' -o -name '*.yml' \) -print 2>/dev/null || true)"
+
+checked=0
+
+# 1. Python worker: runpod.serverless.start present, and a handler with return/yield.
+if [ -n "$PY_FILES" ]; then
+  if printf '%s\n' "$PY_FILES" | xargs grep -lE 'runpod\.serverless\.start\(' 2>/dev/null | grep -q .; then
+    checked=1
+    pass "found runpod.serverless.start( in a worker file"
+    # Any handler-ish def with a body that returns or yields.
+    if printf '%s\n' "$PY_FILES" | xargs grep -lE '\b(return|yield)\b' 2>/dev/null | grep -q .; then
+      pass "handler returns or yields a result"
+    else
+      fail "no handler 'return' or 'yield' found — worker would produce no output"
+    fi
+  else
+    warn "no runpod.serverless.start( found — not a serverless worker dir, skipping worker checks"
+  fi
+
+  # 2. No hardcoded API key. Flag literal string assignments to api_key / RUNPOD_API_KEY.
+  if printf '%s\n' "$PY_FILES" | xargs grep -nE '(runpod\.api_key|RUNPOD_API_KEY)[[:space:]]*=[[:space:]]*["'"'"'][A-Za-z0-9_-]+["'"'"']' 2>/dev/null | grep -q .; then
+    checked=1
+    fail "hardcoded API key literal found — read it from os.environ['RUNPOD_API_KEY']"
+  else
+    [ -n "$PY_FILES" ] && pass "no hardcoded API key literal in Python sources"
+  fi
+fi
+
+# 3. Serverless config (json/yaml) — bounded max_workers + timeout keys present.
+if [ -n "$CONFIGS" ]; then
+  CFG_WITH_MW="$(printf '%s\n' "$CONFIGS" | xargs grep -lEi 'max[_-]?workers' 2>/dev/null || true)"
+  if [ -n "$CFG_WITH_MW" ]; then
+    checked=1
+    # Must be a finite positive int — fail on missing/0/negative/inf.
+    if printf '%s\n' "$CFG_WITH_MW" | xargs grep -hEi 'max[_-]?workers' 2>/dev/null \
+        | grep -qE 'max[_-]?[Ww]orkers["'"'"']?[[:space:]]*[:=][[:space:]]*[1-9][0-9]*'; then
+      pass "max_workers is a bounded positive integer"
+    else
+      fail "max_workers present but not a bounded positive int (set a finite ceiling)"
+    fi
+    if printf '%s\n' "$CFG_WITH_MW" | xargs grep -qiE 'idle[_-]?timeout' 2>/dev/null; then
+      pass "idle timeout set in config"
+    else
+      fail "config has max_workers but no idle timeout — set it explicitly"
+    fi
+    if printf '%s\n' "$CFG_WITH_MW" | xargs grep -qiE 'execution[_-]?timeout' 2>/dev/null; then
+      pass "execution timeout set in config"
+    else
+      fail "config has max_workers but no execution timeout — a hung job can run for days"
+    fi
+  fi
+fi
+
+# 4. Dockerfile — pinned FROM (not bare/:latest) and a CMD/ENTRYPOINT.
+if [ -n "$DOCKERFILES" ]; then
+  while IFS= read -r df; do
+    [ -n "$df" ] || continue
+    checked=1
+    fromline="$(grep -iE '^[[:space:]]*FROM[[:space:]]' "$df" 2>/dev/null | head -1 || true)"
+    if [ -z "$fromline" ]; then
+      fail "$df: no FROM line"
+    elif printf '%s' "$fromline" | grep -qiE ':latest([[:space:]]|$)'; then
+      fail "$df: FROM uses :latest — pin a version tag"
+    elif printf '%s' "$fromline" | grep -qE '[^[:space:]]+:[^[:space:]]+'; then
+      pass "$df: FROM is pinned to a tag"
+    else
+      fail "$df: FROM has no tag — pin a version"
+    fi
+    if grep -qiE '^[[:space:]]*(CMD|ENTRYPOINT)[[:space:]]' "$df" 2>/dev/null; then
+      pass "$df: has CMD/ENTRYPOINT"
+    else
+      fail "$df: no CMD or ENTRYPOINT — worker has no entrypoint"
+    fi
+  done <<EOF
+$DOCKERFILES
+EOF
+fi
+
+if [ "$checked" -eq 0 ]; then
+  warn "no RunPod worker artifacts found in '$TARGET' — nothing to lint"
+fi
+
+if [ "$rc" -ne 0 ]; then
+  printf '%sverify.sh: FAILED%s\n' "$RED" "$RESET" >&2
+  exit "$rc"
+fi
+printf '%sverify.sh: OK%s\n' "$GREEN" "$RESET"
+exit 0

package/skills/shared/rust/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: rust
+description: "Use when writing, reviewing, testing, or shipping Rust — ownership and the borrow checker (move/borrow/clone, Arc/RefCell, lifetimes), errors with Result/`?`/thiserror/anyhow, async on tokio, axum 0.8 services, cargo test, and sqlx + cargo-audit hardening. NOT the same service in Go (that is `go`), NOT a desktop webview shell (that is `tauri`)."
+tags: [rust, tokio, axum, async, backend, service]
+recommends: [go, postgresdb, secure-coding, deployment]
+origin: ai-hub
+---
+
+# Idiomatic Rust services
+
+Write, review, test, and ship idiomatic async Rust services with the ownership model working *for*
+you, not against you.
+
+Targets **Rust 1.85+ / edition 2024** as the floor: native `async fn`
+in traits (no reflexive `#[async_trait]`), **tokio 1.x** as the runtime, **axum 0.8** for the HTTP
+surface (`{id}` path-capture syntax, async-trait-free extractors), **thiserror 2** for library error
+enums and **anyhow** at the application edge, **sqlx** for compile-time-checked SQL, and **tracing**
+for structured observability.
+
+The thing an agent gets wrong in Rust is almost never syntax — it is *ownership*. Most "bugs" are
+compile errors about moves, borrows, and `Send + Sync` across `.await`. Front-load that mental model;
+the rest follows.
+
+## Ownership & borrowing (essentials)
+
+This is the skill's center of gravity. Three moves: **move** (transfer ownership), **borrow** (`&`/`&mut`,
+no transfer), **clone** (a real copy, real cost) — and prefer them in that order, borrow first.
+Take `&str`/`&[T]` in function params, return owned `String`/`Vec<T>`: borrow on the way in, own on the
+way out is both the most flexible and the cheapest.
+
+```rust
+fn print_name(name: &str) { println!("{name}"); }   // borrows; caller keeps ownership
+
+let s = String::from("ada");
+print_name(&s);                                       // Good: lend a reference
+println!("{s}");                                      // still usable
+
+// Bad: takes by value, moves it, then the caller can't use `s` anymore.
+fn consume(name: String) { /* ... */ }
+consume(s);
+// println!("{s}");  // error[E0382]: borrow of moved value: `s`
+```
+
+The four borrow-checker errors you will actually hit, with the fix:
+
+```rust
+// 1. "value moved here" (E0382): you used a value after moving it.
+//    Fix: borrow instead of move, or .clone() only if you genuinely need two owners.
+let v = vec![1, 2, 3];
+let first = &v[0];           // Good: borrow
+// let taken = v; let _ = first;  // Bad: moves v while `first` borrows it.
+
+// 2. "cannot borrow as mutable more than once" (E0499): two &mut alive at once.
+//    Fix: scope the first borrow so it ends before the second begins.
+let mut data = vec![1, 2, 3];
+{ let a = &mut data; a.push(4); }   // borrow ends here
+let b = &mut data; b.push(5);       // Good: non-overlapping
+
+// 3. "cannot borrow as mutable, already borrowed as immutable" (E0502).
+//    Fix: don't hold a shared ref across a mutation; collect indices first, mutate after.
+
+// 4. "does not live long enough" (E0597): a reference outlives the value it points to.
+//    Fix: return an owned value, or restructure so the owner outlives the borrow.
+```
+
+Shared state: pick the smallest tool that fits. Decision table —
+
+| Need | Use | Why |
+| --- | --- | --- |
+| One owner, sized value | the value, or `Box<T>` | `Box` only when heap/indirection/`dyn` is required |
+| Shared ownership, single thread | `Rc<T>` | cheap refcount, **not** thread-safe |
+| Shared ownership, across threads/await | `Arc<T>` | atomic refcount; the default for async app state |
+| Interior mutability, single thread | `RefCell<T>` | runtime borrow check; panics on violation |
+| Shared mutable state, async | `Arc<Mutex<T>>` (tokio's) | but prefer a channel if it is really message passing |
+| Read-heavy shared state | `Arc<RwLock<T>>` | many readers, rare writer |
+
+Shared async state is `Arc<AppState>` injected through axum `State` — never a global `static mut`.
+Lifetimes, `'static`, `Cow`, and the full smart-pointer tree -> `references/ownership.md`.
+
+## Errors
+
+Error modeling is owned here, in Rust terms — it is not a separate skill. The model: `Result<T, E>` +
+`?`, typed enums for libraries, `anyhow` at the edge, one mapping from a domain enum to an HTTP status.
+
+```rust
+use thiserror::Error;
+
+// Library / domain layer: a typed enum callers can match on. #[from] gives free `?` conversion.
+#[derive(Debug, Error)]
+pub enum UserError {
+    #[error("user {0} not found")]
+    NotFound(i64),
+    #[error("database error")]
+    Db(#[from] sqlx::Error),   // any sqlx::Error becomes UserError::Db via `?`
+}
+```
+
+```rust
+// Application edge: anyhow when you just need context, not a match.
+use anyhow::Context;
+let config = std::fs::read_to_string(path)
+    .with_context(|| format!("reading config at {path}"))?;   // adds a human breadcrumb
+```
+
+**The 3-layer flow (twin of go's).** Repository returns the typed domain error; service propagates with
+`?`; the handler maps the enum to a status *once*, via `IntoResponse` — pattern-match the variant, never
+string-match the message, and log only the unexpected one (no internal leak to the client).
+
+```rust
+use axum::{http::StatusCode, response::{IntoResponse, Response}, Json};
+use serde_json::json;
+
+impl IntoResponse for UserError {
+    fn into_response(self) -> Response {
+        let status = match self {
+            UserError::NotFound(_) => StatusCode::NOT_FOUND,            // 404
+            UserError::Db(ref e) => {                                  // 500
+                tracing::error!(error = %e, "unexpected db error");    // log here, not to the client
+                StatusCode::INTERNAL_SERVER_ERROR
+            }
+        };
+        (status, Json(json!({ "error": self.to_string() }))).into_response()
+    }
+}
+```
+
+Full repo->service->handler skeleton -> `references/axum-service.md`.
+
+## Async (tokio, essentials)
+
+`#[tokio::main]` boots the multi-thread runtime; futures do nothing until `.await`. Bound your fan-out:
+
+```rust
+use tokio::task::JoinSet;
+
+let mut set = JoinSet::new();
+for id in ids {                                  // Good: a JoinSet you can drain and cap
+    set.spawn(async move { fetch(id).await });
+}
+let mut out = Vec::new();
+while let Some(res) = set.join_next().await {
+    out.push(res??);                             // join error, then task error
+}
+```
+
+The two pitfalls that bite agents, with the fix:
+
+```rust
+// Bad: std Mutex guard held across .await -> "future cannot be sent between threads safely".
+let guard = state.lock().unwrap();
+do_io().await;                  // guard is still alive here -> not Send
+guard.update();
+
+// Good: drop the lock before awaiting, or use tokio::sync::Mutex if the lock must span the await.
+{
+    let mut g = state.lock().unwrap();
+    g.update();
+}                               // guard dropped here
+do_io().await;                  // nothing non-Send is held across the await
+```
+
+```rust
+// Bad: a CPU-bound parse on the async worker thread starves every other task.
+let parsed = heavy_parse(&blob);          // blocks the executor
+// Good: move blocking/CPU work off the runtime.
+let parsed = tokio::task::spawn_blocking(move || heavy_parse(&blob)).await?;
+```
+
+`select!` races futures (handle a cancellation token in one arm); `tokio::sync::mpsc` for message
+passing — prefer a channel over `Arc<Mutex<T>>` when the data flows one way. Cancellation, a
+bounded-concurrency + jittered-retry helper (ctx-aware, never retries a 4xx), and the full `Send + Sync`
+rules -> `references/async-tokio.md`.
+
+## Service (axum, essentials)
+
+axum 0.8: `{id}` capture in the path, `Path`/`State`/`Json` extractors, your error enum as the return:
+
+```rust
+use axum::{extract::{Path, State}, routing::get, Router, Json};
+use std::sync::Arc;
+
+async fn get_user(
+    State(app): State<Arc<AppState>>,            // shared state, not a global
+    Path(id): Path<i64>,                         // {id} parsed and typed
+) -> Result<Json<User>, UserError> {             // UserError: IntoResponse maps it
+    let user = app.users.find(id).await?;        // `?` propagates the typed error
+    Ok(Json(user))
+}
+
+let app = Router::new()
+    .route("/users/{id}", get(get_user))         // 0.8 syntax: {id}, not :id
+    .with_state(state);
+```
+
+Validate at the boundary and parse into a typed domain model — "parse, don't validate" makes illegal
+states unrepresentable, so the handler body never re-checks. Full skeleton — tower middleware
+(`TraceLayer`, timeout, request-id), graceful shutdown via
+`axum::serve(...).with_graceful_shutdown(...)`, and JSON helpers -> `references/axum-service.md`.
+
+## Project layout
+
+Keep the binary thin; put logic in the library so tests and integration tests can reach it.
+
+```text
+my-service/
+  Cargo.toml          # [dependencies], [profile.release], optional [workspace]
+  src/
+    main.rs           # entrypoint: parse config, build state, axum::serve — wiring only
+    lib.rs            # pub mod error; pub mod app; pub mod users; — the testable surface
+    error.rs          # the thiserror enum + IntoResponse
+    users/
+      mod.rs          # handlers + the domain model
+      repo.rs         # sqlx queries
+  tests/
+    users_api.rs      # integration tests that spin up the Router
+```
+
+A larger system becomes a Cargo **workspace** (`[workspace] members = [...]`) with one crate per bounded
+context. Gate optional deps behind `[features]`. The `lib.rs` carries `#![forbid(unsafe_code)]`.
+
+## Testing (essentials)
+
+`#[test]` for sync, `#[tokio::test]` for async; integration tests under `tests/` exercise the real
+`Router`; doctests keep examples honest.
+
+```rust
+#[tokio::test]
+async fn get_user_404_when_missing() {
+    let app = build_router(test_state());            // the same Router main builds
+    let res = app
+        .oneshot(Request::get("/users/999").body(Body::empty()).unwrap())
+        .await
+        .unwrap();
+    assert_eq!(res.status(), StatusCode::NOT_FOUND);
+}
+```
+
+Use `cargo nextest run` for faster, cleaner parallel runs; `cargo test --doc` for doctests. Trait-based
+fakes (a `UserRepo` trait the handler depends on, a fake impl in tests) keep the DB out of unit tests.
+Integration matrices, `insta` snapshots, and the full `tests/` HTTP setup -> `references/testing.md`.
+
+## Security (embedded)
+
+Parametrize SQL, forbid unsafe, audit dependencies, read secrets from the environment:
+
+```rust
+// Good: bound parameters; sqlx checks the query at compile time against the DB schema.
+sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id).fetch_one(&pool).await?;
+
+// Bad: format! into SQL is injection, full stop.
+// sqlx::query(&format!("SELECT * FROM users WHERE id = {id}")).fetch_one(&pool).await?;
+```
+
+`#![forbid(unsafe_code)]` at the crate root; run `cargo audit` (RustSec advisories) and `cargo deny` (license
++ ban + advisory policy) in CI; never `.unwrap()` on untrusted input — a malicious request becomes a
+panic. Read secrets from env or a secret manager, never hardcode or log them. Deeper authz / threat
+modeling -> [`secure-coding`](../secure-coding/SKILL.md). Pure SQL schema/index/plan tuning ->
+[`postgresdb`](../postgresdb/SKILL.md); this skill covers only the Rust-side sqlx query.
+
+## Production
+
+Structured logs and a lean release binary:
+
+```rust
+// JSON tracing subscriber, level from RUST_LOG; do this once in main before serving.
+tracing_subscriber::fmt().json().with_env_filter(tracing_subscriber::EnvFilter::from_default_env()).init();
+```
+
+```toml
+[profile.release]
+lto = true              # link-time optimization: smaller, faster binary
+codegen-units = 1       # better optimization at the cost of compile time
+panic = "abort"         # no unwinding in prod; smaller binary, fail fast
+strip = true            # strip symbols
+```
+
+Expose `/healthz` (static 200 liveness) and `/readyz` (pings the DB pool, 503 on failure). Docker:
+multi-stage build, `cargo build --release`, copy the binary onto a distroless/slim base. Full
+Containerfile + CI -> [`deployment`](../deployment/SKILL.md).
+
+## Anti-patterns
+
+| Anti-pattern | Reality / Do instead |
+| --- | --- |
+| `.clone()` to make the borrow checker happy | It hides the real ownership question; borrow, or restructure who owns what. |
+| `.unwrap()` / `.expect()` off the test path | A panic on the request path is a 500 or a crashed worker; use `?` + a typed error. |
+| Matching an error by its message string | Messages are prose and they change; match the enum variant. |
+| `Box<dyn Error>` everywhere because it is simpler | Nothing can branch on the failure; use a `thiserror` enum the caller can match. |
+| `#[async_trait]` on every async trait | Edition 2024 has native async fn in traits; drop the macro for most cases. |
+| `block_on` inside an async fn | Nesting a runtime panics or deadlocks; restructure to `.await`. |
+| A bare `tokio::spawn` per loop iteration | Unbounded fan-out exhausts the runtime; bound it with `JoinSet`/semaphore. |
+| `Arc<Mutex<T>>` for everything shared | If data flows one way it is a channel; reach for `mpsc` first. |
+| `unsafe` to get past the borrow checker | `unsafe` turns a compile error into UB; the checker was right — restructure. |
+| Skipping clippy as "just style" | clippy catches correctness (`.unwrap()` on `Option`, await-holds-lock); gate on `-D warnings`. |
+
+## Gates & commands
+
+| Task | Command |
+| --- | --- |
+| Format check | `cargo fmt --all -- --check` |
+| Lint (gate) | `cargo clippy --all-targets -- -D warnings` |
+| Test | `cargo test` / `cargo nextest run` |
+| Doctests | `cargo test --doc` |
+| Audit deps | `cargo audit` / `cargo deny check` |
+| Local gate | `./scripts/verify.sh` (run in your crate root) |
+
+Format and lint are build gates, not suggestions.
+
+## Project grounding (02-DOCS)
+
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) wiki), the service decisions
+live in `02-DOCS/wiki/stack/rust.md`, indexed from `02-DOCS/wiki/index.md`. Read it first and stay
+consistent; if it is missing or stale, write the project's real choices there — crate/workspace layout,
+runtime (tokio), HTTP framework (axum 0.8), error strategy (thiserror enum + `IntoResponse` mapping), DB
+layer (sqlx + pool), tracing and concurrency defaults — bump its `Updated` date, and index it. No
+`02-DOCS/`? Skip silently. Conventions are *recorded, not gated* — never block the task on this.
+
+[`go`](../go/SKILL.md) is the structural twin: same write/review/test/ship service shape, GC +
+goroutines + multi-return errors instead of ownership + futures + `Result`. A desktop shell around a
+webview is [`tauri`](../tauri/SKILL.md), not this.

package/skills/shared/rust/evals/README.md

@@ -0,0 +1,12 @@
+# Eval harness — `rust` skill
+
+`cases.yaml` is a human/CI-readable trigger-and-capability spec, not an automated runner. To exercise
+it, load the full skill catalog descriptions into a routing agent and, for each `should_trigger` prompt,
+check that the `rust` skill fires; for each `should_not_trigger` prompt, check that it stays silent and
+that any skill that does fire matches the stated `route_to` sibling (secure-coding, deployment,
+postgresdb, tauri, go). Because LLM routing is non-deterministic, run a few trials per prompt and take
+the majority. For the `capability` scenario, run it once with the skill body unavailable and once with
+`rust/SKILL.md` (plus references) loaded, then eyeball each output against the `must_include` rubric —
+the with-skill answer should cover the rubric and clearly beat the baseline (a `thiserror` enum mapped
+via `IntoResponse`, a `$1` bind parameter, `?` propagation with no `.unwrap()` on the request path).
+Keep `cases.yaml` faithful to SKILL.md's "When to use / When NOT to use" whenever scope changes.

package/skills/shared/rust/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: rust
+
+should_trigger:
+  - prompt: "Write an axum service that exposes GET /users/{id} backed by Postgres, with graceful shutdown."
+    why: "Authoring a tokio + axum 0.8 service with sqlx and shutdown is the skill's core use case."
+  - prompt: "The compiler says `value moved here` and `borrow of moved value` on my struct — how do I fix this without cloning everywhere?"
+    why: "Non-obvious: the prompt never says 'Rust', it is pure borrow-checker symptom text; ownership debugging is the skill's center of gravity."
+  - prompt: "How should I model errors across my repository, service, and handler layers so I return the right HTTP status?"
+    why: "thiserror enum + #[from] + the IntoResponse status mapping is canonically owned here; same shape as go's 3-layer flow."
+  - prompt: "I get `future cannot be sent between threads safely` after I lock a Mutex right before an .await — how do I fix it?"
+    why: "The not-Send / MutexGuard-held-across-await async pitfall is a named trigger; the symptom text routes here without the word 'tokio'."
+  - prompt: "Review this .rs before I ship: it `.unwrap()`s the DB row and `format!`s the id straight into the SQL string."
+    why: "Review trigger combining the Rust-specific security controls (sqlx parametrization, no unwrap on untrusted input) embedded here."
+  - prompt: "El borrow checker no em deixa compilar aquesta funció async amb tokio, com ho arreglo?"
+    why: "Catalan trigger: borrow checker + async tokio is squarely this skill."
+
+should_not_trigger:
+  - prompt: "Do a threat model and OWASP-style authz review of my multi-tenant app's permission boundaries."
+    route_to: "secure-coding"
+    why: "Language-agnostic threat modeling and authz/abuse review is delegated to secure-coding; only Rust-specific controls stay here."
+  - prompt: "Write a multi-stage Dockerfile and a GitHub Actions CI pipeline to build and deploy my Rust service."
+    route_to: "deployment"
+    why: "Containerfile / CI / shipping is delegated to deployment; this skill ships only a Docker note plus release-profile flags."
+  - prompt: "Design the indexes and tune the query plan for this Postgres users table with a composite lookup."
+    route_to: "postgresdb"
+    why: "Pure SQL schema/index/plan tuning is a database concern; the Rust skill only covers parametrization from the Rust side."
+  - prompt: "Build a cross-platform desktop app with a Rust backend and a webview UI."
+    route_to: "tauri"
+    why: "Native GUI / desktop shell with a webview is out of scope here and routes to tauri."
+  - prompt: "Write the same service in Go with net/http and graceful shutdown."
+    route_to: "go"
+    why: "Go service work belongs to the go skill, the structural twin; this skill is Rust-only."
+
+capability:
+  - scenario: "Implement an axum handler GET /users/{id} over sqlx + Postgres that returns 404 when the user is missing and 500 on an unexpected DB error, with shared state via Arc and no panics on the request path."
+    must_include:
+      - "Uses the axum 0.8 routed path `/users/{id}` with a `Path<i64>` extractor and `State<Arc<AppState>>` (shared state, no static mut / globals)"
+      - "Defines a `thiserror` domain enum (e.g. NotFound + Db) with `#[from]` so `?` lifts sqlx::Error automatically"
+      - "Implements `impl IntoResponse` that pattern-matches the enum: NotFound -> 404, default/Db -> 500 (no string-matching of error messages)"
+      - "Parametrizes the SQL with a bind parameter ($1), never `format!`/string-interpolation into the query"
+      - "Propagates with `?` and has zero `.unwrap()`/`.expect()` on the request path"
+      - "Logs only the unexpected error with `tracing` (e.g. tracing::error!) and does not leak the internal error to the client body"