rsc-universal 0.1.1

package/skills/electron/scripts/verify.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# NAME
+#   verify.sh — Electron insecure-pattern gate
+#
+# USAGE
+#   ./verify.sh [TARGET_DIR]
+#
+#   With TARGET_DIR: scans that Electron project's source for insecure
+#   patterns and exits non-zero if any are found.
+#   With no argument: self-checks THIS skill's own example code fences — the
+#   recommended ("Good") snippets must be clean and must contain the secure
+#   baseline. Fences flagged with a `// Bad` comment are intentional
+#   counter-examples and are skipped; prose, tables, and checklists (which
+#   legitimately NAME the banned patterns) are not scanned.
+#
+# WHAT IT FLAGS (each = FAIL)
+#   nodeIntegration: true            renderer gets full Node → XSS becomes RCE
+#   contextIsolation: false          page can rewrite the preload bridge
+#   sandbox: false                   renderer escapes the OS sandbox
+#   @electron/remote                 direct renderer→main escalation path
+#   new BrowserView                  deprecated since Electron 30
+#   exposeInMainWorld(..., ipcRenderer)  universal IPC weapon (empty obj now)
+#
+# GUARANTEES
+#   - Read-only: never writes to or modifies the target.
+#   - Exits 0 on an empty or clean target (no false failure).
+#   - Portable to stock macOS bash 3.2 (no mapfile/associative arrays).
+#
+# EXIT CODES
+#   0  clean (or empty target)
+#   1  at least one insecure pattern found
+#   2  bad usage (target path does not exist)
+# ============================================================================
+
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+  RED=$'\033[31m'; GRN=$'\033[32m'; YLW=$'\033[33m'; RST=$'\033[0m'
+else
+  RED=''; GRN=''; YLW=''; RST=''
+fi
+
+FAILED=0
+ok()   { printf '%sPASS%s %s\n' "$GRN" "$RST" "$1"; }
+bad()  { printf '%sFAIL%s %s\n' "$RED" "$RST" "$1"; FAILED=1; }
+info() { printf '%s•%s    %s\n' "$YLW" "$RST" "$1"; }
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(dirname "$SCRIPT_DIR")"
+
+PAT_NODEINT='nodeIntegration[[:space:]]*:[[:space:]]*true'
+PAT_CTXISO='contextIsolation[[:space:]]*:[[:space:]]*false'
+PAT_SANDBOX='sandbox[[:space:]]*:[[:space:]]*false'
+PAT_REMOTE='@electron/remote'
+PAT_BROWSERVIEW='new[[:space:]]+BrowserView'
+PAT_EXPOSE='exposeInMainWorld\([^,]*,[[:space:]]*ipcRenderer[[:space:]]*\)'
+
+scan_lines() { # $1=label $2=pattern $3=haystack ; runs in the CURRENT shell so
+               # FAILED mutations stick (a pipe would fork a subshell and lose them)
+  local label="$1" pat="$2" hits
+  hits="$(printf '%s\n' "$3" | grep -nE "$pat" || true)"
+  if [ -n "$hits" ]; then
+    bad "$label"
+    printf '%s\n' "$hits" | sed 's/^/       /'
+  else
+    ok "$label"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+if [ "$#" -ge 1 ]; then
+  # ---- TARGET MODE: scan a real Electron project's source files ----------
+  TARGET="$1"
+  if [ ! -e "$TARGET" ]; then
+    printf '%sverify.sh: target does not exist: %s%s\n' "$RED" "$TARGET" "$RST" >&2
+    exit 2
+  fi
+  printf 'Scanning %s (target mode)\n\n' "$TARGET"
+
+  SRC="$(
+    find "$TARGET" \
+      \( -name node_modules -o -name .git -o -name dist -o -name out \) -prune -o \
+      \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.mjs' -o -name '*.cjs' \) \
+      -type f -print 2>/dev/null || true
+  )"
+  if [ -z "$SRC" ]; then
+    info "no Electron source files found under $TARGET"
+    ok "clean (nothing to check)"
+    exit 0
+  fi
+
+  # Concatenate source as file:line so findings point somewhere useful.
+  ALL="$(printf '%s\n' "$SRC" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -nH '' "$f" 2>/dev/null || true
+  done)"
+
+  scan_lines "no nodeIntegration: true"                 "$PAT_NODEINT"     "$ALL"
+  scan_lines "no contextIsolation: false"               "$PAT_CTXISO"      "$ALL"
+  scan_lines "no sandbox: false"                        "$PAT_SANDBOX"     "$ALL"
+  scan_lines "no @electron/remote"                      "$PAT_REMOTE"      "$ALL"
+  scan_lines "no new BrowserView (use WebContentsView)" "$PAT_BROWSERVIEW" "$ALL"
+  scan_lines "no ipcRenderer over contextBridge"        "$PAT_EXPOSE"      "$ALL"
+
+else
+  # ---- SELF MODE: vet the skill's own "Good" code fences -----------------
+  printf 'Self-checking %s (self mode)\n\n' "$SKILL_DIR"
+  DOCS="$(find "$SKILL_DIR" -type f \( -name 'SKILL.md' -o -path '*/references/*.md' \) 2>/dev/null || true)"
+
+  # Extract only code-fence bodies, dropping any fence that is marked as a
+  # `// Bad` counter-example. Prose/tables/checklists are never scanned.
+  GOOD="$(
+    printf '%s\n' "$DOCS" | while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      awk '
+        /^```/      { infence = !infence; if (infence) { buf=""; bad=0 } else { if (!bad) printf "%s", buf }; next }
+        infence     { if ($0 ~ /\/\/[[:space:]]*Bad/) bad=1; buf = buf $0 "\n" }
+      ' "$f"
+    done
+  )"
+
+  scan_lines "Good snippets: no nodeIntegration: true"   "$PAT_NODEINT"     "$GOOD"
+  scan_lines "Good snippets: no contextIsolation: false" "$PAT_CTXISO"      "$GOOD"
+  scan_lines "Good snippets: no sandbox: false"          "$PAT_SANDBOX"     "$GOOD"
+  scan_lines "Good snippets: no @electron/remote import" "$PAT_REMOTE"      "$GOOD"
+  scan_lines "Good snippets: no new BrowserView"         "$PAT_BROWSERVIEW" "$GOOD"
+  scan_lines "Good snippets: no exposed ipcRenderer"     "$PAT_EXPOSE"      "$GOOD"
+
+  # Positive assertion: the secure baseline must actually appear somewhere.
+  for tok in 'nodeIntegration: false' 'contextIsolation: true' 'sandbox: true'; do
+    if printf '%s\n' "$GOOD" | grep -qF "$tok"; then ok "baseline present: $tok"
+    else bad "baseline missing from example snippets: $tok"; fi
+  done
+fi
+
+echo
+if [ "$FAILED" -eq 0 ]; then
+  ok "no insecure Electron patterns found"
+else
+  printf '%sinsecure patterns present — fix before shipping%s\n' "$RED" "$RST" >&2
+fi
+exit "$FAILED"

package/skills/elixir/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: elixir
+description: "Use when writing or refactoring Elixir/OTP code — GenServers, supervision trees, processes, pattern matching, mix projects and releases — or when BEAM behaviour misbehaves (restart loops, mailbox growth, timeouts). Triggers: 'write a GenServer', 'design a supervision tree', 'restart strategy one_for_one', 'let it crash instead of try/rescue', 'mix release for production', non-obvious 'my process mailbox keeps growing', 'GenServer call timeout / restart loop', Catalan 'arbre de supervisio en Elixir / processos que peten', Spanish 'arbol de supervision / procesos en Elixir / que es let it crash'. NOT building a Phoenix web app, LiveView, Ecto schemas, controllers or channels (that is phoenix)."
+tags: [elixir, otp, genserver, supervision, beam, mix, concurrency, functional]
+recommends: [phoenix, postgresdb, docker]
+origin: risco
+---
+
+# Elixir
+
+You are writing Elixir on the BEAM. The runtime gives you cheap isolated processes, preemptive scheduling, and supervision. The single mental shift that separates idiomatic Elixir from ported imperative code: **let it crash and supervise it, do not defend every call**. A process that hits an impossible state should die and be restarted clean by its supervisor — that is more correct than a `try/rescue` that limps on with corrupt state.
+
+Default to **pure functions**. Most of your code is data transformation and needs no process at all. Reach for a process only when you need state, concurrency, or fault isolation. Target Elixir **v1.19.5** (stable, requires Erlang/OTP 28.1+) or **v1.20-rc** (full type inference, OTP 27+/29). Use the modern stdlib: built-in `JSON`, set-theoretic type warnings, `mix format`.
+
+## Decision: do you even need a process?
+
+A process is not "an object". Spawning one to hold a value you could pass as an argument is the most common beginner mistake — it adds a serialization bottleneck and a failure mode for nothing.
+
+| Situation | Use | Why |
+|---|---|---|
+| Pure transform of input -> output | plain function / module | No state, no concurrency: a process only adds overhead and a mailbox |
+| Hold mutable state behind an API | `GenServer` (or `Agent` for trivial state) | Serializes access, owns a lifecycle, supervisable |
+| Run N independent jobs concurrently | `Task.async_stream` / `Task.Supervisor` | Bounded fan-out, results collected, crashes isolated |
+| Isolate a risky/external boundary | a supervised process | A crash there restarts clean without taking down callers |
+| Shared read-heavy cache | `:ets` table | Concurrent lock-free reads, no single-process bottleneck |
+
+Rule: if two pieces of code never run at the same time and share no mutable state, they are functions, not processes.
+
+## The functional core
+
+Each rule below earns its place; the why is one line.
+
+**Match in function heads, not with `if`** — branches become exhaustive and self-documenting, and a non-match crashes loudly instead of silently falling through.
+
+```elixir
+# Bad - imperative branching, easy to miss a case
+def area(shape) do
+  if shape.type == :circle do
+    :math.pi() * shape.r * shape.r
+  else
+    shape.w * shape.h
+  end
+end
+
+# Good - one clause per shape, unmatched input crashes (which a supervisor handles)
+def area(%Circle{r: r}), do: :math.pi() * r * r
+def area(%Rect{w: w, h: h}), do: w * h
+```
+
+**Return tagged tuples `{:ok, value}` / `{:error, reason}`** — the caller pattern-matches the outcome; this is the protocol the whole ecosystem speaks.
+
+```elixir
+# Good
+def fetch(id) do
+  case Repo.get(id) do
+    nil -> {:error, :not_found}
+    record -> {:ok, record}
+  end
+end
+```
+
+**Chain fallible steps with `with`** — it reads as the happy path and short-circuits on the first non-match, no nested `case` pyramids.
+
+```elixir
+# Good - any step returning a non-{:ok, _} falls straight to else
+with {:ok, user} <- fetch_user(id),
+     {:ok, acct} <- fetch_account(user),
+     :ok <- authorize(acct) do
+  {:ok, acct}
+else
+  {:error, reason} -> {:error, reason}
+end
+```
+
+**Use guards to constrain clauses** (`when is_integer(n) and n > 0`) — keeps validation declarative and lets the compiler reason about types.
+
+**Pipe left-to-right for data flowing through transforms** — `data |> step1() |> step2()`. Do not pipe just to avoid an intermediate variable; if a step needs the value in a non-first argument, name it.
+
+**There is no mutation.** Rebinding `x = f(x)` makes a new binding; data you passed elsewhere is unchanged. Stop reaching for mutable accumulators — use `Enum.reduce/3`, comprehensions, or recursion.
+
+## Processes and message passing
+
+Raw `spawn`/`send`/`receive` exists, but in production you almost always want an OTP behaviour (GenServer/Task/Agent) so you get `child_spec`, supervision, and shutdown handling for free.
+
+- **Link** (`spawn_link`) couples lifetimes: if one dies abnormally, the other gets an exit signal. This is how supervision works.
+- **Monitor** (`Process.monitor/1`) is one-directional and non-fatal: you get a `{:DOWN, ...}` message but you do not die. Use it when you care *that* something died but should survive it.
+
+Drop to raw processes only for a throwaway fire-and-forget where supervision genuinely does not matter; otherwise reach for OTP.
+
+## GenServer
+
+Split the **client API** (runs in the caller) from the **server callbacks** (run in the GenServer process). Callers never touch state directly.
+
+```elixir
+defmodule Counter do
+  use GenServer
+
+  # --- Client API (caller's process) ---
+  def start_link(opts) do
+    GenServer.start_link(__MODULE__, opts[:start] || 0, name: opts[:name] || __MODULE__)
+  end
+
+  @spec increment(GenServer.server()) :: :ok
+  def increment(server \\ __MODULE__), do: GenServer.cast(server, :increment)
+
+  @spec value(GenServer.server()) :: integer()
+  def value(server \\ __MODULE__), do: GenServer.call(server, :value)
+
+  # --- Server callbacks (GenServer's process) ---
+  @impl true
+  def init(start), do: {:ok, start, {:continue, :warm_up}}
+
+  @impl true
+  def handle_continue(:warm_up, state) do
+    # heavy/slow init goes here, AFTER start_link has returned
+    {:noreply, state}
+  end
+
+  @impl true
+  def handle_cast(:increment, count), do: {:noreply, count + 1}
+
+  @impl true
+  def handle_call(:value, _from, count), do: {:reply, count, count}
+end
+```
+
+Rules, each with its why:
+
+- **Never block in `init/1`.** `start_link` blocks until `init` returns, so a slow `init` stalls the whole supervision tree boot. Return `{:ok, state, {:continue, term}}` and do the work in `handle_continue/2`.
+- **`use GenServer` auto-defines `child_spec/1`** — you rarely write one by hand; override only to change `:restart` or `:shutdown`.
+- **`call` is synchronous (with a 5s default timeout), `cast` is fire-and-forget.** Use `call` when the caller needs the result or backpressure; `cast` when it does not. A flood of `cast`s with no backpressure is the classic mailbox-growth bug — see references/otp-patterns.md.
+- **Name via `Registry`, not a global atom**, when you have many dynamic instances — atoms are never garbage-collected (see anti-patterns).
+
+## Supervision trees
+
+The supervision tree starts in `lib/<app>/application.ex`, wired via the `mod:` key in `mix.exs`. `mix new <app> --sup` scaffolds this.
+
+```elixir
+defmodule MyApp.Application do
+  use Application
+
+  @impl true
+  def start(_type, _args) do
+    children = [
+      {Registry, keys: :unique, name: MyApp.Registry},
+      {DynamicSupervisor, name: MyApp.WorkerSup, strategy: :one_for_one},
+      Counter
+    ]
+
+    Supervisor.start_link(children, strategy: :one_for_one, name: MyApp.Supervisor)
+  end
+end
+```
+
+**Restart strategy** — how siblings react when one child dies:
+
+| Strategy | On a child crash | Use when |
+|---|---|---|
+| `:one_for_one` | restart only that child | children are independent (the default, most common) |
+| `:one_for_all` | restart all children | children depend on each other and shared state is invalidated |
+| `:rest_for_one` | restart that child and the ones started after it | later children depend on earlier ones |
+
+**Restart value** per child — `:permanent` (always restart, the default), `:transient` (restart only on abnormal exit), `:temporary` (never restart). A pool worker is often `:transient`; a one-shot job is `:temporary`.
+
+**Let it crash**: do not wrap business logic in `try/rescue` to keep a process alive. Validate inputs at the boundary, then trust the happy path; if an invariant breaks, crashing and restarting from a known-good `init` state is the recovery mechanism. Reserve `rescue` for boundaries where you must convert an exception into a tagged tuple for a caller.
+
+For runtime-spawned children (a worker per connection/job) use `DynamicSupervisor` + `Registry` for lookup. Full recipe in references/otp-patterns.md.
+
+## mix project
+
+```text
+my_app/
+  mix.exs               # project, deps, application/0 with mod: callback
+  config/
+    config.exs          # compile-time config (read once, at build)
+    runtime.exs         # runtime config — reads System.get_env at boot
+  lib/
+    my_app.ex
+    my_app/
+      application.ex     # supervision tree
+  test/
+```
+
+- **`config.exs` is compile-time; `runtime.exs` is runtime.** Anything coming from the environment of the running release (DB URL, secrets, ports) goes in `runtime.exs` — it is the only config evaluated inside the built release at boot. Putting secrets in `config.exs` bakes build-time values into the artifact.
+- **`mix release`** produces a self-contained tarball with its own ERTS; no Elixir/Erlang needed on the target. Run it with `bin/<app> start`.
+
+```bash
+MIX_ENV=prod mix release
+_build/prod/rel/my_app/bin/my_app start
+```
+
+Deps anatomy, environments, env vars, and the umbrella decision live in references/mix-and-releases.md.
+
+## Types and modern stdlib
+
+- **Add `@spec` to public functions.** The set-theoretic type system (gradual, sound; v1.18 inferred patterns/calls, v1.19 added protocol + anonymous-fn inference, v1.20 targets full inference) uses them and surfaces warnings at compile time — **treat type warnings as bugs**, they catch real mismatches before runtime.
+- **Use built-in `JSON`** (`JSON.encode!/1`, `JSON.decode!/1`, since v1.18) for basic encoding/decoding — no Jason/Poison dependency needed unless you require their extras.
+- **`mix format`** is the canonical formatter; run it and gate CI on `mix format --check-formatted`.
+- **`mix compile --warnings-as-errors`** in CI. Dialyzer and Credo are optional add-ons, not required for correct OTP code.
+- v1.19 perf: lazy module loading (>2x faster compiles on large projects) and `MIX_OS_DEPS_COMPILE_PARTITION_COUNT` for parallel dep compilation.
+
+## Anti-patterns
+
+| Bad | Why it bites | Do instead |
+|---|---|---|
+| `String.to_atom(user_input)` | Atoms are never garbage-collected; attacker-controlled input exhausts the atom table and crashes the VM | `String.to_existing_atom/1`, or keep it a string / map key |
+| One god GenServer all calls route through | Serializes everything into one mailbox — a hard concurrency ceiling and a single point of failure | Split by responsibility; use a `Registry` of per-entity processes or `Task` for parallel work |
+| Heavy work inside `init/1` | `start_link` blocks until `init` returns, stalling the supervision tree boot | `{:ok, state, {:continue, msg}}` + `handle_continue/2` |
+| `try/rescue` wrapping all logic | Defeats let-it-crash; the process limps on with corrupt state | Validate at the boundary, trust the path, let the supervisor restart |
+| A new process per trivial call | Spawn + mailbox + scheduling overhead for nothing | A plain function; processes are for state/concurrency/isolation |
+| Unbounded `cast` into a slow GenServer | Producer outruns consumer, mailbox grows without bound, OOM | Use `call` for backpressure, or a bounded queue / `GenStage` |
+
+## Verify
+
+Run `scripts/verify.sh` from your mix project root (the directory containing `mix.exs`). It checks `mix format --check-formatted` and `mix compile --warnings-as-errors`, and skips cleanly with exit 0 when Elixir/mix is not installed so it never blocks a toolchain-free CI.
+
+See references/otp-patterns.md (DynamicSupervisor+Registry, Task, Agent, ETS, timeouts/backpressure, choosing an OTP behaviour) and references/mix-and-releases.md (mix.exs anatomy, config vs runtime, releases, umbrellas).

package/skills/elixir/evals/README.md

@@ -0,0 +1,3 @@
+# Evals: elixir
+
+These cases are illustrative, not an automated grader. To run them by hand, read each `should_trigger` prompt and confirm the skill would fire (especially the non-obvious mailbox-growth and blocking-init cases and the Catalan/Spanish phrasings); then read each `should_not_trigger` prompt and confirm you would instead route to the named sibling (`phoenix` for web/LiveView/Ecto, `go` for goroutines, `postgresdb` for DB tuning) rather than answering as Elixir. For the `capability` case, give the scenario to the agent and check the produced code against the `must_include` rubric line by line — every item should be present and idiomatic (client/server split, DynamicSupervisor + Registry, child_spec, `@spec`, no blanket `try/rescue`, tagged tuples, a real mix layout). Score it as pass only if nothing in the rubric is missing or faked.

package/skills/elixir/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: elixir
+
+should_trigger:
+  - prompt: "Write me a GenServer that keeps a counter and supports increment and get."
+    why: Core GenServer authoring — client API + callbacks + child_spec, the central capability.
+  - prompt: "Design a supervision tree for a worker pool that restarts crashed workers."
+    why: Supervision strategy and restart values, the OTP design layer this skill owns.
+  - prompt: "How do I structure 'let it crash' instead of wrapping everything in try/rescue?"
+    why: BEAM failure philosophy; the mental shift the skill is built around.
+  - prompt: "Set up a mix release so I can deploy my Elixir app to production."
+    why: mix project, runtime.exs vs config.exs, and `mix release` packaging.
+  - prompt: "Els meus processos d'Elixir acumulen missatges al mailbox i acaben petant, com ho arreglo?"
+    why: Catalan, non-obvious symptom — unbounded mailbox growth from cast flooding / slow handlers.
+  - prompt: "Mi GenServer entra en un bucle de reinicios al arrancar, creo que el init bloquea."
+    why: Spanish, non-obvious — blocking init stalling the supervisor; route to handle_continue.
+
+should_not_trigger:
+  - prompt: "Build a LiveView page with a form and live validation."
+    route_to: phoenix
+    why: Web/LiveView is the Phoenix layer that builds its own tree on top of OTP.
+  - prompt: "Write an Ecto schema and a query with preloads for my users table."
+    route_to: phoenix
+    why: Ecto schemas/queries ship with the Phoenix sibling, not the bare language/OTP skill.
+  - prompt: "Use goroutines and channels to fan out work across CPUs."
+    route_to: go
+    why: Different runtime and concurrency model; the request names Go primitives.
+  - prompt: "Tune Postgres indexes and analyze a slow query plan."
+    route_to: postgresdb
+    why: Database tuning, unrelated to the BEAM or OTP.
+
+capability:
+  - scenario: "Build a token-bucket rate limiter as a supervised OTP service, one bucket process per API key, created on demand and addressable by key."
+    must_include:
+      - GenServer with a clear client API separated from server callbacks
+      - supervised under application.ex, with buckets started via DynamicSupervisor at runtime
+      - Registry-based naming ({:via, Registry, ...}) instead of dynamic global atoms
+      - child_spec via `use GenServer` (or an explicit override only if changing restart/shutdown)
+      - "@spec on the public functions"
+      - "let-it-crash: no blanket try/rescue around the bucket logic; supervisor restarts on crash"
+      - mix project structure (mix.exs application/0 with mod:, lib/ layout)
+      - tagged tuple returns ({:ok, _} / {:error, :rate_limited})

package/skills/elixir/references/mix-and-releases.md

@@ -0,0 +1,91 @@
+# mix project and releases
+
+Depth offloaded from SKILL.md.
+
+## mix.exs anatomy
+
+```elixir
+defmodule MyApp.MixProject do
+  use Mix.Project
+
+  def project do
+    [
+      app: :my_app,
+      version: "0.1.0",
+      elixir: "~> 1.19",
+      start_permanent: Mix.env() == :prod,
+      deps: deps()
+    ]
+  end
+
+  # application/0 — `mod:` names the Application module + start args.
+  # Omit `mod:` for a library that has no supervision tree of its own.
+  def application do
+    [
+      extra_applications: [:logger],
+      mod: {MyApp.Application, []}
+    ]
+  end
+
+  defp deps do
+    [
+      {:req, "~> 0.5"},
+      {:credo, "~> 1.7", only: [:dev, :test], runtime: false}
+    ]
+  end
+end
+```
+
+- `elixir: "~> 1.19"` pins the language line; `~>` allows patch/minor within the constraint.
+- Dev/test-only tooling uses `only:` and `runtime: false` so it is not shipped in a release.
+
+## Common mix tasks
+
+```bash
+mix deps.get                         # fetch deps
+mix compile --warnings-as-errors     # gate CI on this
+mix format                           # canonical formatter (write)
+mix format --check-formatted         # CI check (no write)
+mix test                             # run ExUnit
+mix release                          # build a self-contained release
+```
+
+## Config: config.exs vs runtime.exs
+
+| File | Evaluated | Put here |
+|---|---|---|
+| `config/config.exs` | compile time (at build) | static, non-secret, compile-time settings; `import_config "#{config_env()}.exs"` |
+| `config/runtime.exs` | runtime (release boot) | anything from `System.get_env/1` — DB URLs, secrets, ports, hostnames |
+
+`runtime.exs` is the **only** config evaluated inside a built release at startup. Build-time `config.exs` values are frozen into the artifact, so secrets and per-environment values belong in `runtime.exs`:
+
+```elixir
+# config/runtime.exs
+import Config
+
+if config_env() == :prod do
+  config :my_app, MyApp.Repo,
+    url: System.fetch_env!("DATABASE_URL"),
+    pool_size: String.to_integer(System.get_env("POOL_SIZE", "10"))
+end
+```
+
+## mix release
+
+`mix release` bundles your app, its deps, and the Erlang runtime (ERTS) into a tarball that runs on a target with no Elixir/Erlang installed.
+
+```bash
+MIX_ENV=prod mix release
+_build/prod/rel/my_app/bin/my_app start    # foreground
+_build/prod/rel/my_app/bin/my_app daemon   # background
+_build/prod/rel/my_app/bin/my_app remote   # connect a remote IEx shell
+```
+
+Set runtime env vars (read in `runtime.exs`) in the deployment environment, not baked into the image. A release plus a small Docker base image is a common production shape.
+
+## Umbrella projects: when and when not
+
+An umbrella is multiple in-repo apps under one `apps/` directory sharing config and deps.
+
+- **Use** when you have genuinely separate deployables/bounded contexts that you still want versioned and built together.
+- **Do not** reach for it to organize one app — plain `lib/` directories and module namespacing handle that, and umbrellas add ceremony (per-app mix.exs, cross-app dep wiring) you will regret for a single service. Start as one app; split to an umbrella only when a real boundary appears.

package/skills/elixir/references/otp-patterns.md

@@ -0,0 +1,96 @@
+# OTP patterns
+
+Depth offloaded from SKILL.md. Pick the lightest behaviour that fits.
+
+## Choosing an OTP behaviour
+
+| Need | Reach for | Notes |
+|---|---|---|
+| State behind a custom API, callbacks | `GenServer` | The workhorse; full control over messages |
+| Trivial state, get/update by function | `Agent` | A thin GenServer wrapper; no custom protocol |
+| One-off concurrent computation | `Task` | `Task.async/await`, or `Task.async_stream` for bounded fan-out |
+| Supervised fire-and-forget jobs | `Task.Supervisor` | Crashes isolated, no result needed |
+| Many dynamic, identical children | `DynamicSupervisor` + `Registry` | Start/stop children at runtime, look them up by key |
+| Explicit state machine with phases | `:gen_statem` (Erlang) | When transitions/events dominate; usable directly from Elixir |
+| Shared read-heavy data | `:ets` | Concurrent lock-free reads; one owner process holds the table |
+
+## DynamicSupervisor + Registry recipe
+
+Use this when you want one process per logical entity (per user, per connection, per token bucket) started on demand and addressable by a key.
+
+```elixir
+# In application.ex children, before the workers:
+#   {Registry, keys: :unique, name: MyApp.Registry},
+#   {DynamicSupervisor, name: MyApp.WorkerSup, strategy: :one_for_one}
+
+defmodule MyApp.Worker do
+  use GenServer
+
+  def start_link(id) do
+    GenServer.start_link(__MODULE__, id, name: via(id))
+  end
+
+  defp via(id), do: {:via, Registry, {MyApp.Registry, id}}
+
+  # Start (or return existing) a worker for `id`.
+  def ensure_started(id) do
+    case DynamicSupervisor.start_child(MyApp.WorkerSup, {__MODULE__, id}) do
+      {:ok, pid} -> {:ok, pid}
+      {:error, {:already_started, pid}} -> {:ok, pid}
+      other -> other
+    end
+  end
+
+  @impl true
+  def init(id), do: {:ok, %{id: id}}
+end
+```
+
+`{:via, Registry, {Registry, key}}` lets you address a process by `key` without ever touching its pid. The Registry entry is removed automatically when the process dies — no stale-pid bookkeeping.
+
+## Timeouts, backpressure, and mailbox growth
+
+- `GenServer.call/3` defaults to a **5000 ms** timeout. If the server is slow, the *caller* gets an `:timeout` exit. Raise the timeout only when the operation is legitimately long; otherwise the slowness is the bug.
+- A **growing mailbox** means messages arrive faster than `handle_*` drains them. Causes: an unbounded `cast` producer, an expensive `handle_info`, or a process doing too much. Fixes:
+  - Switch hot producers from `cast` to `call` so the caller blocks (natural backpressure).
+  - Move heavy work out of the GenServer (into a `Task` it supervises).
+  - Shard the work across many processes instead of one.
+  - For true streaming/backpressure, use `GenStage`/`Flow` (external deps).
+- `handle_continue/2` runs immediately after `init` (or after the returning callback) before the next message — use it for post-init warm-up so `start_link` returns fast.
+
+## Task and Task.Supervisor
+
+```elixir
+# Bounded concurrent fan-out — never spawns more than max_concurrency at once.
+ids
+|> Task.async_stream(&fetch/1, max_concurrency: 10, timeout: 30_000)
+|> Enum.map(fn {:ok, result} -> result end)
+
+# Supervised fire-and-forget (add {Task.Supervisor, name: MyApp.Tasks} to children):
+Task.Supervisor.start_child(MyApp.Tasks, fn -> do_async_thing() end)
+```
+
+Prefer `Task.async_stream` over manually spawning N tasks — it bounds concurrency and applies a per-item timeout.
+
+## Agent (when GenServer is overkill)
+
+```elixir
+{:ok, agent} = Agent.start_link(fn -> %{} end)
+Agent.update(agent, &Map.put(&1, :k, 1))
+Agent.get(agent, &Map.get(&1, :k))
+```
+
+Note: every `Agent.get`/`update` runs its function in the agent process — keep them tiny, or you recreate the god-process bottleneck.
+
+## ETS for shared read state
+
+```elixir
+:ets.new(:cache, [:named_table, :set, :public, read_concurrency: true])
+:ets.insert(:cache, {:key, value})
+case :ets.lookup(:cache, :key) do
+  [{:key, v}] -> {:ok, v}
+  [] -> :error
+end
+```
+
+ETS gives concurrent lock-free reads, so a read-heavy cache does not bottleneck on a single GenServer mailbox. Have one process own and create the table (so the table dies with it, or use `:heir` to transfer ownership on crash).

package/skills/elixir/scripts/verify.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# verify.sh — read-only checks for an Elixir/OTP target.
+#
+# Checks (only when the toolchain and artifacts are present):
+#   - `mix format --check-formatted` (style)
+#   - `mix compile --warnings-as-errors` (warning-free compile) at a mix project root
+#
+# Never blocks a toolchain-free or empty target: exits 0 with a skip note when
+# Elixir/mix is absent or there is nothing to check. No network, no writes.
+#
+# Usage: bash scripts/verify.sh [TARGET_DIR]   (default: current directory)
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify: target '$TARGET' is not a directory — nothing to check. SKIP."
+  exit 0
+fi
+
+# Toolchain gate: no mix on PATH -> skip cleanly (do not fail CI without a toolchain).
+if ! command -v mix >/dev/null 2>&1; then
+  echo "verify: 'mix' not found on PATH — Elixir toolchain not installed. SKIP."
+  exit 0
+fi
+
+# Find a mix project root (a directory containing mix.exs), shallowest first.
+mix_root=""
+if [ -f "$TARGET/mix.exs" ]; then
+  mix_root="$TARGET"
+else
+  mix_root="$(find "$TARGET" -maxdepth 4 -name mix.exs -not -path '*/deps/*' -not -path '*/_build/*' 2>/dev/null \
+    | awk '{ print gsub(/\//,"/"), $0 }' | sort -n | head -n1 | cut -d' ' -f2- || true)"
+  [ -n "$mix_root" ] && mix_root="$(dirname "$mix_root")"
+fi
+
+# Count loose Elixir sources in the target (excludes deps/_build).
+ex_count="$(find "$TARGET" \( -name '*.ex' -o -name '*.exs' \) \
+  -not -path '*/deps/*' -not -path '*/_build/*' 2>/dev/null | wc -l | tr -d ' ')"
+
+if [ -z "$mix_root" ] && [ "$ex_count" = "0" ]; then
+  echo "verify: no mix.exs and no .ex/.exs files under '$TARGET' — nothing to check. SKIP."
+  exit 0
+fi
+
+status=0
+
+if [ -n "$mix_root" ]; then
+  echo "verify: mix project root -> $mix_root"
+
+  echo "verify: mix format --check-formatted"
+  if ! ( cd "$mix_root" && mix format --check-formatted ); then
+    echo "verify: FAIL — files are not formatted (run: mix format)"
+    status=1
+  fi
+
+  echo "verify: mix compile --warnings-as-errors"
+  if ! ( cd "$mix_root" && mix compile --warnings-as-errors ); then
+    echo "verify: FAIL — compile produced warnings or errors"
+    status=1
+  fi
+else
+  # Loose .ex/.exs without a mix project: format check only (compile needs a project).
+  echo "verify: no mix.exs found; checking formatting of $ex_count loose Elixir file(s)"
+  echo "verify: mix format --check-formatted"
+  if ! ( cd "$TARGET" && mix format --check-formatted ); then
+    echo "verify: FAIL — files are not formatted (run: mix format)"
+    status=1
+  fi
+fi
+
+if [ "$status" -eq 0 ]; then
+  echo "verify: OK"
+fi
+exit "$status"