rsc-universal 0.1.1

package/skills/ruby/references/gems-and-testing.md

@@ -0,0 +1,208 @@
+# Gems, Bundler, and testing, in depth
+
+## bundle gem layout
+
+`bundle gem tally` scaffolds a conventional gem:
+
+```text
+tally/
+├── tally.gemspec
+├── Gemfile                 # usually just: gemspec
+├── Rakefile
+├── lib/
+│   ├── tally.rb            # requires lib/tally/version.rb, defines the module
+│   └── tally/
+│       └── version.rb      # Tally::VERSION = "0.1.0"
+├── sig/
+│   └── tally.rbs           # optional RBS signatures
+└── test/  (or spec/)
+    ├── test_helper.rb
+    └── tally_test.rb
+```
+
+`lib/tally.rb` is the entry point loaded by `require "tally"`. Keep the public API in
+the top-level module; put implementation in `lib/tally/`.
+
+## The .gemspec
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "lib/tally/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "tally"
+  spec.version     = Tally::VERSION
+  spec.summary     = "Count word frequencies."
+  spec.description = "A tiny, dependency-free word-frequency counter."
+  spec.authors     = ["You"]
+  spec.license     = "MIT"
+  spec.homepage    = "https://github.com/you/tally"
+
+  spec.required_ruby_version = ">= 3.4"
+  spec.files     = Dir["lib/**/*.rb", "README.md", "LICENSE.txt"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "thor", "~> 1.3"          # runtime dep, pessimistic constraint
+  spec.metadata["rubygems_mfa_required"] = "true"
+end
+```
+
+Declare development tools (rake, minitest, rubocop) in the `Gemfile`'s `:development`
+group or via `spec.add_development_dependency`, not as runtime deps.
+
+## SemVer and version constraints
+
+Versions are `MAJOR.MINOR.PATCH`. Bump MAJOR on a breaking change, MINOR on a
+backward-compatible feature, PATCH on a fix.
+
+| Constraint | Allows | Use for |
+|------------|--------|---------|
+| `~> 1.3`   | `>= 1.3.0, < 2.0` | Library deps — accept features and fixes, block breaks |
+| `~> 1.3.2` | `>= 1.3.2, < 1.4.0` | Pin to a patch line when a minor broke you |
+| `>= 1.3`   | any future major | Rarely; you are promising forward compat |
+| `= 1.3.2`  | exactly that | Last resort; you own the upgrade churn |
+
+`Gemfile.lock`: commit it for **applications** (reproducible installs everywhere); do
+**not** commit it for a published **library** gem — let each consumer resolve against
+their own dependency graph.
+
+## Publishing to RubyGems
+
+```bash
+gem build tally.gemspec          # produces tally-0.1.0.gem
+gem push tally-0.1.0.gem         # uploads to rubygems.org (needs an account + MFA)
+```
+
+`bundle exec rake release` automates tag + build + push when the Rakefile uses the
+Bundler gem tasks.
+
+## Rakefile with a test task
+
+```ruby
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test
+```
+
+Run with `bundle exec rake test` (or just `bundle exec rake`).
+
+## Minitest, full file
+
+Minitest ships with Ruby. Both an `assert`-style and a spec-style exist; assert-style
+is the low-ceremony default.
+
+```ruby
+# test/tally_test.rb
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "tally"
+
+class TallyTest < Minitest::Test
+  def setup
+    @sentence = "the cat the hat the"
+  end
+
+  def test_counts_each_word
+    assert_equal({ "the" => 3, "cat" => 1, "hat" => 1 }, Tally.count(@sentence))
+  end
+
+  def test_empty_string_is_empty_hash
+    assert_empty Tally.count("")
+  end
+
+  def test_raises_on_nil
+    assert_raises(TypeError) { Tally.count(nil) }
+  end
+end
+```
+
+## RSpec, full spec
+
+RSpec is the dominant third-party DSL. Use `let` for lazy fixtures, `subject` for the
+object under test, and `context` to group scenarios.
+
+```ruby
+# spec/tally_spec.rb
+# frozen_string_literal: true
+
+require "tally"
+
+RSpec.describe Tally do
+  describe ".count" do
+    subject(:counts) { described_class.count(sentence) }
+
+    context "with repeated words" do
+      let(:sentence) { "the cat the hat the" }
+
+      it { is_expected.to include("the" => 3) }
+      it { is_expected.to eq("the" => 3, "cat" => 1, "hat" => 1) }
+    end
+
+    context "with an empty string" do
+      let(:sentence) { "" }
+
+      it { is_expected.to be_empty }
+    end
+
+    context "with nil" do
+      let(:sentence) { nil }
+
+      it "raises" do
+        expect { counts }.to raise_error(TypeError)
+      end
+    end
+  end
+end
+```
+
+Run with `bundle exec rspec`. Add a `.rspec` file with `--require spec_helper` to load
+shared config.
+
+## The implementation, idiomatically
+
+The gem these tests describe — note `each_with_object`/`tally`, the magic comment, and
+the module namespace, with no metaprogramming:
+
+```ruby
+# lib/tally.rb
+# frozen_string_literal: true
+
+require_relative "tally/version"
+
+module Tally
+  def self.count(text)
+    text.split.tally          # Enumerable#tally does the whole job
+  end
+end
+```
+
+## RuboCop vs Standard
+
+```yaml
+# .rubocop.yml — full control, every cop tunable
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+Metrics/MethodLength:
+  Max: 15
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+```
+
+```ruby
+# Gemfile — zero-config alternative; no config file to bikeshed
+gem "standard", group: :development
+# run: bundle exec standardrb
+```
+
+Pick **Standard** when you want to end style arguments; pick **RuboCop** when the team
+wants to dial individual cops. Run whichever in CI as a non-negotiable gate.

package/skills/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/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/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 model inference. Triggers: deploying a vLLM or custom-model serverless endpoint, writing or debugging a handler(job) worker, building a worker Docker template, attaching a network volume, tuning idle/execution timeout, max/active workers, FlashBoot, or chasing a runaway RunPod bill or slow cold starts; 'mi factura de RunPod se disparó', 'pod o serverless en RunPod', 'workers que no escalan a cero', 'el cold start tarda 20s'. NOT generic 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: risco
+---
+
+# 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.