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

package/skills/shared/ruby/references/metaprogramming.md

@@ -0,0 +1,161 @@
+# Metaprogramming, in depth
+
+Ruby's dynamism is a power tool, and the default answer is *don't*: a plain method,
+`Struct`, `Data`, or Hash is more discoverable than a clever interception. Reach here
+only when the boring version produces real, repeated boilerplate, and always pick the
+most reversible, most introspectable tool that does the job.
+
+Order of preference: **plain method -> `define_method` -> `method_missing` (last
+resort, always paired)**.
+
+## define_method — dynamic names, real methods
+
+`define_method` defines an actual method visible to `respond_to?`, `method`, docs, and
+tooling. Use it to collapse repetitive accessor/delegation boilerplate.
+
+```ruby
+# frozen_string_literal: true
+
+class Settings
+  def initialize(**data) = @data = data
+
+  %i[host port timeout].each do |key|
+    define_method(key)       { @data.fetch(key) }
+    define_method("#{key}?") { !@data[key].nil? }
+  end
+end
+
+s = Settings.new(host: "db", port: 5432, timeout: nil)
+s.respond_to?(:port)   # => true   (a real method)
+s.timeout?             # => false
+```
+
+The block captures its surrounding scope (a closure), so `key` is available inside
+each generated method. That is the whole reason to prefer it over `eval`-built strings.
+
+## method_missing — and why it must be paired
+
+`method_missing` intercepts calls to methods that do not exist. It is slower (every
+miss walks the ancestry chain first), invisible to introspection, and easy to leave
+buggy. If you use it, you **must** also define `respond_to_missing?`, or `respond_to?`,
+`method(...)`, and any duck-typing check will lie about your object.
+
+```ruby
+# frozen_string_literal: true
+
+# A read-only view over a Hash with dotted access. method_missing is justified here
+# because the key set is open and data-driven — you cannot define_method them ahead.
+class OpenRecord
+  def initialize(attrs) = @attrs = attrs
+
+  def method_missing(name, *args)
+    return @attrs[name] if @attrs.key?(name) && args.empty?
+
+    super   # preserve normal NoMethodError for genuinely unknown calls
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    @attrs.key?(name) || super
+  end
+end
+
+r = OpenRecord.new(name: "Ada", lang: "Ruby")
+r.name                 # => "Ada"
+r.respond_to?(:lang)   # => true   (because respond_to_missing? is defined)
+r.nope                 # => NoMethodError, via super
+```
+
+Always call `super` in the fall-through branch so unhandled names raise the normal
+`NoMethodError` instead of returning `nil` silently.
+
+## instance_eval / class_eval
+
+- `instance_eval` runs a block with `self` rebound to the receiver — the basis of
+  configuration DSLs where the block "is" the object being configured.
+- `class_eval` (a.k.a. `module_eval`) runs a block in a class's definition context, so
+  `def` inside it defines instance methods. Prefer the block form over the string form;
+  the string form loses lexical scope and gives bad backtraces.
+
+## A small, justified DSL
+
+A DSL earns its place when the *call site* reads dramatically better than passing a
+Hash and the surface is stable. Build it on `instance_eval`, collecting plain data:
+
+```ruby
+# frozen_string_literal: true
+
+class RouteSet
+  def self.draw(&block)
+    set = new
+    set.instance_eval(&block)
+    set.routes
+  end
+
+  attr_reader :routes
+
+  def initialize = @routes = []
+
+  def get(path, to:)  = @routes << { verb: :get,  path:, to: }
+  def post(path, to:) = @routes << { verb: :post, path:, to: }
+end
+
+routes = RouteSet.draw do
+  get  "/health", to: "system#health"
+  post "/orders", to: "orders#create"
+end
+# => [{verb: :get, path: "/health", to: "system#health"}, ...]
+```
+
+Note it ends in a plain array of hashes — the DSL is a thin front, not a maze of
+dynamic dispatch. If the config is one level deep, skip the DSL and accept a Hash.
+
+## Refinements vs monkey-patching
+
+Monkey-patching reopens a core class globally, so the change leaks into every file and
+every gem in the process — the classic source of "it worked until I added that gem"
+bugs. A **refinement** scopes the patch to files that opt in with `using`.
+
+```ruby
+# frozen_string_literal: true
+
+module StringTitleize
+  refine String do
+    def titleize = split.map(&:capitalize).join(" ")
+  end
+end
+
+# Only active below this line, only in this file.
+using StringTitleize
+"hello world".titleize   # => "Hello World"
+```
+
+Rules: refinements are lexically scoped (active from the `using` line to end of file or
+module), do not affect other files, and are reversible by simply not requiring them.
+Prefer them to monkey-patching whenever you must add behavior to a class you do not own.
+
+## prepend for wrapping
+
+To wrap an existing method (logging, memoization, instrumentation) without `alias`
+gymnastics, put the wrapper in a module and `prepend` it so it sits *before* the class
+in the lookup chain and can call `super`:
+
+```ruby
+# frozen_string_literal: true
+
+module Timed
+  def call(*)
+    t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    super
+  ensure
+    warn("#{self.class}#call took #{Process.clock_gettime(Process::CLOCK_MONOTONIC) - t}s")
+  end
+end
+
+class Job
+  prepend Timed
+  def call = do_work
+end
+```
+
+`super` reaches the original `Job#call` because `Timed` was prepended ahead of it.
+This is cleaner and more reversible than aliasing the old method out from under callers.

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

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+#
+# verify.sh - read-only quality gate for plain-Ruby sources.
+#
+# Usage:
+#   cd <dir-with-ruby-sources>   # e.g. a gem root or a scripts directory
+#   /path/to/verify.sh [TARGET_DIR]
+#
+# Checks, all guarded so a Ruby-less box still passes:
+#   1. `ruby -c` syntax-checks every *.rb (and *.gemspec) found.
+#   2. If a Gemfile exists, `ruby -c` it too (it is Ruby).
+#   3. If rubocop or standardrb is present, lint (report only, never fatal).
+#
+# Read-only: never writes, formats, or mutates your source.
+# Exit codes: 0 = clean OR toolchain/target absent; 1 = a real syntax error.
+# Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).
+
+set -euo pipefail
+
+target="${1:-.}"
+
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+
+if [ ! -d "$target" ]; then
+  printf '%serror:%s target dir not found: %s\n' "$RED" "$RESET" "$target" >&2
+  exit 2
+fi
+
+if ! have ruby; then
+  skip "ruby not found - skipping syntax check (clean pass on a Ruby-less box)"
+  exit 0
+fi
+
+failed=0
+checked=0
+
+# 1 + 2. Syntax-check Ruby sources, gemspecs, and any Gemfile.
+#        -print0 / read -d keeps paths-with-spaces safe; no mapfile needed.
+while IFS= read -r -d '' file; do
+  checked=$((checked + 1))
+  if ruby -c "$file" >/dev/null 2>err.$$; then
+    ok "ruby -c $file"
+  else
+    fail "syntax error: $file"
+    sed 's/^/      /' err.$$ || true
+    failed=1
+  fi
+  rm -f err.$$
+done < <(find "$target" \( -name '*.rb' -o -name '*.gemspec' -o -name 'Gemfile' \) \
+          -type f -print0 2>/dev/null)
+
+if [ "$checked" -eq 0 ]; then
+  skip "no .rb / .gemspec / Gemfile under $target - nothing to check"
+  exit 0
+fi
+
+# 3. Optional lint, report-only (style is advisory, not a gate here).
+if have standardrb; then
+  printf -- '----- standardrb (report only)\n'
+  standardrb "$target" || skip "standardrb reported style issues (non-fatal)"
+elif have rubocop; then
+  printf -- '----- rubocop (report only)\n'
+  rubocop "$target" || skip "rubocop reported style issues (non-fatal)"
+else
+  skip "no rubocop/standardrb - skipping lint"
+fi
+
+if [ "$failed" -ne 0 ]; then
+  printf '%sverify failed:%s syntax errors above.\n' "$RED" "$RESET" >&2
+  exit 1
+fi
+
+printf '%sall %d Ruby file(s) parse.%s\n' "$GREEN" "$checked" "$RESET"
+exit 0

package/skills/shared/runpod/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: runpod
+description: "Use when running GPU compute on RunPod and deciding between Pods (hourly, always-on) and Serverless (per-second, autoscaling) for training, fine-tuning or inference — serverless endpoints, handler workers, worker Docker templates, network volumes, timeout and worker-count tuning, cold starts, and runaway bills. NOT Python-native serverless GPU with snapshot autoscaling (that is `modal`), NOT calling hosted prebuilt model APIs (that is `replicate`), NOT pulling weights from the Hub (that is `huggingface`)."
+tags: [runpod, gpu, serverless, inference, training, cost-control, vllm, ai-infra]
+recommends: [modal, replicate, huggingface, docker, llm-pipeline, cost-tracking, ollama]
+origin: ai-hub
+---
+
+# RunPod: GPU compute, two products, one bill
+
+RunPod sells GPU time two ways and they bill on opposite philosophies. Get the choice
+wrong and you either pay a steep premium for idle work or you pay 24/7 for a box that
+sits warm doing nothing. Everything below is the RunPod-specific operational playbook:
+which product a workload belongs on, how to write a worker that does not waste cold-start
+seconds, and which knobs actually move the number on the invoice.
+
+The two products:
+
+- **Pods** — rent a GPU container by the hour. It runs continuously while it is up,
+  billed every hour whether busy or idle. Your dev box, your training job, your Jupyter.
+- **Serverless** — per-second autoscaling workers. Billed only while a worker is actually
+  running a job, from worker start to full stop, rounded up to the second. Costs roughly
+  **2-3x the equivalent hourly pod rate**, but idle gaps cost nothing on flex workers.
+
+RunPod charges **zero egress/ingress fees** — bandwidth in and out is free, unlike the
+hyperscalers. That removes one variable from cost math: you only reason about GPU-seconds
+and storage.
+
+## When to use
+
+- Deploying inference as a Serverless endpoint (vLLM LLM serving, image gen, custom model).
+- Running a training / fine-tuning job or a Jupyter / dev box on a GPU Pod.
+- Writing or debugging a serverless worker handler (`handler(job)`, async, streaming).
+- Building a custom worker Docker template / image, or wiring a network volume.
+- Cost control on RunPod: cold starts, idle bleed, runaway max workers, idle volume charges.
+- Picking a GPU SKU and the pod-vs-serverless tradeoff for a given workload.
+
+## When NOT to use
+
+- Python-native serverless GPU with snapshot autoscaling and no Dockerfile → that is `modal`.
+- Calling hosted, prebuilt model endpoints you do not host → that is `replicate`.
+- Pulling/pushing weights, datasets, model cards on the Hub → that is `huggingface`.
+- Running models locally on your own machine → that is `ollama`.
+- Provider-agnostic cross-cloud spend dashboards → that is `cost-tracking`.
+- Generic container packaging → that is `docker` (here we cover only the RunPod image shape).
+
+## Decision: Pod vs Serverless
+
+| Workload shape | Pick | Why |
+| --- | --- | --- |
+| Training / fine-tuning, multi-hour runs | **Pod** | Serverless premium + the 600s default execution timeout kill long jobs. You want the box continuously. |
+| Interactive dev / Jupyter / notebooks | **Pod** | You need it now and responsive; per-second autoscaling adds cold-start latency for nothing. |
+| Bursty inference with real idle gaps | **Serverless (flex)** | Idle costs nothing on flex; you pay only for the seconds a request runs. |
+| 24/7 steady high-QPS inference | **Compare** | Active serverless (40% off flex) vs a dedicated Pod. Past roughly 60% utilization a Pod usually wins. |
+
+Rule: if the GPU would sit busy more than ~60% of the time, a Pod is cheaper than
+serverless even with active-worker discount — model the two before committing.
+
+### GPU SKU quick-pick (2026 pod $/hr, lower on Community Cloud)
+
+| GPU | VRAM | Pod ~$/hr | Use for |
+| --- | --- | --- | --- |
+| L4 | 24GB | $0.39 | small models, light inference |
+| A40 | 48GB | $0.44 | mid-size inference, budget training |
+| RTX 4090 | 24GB | $0.69 | 7B-class inference, fast/cheap |
+| L40S | 48GB | $0.86 | 13B inference, image gen |
+| A100 80GB | 80GB | $1.39 | training, large-batch inference |
+| H100 PCIe | 80GB | $2.89 | the biggest models / fastest training |
+
+Rule: **pick the smallest GPU the model fits in VRAM.** Defaulting to H100 is up to ~7x
+the cost for zero speedup when the workload is memory-bound and fits on an L40S or 4090.
+
+## Serverless worker handler
+
+A worker is a Python file using the `runpod` SDK. The minimum: a function that reads
+`job["input"]`, returns a dict, and is registered with `runpod.serverless.start`.
+
+```python
+import runpod
+
+def handler(job):
+    job_input = job["input"]
+    prompt = job_input["prompt"]
+    # ... run the model ...
+    return {"output": f"echo: {prompt}"}
+
+runpod.serverless.start({"handler": handler})
+```
+
+Async handler (for awaiting model calls) and a streaming generator both work:
+
+```python
+import runpod
+
+async def handler(job):
+    job_input = job["input"]
+    return {"output": await run_model(job_input)}
+
+# Streaming: yield chunks from an async generator instead of returning once.
+async def stream_handler(job):
+    async for token in generate(job["input"]["prompt"]):
+        yield {"token": token}
+
+runpod.serverless.start({"handler": stream_handler, "return_aggregate_stream": True})
+```
+
+**Test locally before you push an image.** A broken handler still burns build minutes and
+cold-start seconds when discovered on the platform.
+
+```bash
+# One-shot: reads ./test_input.json, runs the handler once, prints output.
+python worker.py
+
+# HTTP server emulating the real endpoint at http://localhost:8000.
+python worker.py --rp_serve_api
+```
+
+Concurrency (`concurrency_modifier`), job cancel, refresh-worker, and the run / runsync /
+stream / status / cancel / health HTTP endpoints live in
+[references/serverless-workers.md](references/serverless-workers.md).
+
+## Templates & images
+
+A custom template is a Docker image plus environment variables. Pin the base; an unpinned
+or `:latest` base re-pulls on cold start and lengthens it.
+
+```dockerfile
+# Pin the CUDA base — never bare :latest.
+FROM runpod/base:0.6.2-cuda12.4.1
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY handler.py .
+
+# The worker entrypoint runs the handler.
+CMD ["python", "-u", "handler.py"]
+```
+
+**vLLM shortcut.** For OpenAI-compatible LLM serving, use the prebuilt `worker-vllm` image
+instead of writing a handler. Its `AsyncEngineArgs` are set via UPPERCASE env vars:
+
+```bash
+# Template env vars on the endpoint — these map to vLLM AsyncEngineArgs.
+MODEL_NAME=mistralai/Mistral-7B-Instruct-v0.3
+MAX_MODEL_LEN=8192
+```
+
+## Network volumes
+
+Attach a network volume when data outgrows what you want in the image:
+
+- Datasets larger than container disk.
+- Weights shared across many workers (download once, mount everywhere).
+- Checkpoints that must survive a worker / pod restart.
+
+Two traps to state up front:
+
+1. **A volume locks the endpoint/pod to one data center** and adds network latency. That
+   shrinks the pool of available GPUs in that DC — you can get stuck waiting for capacity.
+2. **Idle volume cost is double.** Pod volume disk bills ~$0.10/GB/mo while running but
+   ~$0.20/GB/mo while the pod is stopped. A forgotten volume on a stopped pod bleeds money.
+
+Rule: **bake small, static weights into the image**; reserve volumes for large mutable
+data (datasets, checkpoints). Full storage tables are in
+[references/cost-and-scaling.md](references/cost-and-scaling.md).
+
+## Cost control — the four knobs that move the bill
+
+| Knob | Default | What it does |
+| --- | --- | --- |
+| **Idle Timeout** | 5s | How long a worker stays warm (and billed) after a job. Lower for spiky traffic; raise to dodge repeated cold starts. |
+| **Execution Timeout** | 600s | Max single-job duration (range 5s–7 days). Set it so a hung job cannot run for days. |
+| **Max Workers** | — | Your concurrency cap *and* cost ceiling. Never leave it sky-high; set ~20% over expected peak. |
+| **Active Workers** | 0 | Always-warm minimum: zero cold start but billed 24/7 (at ~40% off the flex rate). Use only when a latency SLA demands it. |
+
+Plus **FlashBoot**: enable it on flex workers to cut cold start (model load into GPU
+memory) toward sub-200ms by caching, so flex stops feeling slow.
+
+Worked example — 100k requests/day, ~2s each on RTX 4090 serverless (~$1.10/hr equiv):
+
+- Compute is ~55.5 GPU-hours/day regardless of mode → roughly **$61/day** of actual work.
+- **Flex** adds idle-timeout tails per cold worker but nothing during true idle — best for
+  bursty business-hours traffic.
+- **Active workers** remove cold starts but bill 24/7; only worth it if traffic is steady
+  enough that the 40% discount beats paying for idle.
+- A **dedicated Pod** at ~$0.69/hr = ~$497/mo flat — wins only if utilization stays high.
+
+Full active-vs-flex math and monthly scenarios: [references/cost-and-scaling.md](references/cost-and-scaling.md).
+
+## Driving resources
+
+`runpodctl` is the open-source CLI. It outputs **JSON by default** (agent-friendly); add
+`--output table` or `--output yaml` for humans. Pods ship with it pre-installed using a
+pod-scoped key.
+
+```bash
+runpodctl serverless list                 # JSON by default
+runpodctl serverless get <endpoint-id>
+runpodctl serverless update <endpoint-id> --output table
+runpodctl get pod --output table
+```
+
+Python SDK for programmatic control — key from env, never in source:
+
+```python
+import os, runpod
+
+runpod.api_key = os.environ["RUNPOD_API_KEY"]  # never a literal
+
+pod = runpod.create_pod(name="train", image_name="my/img:1.0", gpu_type_id="NVIDIA A100 80GB PCIe")
+runpod.stop_pod(pod["id"])      # also resume_pod / terminate_pod
+
+ep = runpod.Endpoint("<endpoint-id>")
+job = ep.run({"prompt": "hi"})  # async: job.status(), job.output()
+out = ep.run_sync({"prompt": "hi"})  # blocks, ~90s max
+```
+
+Rule: read the API key from `RUNPOD_API_KEY`. A leaked key is a stranger spending on your GPUs.
+
+## Anti-patterns
+
+| Bad | Good | Why |
+| --- | --- | --- |
+| Max Workers left unbounded / sky-high | Bound it ~20% over peak | One traffic spike scales to an unbounded bill. |
+| H100 by default | Smallest GPU that fits VRAM | ~7x cost for zero speedup when the model fits an L40S/4090. |
+| 6-hour training run on Serverless | Run it on a Pod | Serverless premium + 600s execution timeout kills long jobs. |
+| Hardcoded API key in source | `os.environ["RUNPOD_API_KEY"]` | A leaked key = a stranger's GPU bill on your card. |
+| Weights downloaded at cold start | Bake into image or mount a volume | Every cold start re-downloads and pays for the wait. |
+| Active workers "just in case" | Flex + FlashBoot | Active bills 24/7; FlashBoot makes flex cold starts cheap. |
+| Volume left on a stopped pod | Detach / delete when idle | Idle volume bills ~$0.20/GB/mo silently. |
+| Push image, debug on the platform | `python worker.py --rp_serve_api` first | Debugging on cold-start seconds is slow and costs money. |
+
+## Verify
+
+Run `bash scripts/verify.sh <worker-dir>` to statically lint a worker directory: it checks
+for `runpod.serverless.start`, a handler with a return/yield, no hardcoded API key, a
+bounded `max_workers` plus timeout keys in any config, and a pinned `FROM` + `CMD` in a
+Dockerfile. Pure grep/parse — no network, no RunPod account. It exits 0 on an empty dir.

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

@@ -0,0 +1,11 @@
+# Evals — runpod
+
+These cases are a manual sanity check on routing and coverage, not an automated harness.
+To run them, read `cases.yaml` and confirm three things by hand: a fresh agent fires this
+skill on every `should_trigger` prompt (including the cost-symptom and cold-start ones that
+never say "serverless"); it defers to the named `route_to` sibling on each
+`should_not_trigger` prompt instead of grabbing the work; and given the `capability`
+scenario it produces an answer hitting every item in the `must_include` rubric (flex over a
+24/7 Pod with reasoning, a right-sized GPU instead of H100, bounded Max Workers, explicit
+idle/execution timeouts, FlashBoot, a `runpod.serverless.start` handler or worker-vllm, env
+API key, and a local test step). No network or RunPod account is involved.

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

@@ -0,0 +1,47 @@
+skill: runpod
+
+should_trigger:
+  - prompt: "Deploy my fine-tuned Llama as a RunPod serverless endpoint with vLLM."
+    why: Direct serverless deployment plus the worker-vllm path — core of the skill.
+  - prompt: "My RunPod bill exploded this month and the workers never seem to scale down."
+    why: Cost / idle-timeout / max-workers symptom with no 'serverless' keyword; the non-obvious cost-control trigger.
+  - prompt: "Write me a handler(job) function and start the serverless worker."
+    why: Handler authoring — the runpod.serverless.start pattern.
+  - prompt: "Necesito entrenar un modelo en una GPU H100 por horas, ¿pod o serverless en RunPod?"
+    why: Spanish phrasing of the Pod-vs-Serverless decision plus SKU pick.
+  - prompt: "Should I use a network volume or bake the weights into the container image on RunPod?"
+    why: Volume-vs-image decision; non-obvious framing of the storage/template tradeoff.
+  - prompt: "Cold starts on my endpoint are 20 seconds, how do I make them faster?"
+    why: FlashBoot / active-worker tuning; non-obvious, no provider named but RunPod endpoint context.
+
+should_not_trigger:
+  - prompt: "Deploy this model with Python-native autoscaling and snapshots, no Dockerfile."
+    route_to: modal
+    why: Snapshot autoscaling with no container is Modal's niche, not RunPod's image-based workers.
+  - prompt: "Call the SDXL endpoint on Replicate and get the image URL back."
+    route_to: replicate
+    why: Hosted prebuilt model API the user does not self-host — not RunPod GPU rental.
+  - prompt: "Download Mistral-7B weights from the Hub and push my fine-tune back."
+    route_to: huggingface
+    why: Hub artifact transfer, not GPU compute.
+  - prompt: "Run Llama 3 locally on my Mac with Ollama."
+    route_to: ollama
+    why: Local on-device inference, not cloud GPU.
+  - prompt: "Containerize my FastAPI service with a multi-stage Dockerfile."
+    route_to: docker
+    why: Generic containerization unrelated to RunPod's worker image shape.
+  - prompt: "Build a cross-provider GPU spend dashboard across AWS, GCP and RunPod."
+    route_to: cost-tracking
+    why: Provider-agnostic cost attribution, not RunPod-specific knobs.
+
+capability:
+  - scenario: "I serve a 7B LLM, about 100k requests/day at ~2s each, bursty during business hours. Set up a cost-efficient RunPod serverless endpoint."
+    must_include:
+      - Recommends Serverless (flex) over a 24/7 Pod for bursty traffic, with utilization reasoning.
+      - Picks a right-sized GPU (e.g. RTX 4090 or L40S), not H100 by default.
+      - Sets Max Workers as a bounded cost ceiling (~20% over peak).
+      - Sets Idle Timeout and Execution Timeout explicitly rather than leaving defaults.
+      - Enables FlashBoot to cut cold-start cost on flex workers.
+      - Worker uses runpod.serverless.start and reads job["input"], or uses worker-vllm with MODEL_NAME env var.
+      - Reads the API key from RUNPOD_API_KEY env, never hardcoded.
+      - Mentions local test (python worker.py --rp_serve_api or test_input.json) before deploying.

package/skills/shared/runpod/references/cost-and-scaling.md

@@ -0,0 +1,85 @@
+# Cost & scaling
+
+Full pricing and the math behind the SKILL.md "Cost control" section. All figures dated
+**2026-06-02**; Community Cloud runs lower than Secure Cloud, so treat these as upper bounds.
+Always reprice against https://www.runpod.io/pricing before committing.
+
+## Pod pricing (per hour)
+
+| GPU | VRAM | ~$/hr |
+| --- | --- | --- |
+| H100 SXM | 80GB | $3.29 |
+| H100 PCIe | 80GB | $2.89 |
+| A100 80GB PCIe | 80GB | $1.39 |
+| L40S | 48GB | $0.86 |
+| RTX 4090 | 24GB | $0.69 |
+| A40 | 48GB | $0.44 |
+| L4 | 24GB | $0.39 |
+
+## Serverless pricing (per-hour equivalent, billed per second rounded up)
+
+Billed only while a worker is active, from start to full stop. Roughly 2-3x the pod rate.
+
+| GPU | VRAM | ~$/hr equiv |
+| --- | --- | --- |
+| H100 | 80GB | $4.18 |
+| A100 | 80GB | $2.72 |
+| L40 / L40S | 48GB | $1.90 |
+| RTX 4090 | 24GB | $1.10 |
+| L4 / A5000 / RTX 3090 | 24GB | $0.69 |
+
+## Storage pricing
+
+| Storage | ~$/GB/mo |
+| --- | --- |
+| Container disk | $0.10 |
+| Network volume, standard, under 1TB | $0.07 |
+| Network volume, standard, over 1TB | $0.05 |
+| Network volume, high-performance | $0.14 |
+| Pod volume disk, running | $0.10 |
+| Pod volume disk, idle (stopped pod) | $0.20 |
+
+The idle rate is **double** the running rate. A volume left on a stopped pod is a silent
+leak. Network volumes also lock the endpoint/pod to a single data center, shrinking GPU
+availability and adding network latency.
+
+## Active vs flex math
+
+- **Flex workers** spin up on demand → cold start, but bill nothing while idle. Best when
+  traffic has real gaps.
+- **Active workers** stay always-warm → zero cold start, but bill every second 24/7 at a
+  **~40% discount** vs the flex rate.
+
+Break-even intuition: an active worker pays off versus flex only when it would otherwise be
+spun up often enough that paying the discounted always-warm rate beats paying flex's
+per-request seconds plus idle-timeout tails. For genuinely bursty traffic, flex + FlashBoot
+almost always wins.
+
+## Worked monthly scenarios
+
+Assume RTX 4090: pod $0.69/hr, serverless $1.10/hr equiv.
+
+1. **Bursty inference, 100k req/day, 2s each, business hours.**
+   ~55.5 GPU-hours/day of real work → ~$61/day on flex serverless plus small idle-timeout
+   tails. A 24/7 pod is ~$497/mo flat. With work concentrated in ~8 hours, **flex wins** —
+   you do not pay for the 16 idle hours.
+
+2. **Steady 24/7 inference at high utilization.**
+   If the GPU is busy >60% of every hour, the serverless 2-3x premium overtakes a flat pod.
+   **A dedicated Pod (~$497/mo) wins.** If a latency SLA forbids cold starts but utilization
+   is moderate, active serverless (40% off flex) is the middle ground.
+
+3. **Fine-tuning, single 6-hour run, A100 80GB.**
+   ~6 × $1.39 = ~$8.34 on a Pod. On serverless the 600s default execution timeout would kill
+   the job outright, and the premium rate makes it pointless. **Pod, always.**
+
+## Scaling strategy knobs
+
+Endpoints scale workers up by one of two scalers:
+
+- **Queue Delay** — add a worker when requests wait longer than a threshold. Smooths latency.
+- **Request Count** — add a worker per N queued requests. Predictable throughput scaling.
+
+Always pair either with **Max Workers ~20% above expected peak** as the hard cost ceiling,
+and **Active Workers** only when an SLA forbids cold starts. Enable **FlashBoot** on flex to
+make scale-from-zero cheap.