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

package/skills/shared/electron/references/security-and-ipc.md

@@ -0,0 +1,158 @@
+# Security & IPC — full hardened example
+
+The SKILL.md gives the rules; this is the copy-paste reference that puts them together.
+
+## Hardened `main.ts`
+
+```ts
+import { app, BrowserWindow, ipcMain, session, shell } from 'electron';
+import path from 'node:path';
+
+const APP_ORIGIN = 'https://app.local'; // or 'file://' for a fully local bundle
+
+function createWindow() {
+  const win = new BrowserWindow({
+    width: 1100,
+    height: 720,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      nodeIntegration: false,
+      contextIsolation: true,
+      sandbox: true,
+      webSecurity: true,
+      allowRunningInsecureContent: false,
+    },
+  });
+  win.loadFile(path.join(__dirname, 'renderer/index.html'));
+}
+
+app.whenReady().then(() => {
+  // CSP as a response header — covers the initial document, unlike a <meta> tag.
+  session.defaultSession.webRequest.onHeadersReceived((details, cb) => {
+    cb({
+      responseHeaders: {
+        ...details.responseHeaders,
+        'Content-Security-Policy': [
+          "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'",
+        ],
+      },
+    });
+  });
+  createWindow();
+});
+
+// Navigation lockdown — applies to every webContents the app creates.
+app.on('web-contents-created', (_e, contents) => {
+  contents.on('will-navigate', (e, url) => {
+    if (new URL(url).origin !== APP_ORIGIN) e.preventDefault();
+  });
+  contents.on('will-attach-webview', (e) => e.preventDefault()); // no <webview> tags
+  contents.setWindowOpenHandler(({ url }) => {
+    if (url.startsWith('https://')) shell.openExternal(url);
+    return { action: 'deny' }; // never open a new in-app window to arbitrary content
+  });
+});
+```
+
+## IPC handlers with validation (`main.ts`, continued)
+
+Every handler treats its arguments as hostile. Validate type, bound size, and never feed an
+attacker string into `path.join`, `child_process`, or `eval`.
+
+```ts
+import { z } from 'zod';
+
+const SaveNote = z.object({ id: z.string().uuid(), text: z.string().max(10_000) });
+
+ipcMain.handle('note:save', async (_e, raw: unknown) => {
+  const { id, text } = SaveNote.parse(raw); // throws → rejects the renderer's invoke()
+  return db.notes.upsert(id, text);
+});
+
+ipcMain.handle('config:read', async () => readUserConfig()); // no input to validate
+```
+
+## `preload.ts` — one function per channel
+
+```ts
+import { contextBridge, ipcRenderer } from 'electron';
+import type { Api } from './ipc/types';
+
+const api: Api = {
+  readConfig: () => ipcRenderer.invoke('config:read'),
+  saveNote: (id, text) => ipcRenderer.invoke('note:save', { id, text }),
+  onSync: (cb) => {
+    const handler = () => cb();
+    ipcRenderer.on('sync:done', handler);
+    return () => ipcRenderer.removeListener('sync:done', handler); // give callers cleanup
+  },
+};
+
+contextBridge.exposeInMainWorld('api', api);
+```
+
+## Shared contract (`ipc/types.ts`)
+
+```ts
+export interface Config { theme: 'light' | 'dark'; }
+
+export interface Api {
+  readConfig(): Promise<Config>;
+  saveNote(id: string, text: string): Promise<void>;
+  onSync(cb: () => void): () => void; // returns an unsubscribe fn
+}
+```
+
+## Renderer global typing (`renderer/global.d.ts`)
+
+```ts
+import type { Api } from '../ipc/types';
+declare global {
+  interface Window { api: Api; } // window.api is now fully typed in the renderer
+}
+export {};
+```
+
+Renderer usage stays type-safe and capability-scoped:
+
+```ts
+const cfg = await window.api.readConfig();
+await window.api.saveNote(crypto.randomUUID(), 'hello');
+```
+
+## Electron Fuses
+
+Fuses flip security bits in the packaged binary itself, so they hold even if the JS is
+tampered with. Apply at build time (e.g. via `@electron/fuses`):
+
+```ts
+import { FuseV1Options, FuseVersion, flipFuses } from '@electron/fuses';
+
+await flipFuses(appPath, {
+  version: FuseVersion.V1,
+  [FuseV1Options.RunAsNode]: false,                 // no ELECTRON_RUN_AS_NODE bypass
+  [FuseV1Options.EnableCookieEncryption]: true,     // encrypt the cookie store at rest
+  [FuseV1Options.EnableNodeOptionsEnvironmentVariable]: false, // no NODE_OPTIONS injection
+  [FuseV1Options.EnableNodeCliInspectArguments]: false,        // no --inspect debug port
+  [FuseV1Options.OnlyLoadAppFromAsar]: true,        // refuse to run unpacked app code
+  [FuseV1Options.LoadBrowserProcessSpecificV8Snapshot]: false,
+});
+```
+
+## The full security checklist (each item, with the why)
+
+- [ ] `nodeIntegration: false` — renderer must not get `require`/`process`; XSS would become RCE.
+- [ ] `contextIsolation: true` — page and preload run in separate worlds; page can't rewrite the bridge.
+- [ ] `sandbox: true` — OS-level sandbox around the renderer process.
+- [ ] `webSecurity: true` — keep same-origin policy; disabling it to "fix CORS" opens the whole app.
+- [ ] `allowRunningInsecureContent: false` — no mixed http content on an https page.
+- [ ] CSP set via `onHeadersReceived`, not a `<meta>` tag — covers the initial document.
+- [ ] `will-navigate` denies origins outside your app — navigation grants attacker content your privilege.
+- [ ] `setWindowOpenHandler` denies new windows; external links go through `shell.openExternal` after protocol allow-listing.
+- [ ] `will-attach-webview` denied (or `webviewTag: false`) — `<webview>` is a fresh attack surface.
+- [ ] Every `ipcMain.handle` validates and bounds its args — the renderer is an untrusted client.
+- [ ] No `ipcRenderer` (or its methods) exposed over `contextBridge` — one function per channel only.
+- [ ] No `@electron/remote` — it's a direct renderer→main escalation path; use explicit IPC.
+- [ ] Electron Fuses applied (run-as-node off, cookie encryption on, ASAR integrity on).
+- [ ] App is on one of the latest 3 Electron majors — older = unpatched Chromium CVEs.
+- [ ] No attacker-controlled string reaches `path.join`, `child_process`, `shell.openExternal`, or `eval`.

package/skills/shared/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/shared/elixir/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: elixir
+description: "Use when writing or refactoring Elixir/OTP on the BEAM — GenServers, supervision trees and restart strategies, pattern matching, mix projects and releases — or when processes misbehave (restart loops, mailbox growth, call timeouts). NOT a Phoenix web app, LiveView, Ecto or channels (that is `phoenix`)."
+tags: [elixir, otp, genserver, supervision, beam, mix, concurrency, functional]
+recommends: [phoenix, postgresdb, docker]
+origin: ai-hub
+---
+
+# 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, and 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
+
+**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 and is fine for a throwaway fire-and-forget where supervision genuinely does not matter, 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.
+
+## 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
+```
+
+- **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 — timeouts and backpressure recipes in `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 — plus `Task`, `Agent`, `:ets` and how to choose an OTP behaviour — 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
+```
+
+`mix.exs` anatomy, deps, environments, env vars, releases 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.

package/skills/shared/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/shared/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/shared/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.