constellai 0.3.0

package/skills/stacks/queue/rabbitmq/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: rabbitmq
+description: Multi-protocol message broker (AMQP/MQTT/STOMP) for reliable async messaging; consult when decoupling services with durable queues and routing.
+domain: stack
+category: queue
+tags: [rabbitmq, message-broker, amqp, queue, messaging, pubsub]
+official_sources:
+  - https://www.rabbitmq.com/docs
+  - https://github.com/rabbitmq/rabbitmq-server
+verified: 2026-06-16
+---
+
+# RabbitMQ
+
+## Overview
+RabbitMQ is a feature-rich, multi-protocol messaging and streaming broker that decouples producers from consumers with durable queues and flexible routing. It speaks AMQP 0-9-1/1.0, MQTT, STOMP, and their WebSocket variants, making it a general-purpose broker for async workflows, task distribution, and event fan-out. Read this when services need reliable, acknowledged message delivery with routing logic rather than a simple in-memory list.
+
+## Official sources
+- Docs: https://www.rabbitmq.com/docs
+- Repo: https://github.com/rabbitmq/rabbitmq-server
+- Install / download: https://www.rabbitmq.com/docs/download
+
+## Install / setup
+```bash
+docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:4-management
+```
+Port 5672 is AMQP; 15672 serves the management UI.
+
+## Core concepts
+- **Producer / Consumer**: producers publish messages; consumers subscribe and process them — they never communicate directly.
+- **Exchange**: receives published messages and routes them to queues based on type (direct, topic, fanout, headers) and bindings.
+- **Queue**: an ordered buffer that holds messages until a consumer acknowledges them; can be durable to survive broker restarts.
+- **Binding + routing key**: rules connecting exchanges to queues; the routing key plus exchange type determines where a message lands.
+- **Acknowledgements**: consumers ack messages after processing; unacked messages are redelivered if the consumer dies, ensuring at-least-once delivery.
+- **Quorum queues**: the recommended replicated, durable queue type for data safety in clustered deployments.
+
+## Best practices
+- Use manual acknowledgements and only ack after successful processing so crashes trigger redelivery instead of message loss.
+- Declare queues and exchanges as durable and publish persistent messages when you need them to survive a broker restart.
+- Prefer quorum queues over classic mirrored queues for replicated, highly-available workloads (per RabbitMQ docs).
+- Set prefetch (QoS) limits so a single consumer is not flooded with unacked messages and work spreads across consumers.
+
+## Common pitfalls
+- Auto-ack mode → messages are removed before processing completes, so a crash silently loses them; use manual ack.
+- Non-durable queues / non-persistent messages → everything is lost on broker restart; mark both durable when persistence matters.
+- Unbounded queues without consumers or limits → memory/disk pressure can trigger flow control and block publishers; monitor depth and apply limits.
+
+## Examples
+```python
+import pika
+conn = pika.BlockingConnection(pika.ConnectionParameters('localhost'))
+ch = conn.channel()
+ch.queue_declare(queue='tasks', durable=True)
+ch.basic_publish(exchange='', routing_key='tasks', body='hello',
+                 properties=pika.BasicProperties(delivery_mode=2))  # persistent
+```
+
+## Further reading
+- https://www.rabbitmq.com/tutorials — official protocol/usage tutorials
+- https://www.rabbitmq.com/docs/quorum-queues — quorum queue reference
+
+## Related skills
+- ../kafka — log-based streaming alternative for high-throughput event pipelines
+- ../celery — Python task queue that commonly uses RabbitMQ as its broker

package/skills/stacks/queue/redis/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: redis
+description: In-memory data store used as a cache, message broker, and queue backend; consult when adding caching, pub/sub, or queue infrastructure.
+domain: stack
+category: queue
+tags: [redis, cache, queue, pubsub, streams, in-memory]
+official_sources:
+  - https://redis.io/docs/latest/develop/
+  - https://github.com/redis/redis
+verified: 2026-06-16
+---
+
+# Redis
+
+## Overview
+Redis is an in-memory key-value data store used as a cache, data-structure server, message broker, and the backing store for many job-queue libraries. It keeps data in RAM for sub-millisecond access while offering optional persistence. Read this when you need fast caching, pub/sub messaging, rate limiting, or a queue substrate (BullMQ, Celery, Sidekiq all build on Redis).
+
+## Official sources
+- Docs: https://redis.io/docs/latest/develop/
+- Repo: https://github.com/redis/redis
+- Install / download: https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/
+
+## Install / setup
+```bash
+# Docker (quickest, only officially supported method on Windows)
+docker run -d --name redis -p 6379:6379 redis
+```
+```bash
+# macOS (Homebrew)
+brew tap redis/redis
+brew install --cask redis
+```
+
+## Core concepts
+- **Data types**: strings, hashes, lists, sets, sorted sets, streams, bitmaps, hyperloglogs, and geospatial indexes — choosing the right type is the primary modeling decision.
+- **Single-threaded command execution**: commands run sequentially on one main thread, so each command is atomic; long-running commands block all clients.
+- **Key expiration / eviction**: keys can be given a TTL (`EXPIRE`/`SET ... EX`); when memory fills, the configured `maxmemory-policy` (e.g. `allkeys-lru`) decides what to evict — central to cache behavior.
+- **Pub/Sub and Streams**: Pub/Sub is fire-and-forget fan-out; Streams are append-only logs with consumer groups for durable, replayable queue semantics.
+- **Persistence (RDB + AOF)**: RDB snapshots and the append-only file give durability; Redis is in-memory first, so persistence is a configurable trade-off, not the default guarantee.
+- **Transactions and Lua scripts**: `MULTI`/`EXEC` and server-side Lua scripts run atomically, which is how queue libraries implement reliable multi-key operations.
+
+## Best practices
+- Set explicit TTLs on cache keys and choose an eviction policy that matches your workload rather than relying on unbounded growth (see Redis eviction docs).
+- Prefer `SCAN` over `KEYS` in production; `KEYS` blocks the single thread across the whole keyspace.
+- Use pipelining or `MULTI`/Lua to batch related operations and cut round-trips instead of issuing many sequential commands.
+- For durable queues use Streams with consumer groups (acknowledge with `XACK`) rather than plain lists, so unprocessed messages survive consumer crashes.
+
+## Common pitfalls
+- Treating Redis as a fully durable primary database → it is in-memory first; enable AOF/RDB and understand the data-loss window, or keep the system of record elsewhere.
+- Running `KEYS *` or large `SMEMBERS`/`HGETALL` on big keys in production → blocks the server; use `SCAN`/cursor-based iteration and avoid giant keys.
+- Forgetting `maxmemory` and eviction policy → Redis can exhaust RAM and start failing writes (or get OOM-killed) under load.
+
+## Examples
+```bash
+SET session:42 "user-data" EX 3600   # value with a 1-hour TTL
+INCR page:views                       # atomic counter
+XADD orders '*' id 99 status new      # append to a stream
+```
+
+## Further reading
+- https://redis.io/docs/latest/develop/data-types/ — data type reference
+- https://redis.io/docs/latest/develop/interact/pubsub/ — Pub/Sub guide
+
+## Related skills
+- ../bullmq — Redis-backed job queue for Node.js built on these primitives
+- ../celery — Python task queue that can use Redis as its broker

package/skills/stacks/runtime/beam/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: beam
+description: The BEAM (Erlang/OTP VM) running Erlang and Elixir — built for massively scalable, fault-tolerant, soft real-time systems. Consult for concurrent/HA services.
+domain: stack
+category: runtime
+tags: [beam, erlang, elixir, otp, concurrency, fault-tolerance]
+official_sources:
+  - https://www.erlang.org/docs
+  - https://github.com/erlang/otp
+verified: 2026-06-16
+---
+
+# BEAM (Erlang/OTP VM)
+
+## Overview
+The BEAM is the virtual machine in Erlang/OTP that executes Erlang and Elixir code. Erlang is designed for building massively scalable soft real-time systems with high-availability requirements. OTP is the runtime system plus a set of libraries and design principles for building robust concurrent applications. Read this when building fault-tolerant, highly concurrent, or distributed services.
+
+## Official sources
+- Docs: https://www.erlang.org/docs
+- Repo: https://github.com/erlang/otp
+- Install / download: https://www.erlang.org/downloads
+
+## Install / setup
+Install via a package manager (commands shown on the official downloads page):
+
+```bash
+brew install erlang      # macOS (Homebrew)
+apt-get install erlang   # Ubuntu/Debian
+```
+
+Or build from source per the official build instructions:
+
+```bash
+./configure && make && make install
+```
+
+Verify the install by starting the shell with `erl` (the downloads page also lists version managers such as kerl, asdf, and mise).
+
+## Core concepts
+- Lightweight processes: BEAM schedules huge numbers of isolated processes that share no memory and communicate by message passing.
+- "Let it crash": processes fail fast and are restarted by supervisors rather than defensively handling every error.
+- OTP behaviours (`gen_server`, supervisors, applications) encode proven patterns for concurrent, supervised systems.
+- Preemptive per-process scheduling gives soft real-time, low-latency responsiveness under load.
+- Built-in distribution lets nodes connect and processes communicate across machines transparently.
+- Hot code loading allows updating running systems without full restarts.
+
+## Best practices
+- Structure applications around supervision trees so failures are isolated and recovered automatically.
+- Build stateful concurrency on OTP behaviours (e.g. `gen_server`) rather than ad-hoc process loops.
+- Keep processes small and single-purpose to maximize isolation and fault containment.
+- Prefer immutable message passing over shared state, in line with the actor model.
+
+## Common pitfalls
+- Writing defensive try/catch everywhere instead of leveraging supervisors → adopt "let it crash" with supervision.
+- Building bespoke process plumbing instead of OTP behaviours → reuse `gen_server`/supervisor patterns.
+- Large messages copied between processes → keep messages small since processes do not share memory.
+
+## Examples
+```erlang
+% Spawn a process and send it a message
+Pid = spawn(fun() ->
+    receive Msg -> io:format("got: ~p~n", [Msg]) end
+end),
+Pid ! hello.
+```
+
+## Further reading
+- OTP design principles: https://www.erlang.org/doc/system/design_principles.html
+- Documentation hub: https://www.erlang.org/docs
+
+## Related skills
+- ../jvm — alternative VM for concurrent, long-running services

package/skills/stacks/runtime/bun/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: bun
+description: Bun — fast all-in-one JS/TS runtime, bundler, test runner, and package manager; a Node.js drop-in. Consult for fast JS/TS dev and tooling.
+domain: stack
+category: runtime
+tags: [bun, javascript, typescript, runtime, bundler, package-manager]
+official_sources:
+  - https://bun.com/docs
+  - https://github.com/oven-sh/bun
+verified: 2026-06-16
+---
+
+# Bun
+
+## Overview
+Bun is an all-in-one toolkit for JavaScript and TypeScript apps, designed as a drop-in replacement for Node.js. It ships as a single dependency-free executable that bundles a runtime, package manager, bundler, and test runner. Written in Zig and powered by JavaScriptCore, it targets fast startup and install times. Read this when you want a single fast tool covering run, install, build, and test.
+
+## Official sources
+- Docs: https://bun.com/docs
+- Repo: https://github.com/oven-sh/bun
+- Install / download: https://bun.com/docs/installation
+
+## Install / setup
+macOS & Linux (from the official installation page):
+
+```bash
+curl -fsSL https://bun.com/install | bash
+```
+
+Windows (PowerShell):
+
+```powershell
+powershell -c "irm bun.sh/install.ps1|iex"
+```
+
+Verify the install:
+
+```bash
+bun --version
+bun --revision
+```
+
+## Core concepts
+- Single executable provides runtime, package manager (`bun install`), bundler (`bun build`), and test runner (`bun test`).
+- Native TypeScript and JSX support — run `.ts`/`.tsx` directly without a separate transpile step.
+- Node.js compatibility layer aims for drop-in replacement of `node`, including many built-in modules and npm packages.
+- Bun-specific APIs (e.g. `Bun.serve`, `Bun.file`) offer optimized I/O and HTTP serving.
+- `bun.lockb`/lockfile and a fast, npm-compatible install resolve dependencies from the npm registry.
+- The binary upgrades itself via `bun upgrade`.
+
+## Best practices
+- Verify after install and add `~/.bun/bin` to `PATH` if `bun` is not found (per the installation docs).
+- Use `bun install` to leverage the integrated, fast package manager and its lockfile.
+- Pin to stable releases; canary builds are untested and upload crash reports (installation docs).
+- Run TypeScript directly with `bun run` instead of adding a separate transpiler step.
+
+## Common pitfalls
+- Assuming 100% Node.js parity → check the Node compatibility docs for unsupported APIs before migrating.
+- On Linux, missing `unzip` breaks the install script → install `unzip` first (installation docs).
+- Using a baseline build on a modern CPU unnecessarily → only use baseline builds when you hit "Illegal Instruction" errors.
+
+## Examples
+```ts
+const server = Bun.serve({
+  port: 3000,
+  fetch(req) {
+    return new Response('Hello from Bun');
+  },
+});
+
+console.log(`listening on ${server.url}`);
+```
+
+## Further reading
+- Documentation index: https://bun.com/docs
+- Runtime / Node compatibility: https://bun.com/docs/runtime/nodejs-apis
+
+## Related skills
+- ../node — the runtime Bun aims to replace
+- ../deno — alternative secure JS/TS runtime

package/skills/stacks/runtime/deno/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: deno
+description: Deno — a secure-by-default JS/TS/WebAssembly runtime with built-in tooling (fmt, lint, test) and explicit permissions. Consult for secure JS/TS runtimes.
+domain: stack
+category: runtime
+tags: [deno, javascript, typescript, webassembly, runtime, security]
+official_sources:
+  - https://docs.deno.com/
+  - https://github.com/denoland/deno
+verified: 2026-06-16
+---
+
+# Deno
+
+## Overview
+Deno is a JavaScript, TypeScript, and WebAssembly runtime with secure defaults and a focus on developer experience. It is built on V8, Rust, and Tokio, and ships with built-in tooling (formatter, linter, test runner, bundler). Unlike Node, code runs sandboxed: file, network, and environment access must be explicitly granted. Read this when you want first-class TypeScript and an opt-in permission model.
+
+## Official sources
+- Docs: https://docs.deno.com/
+- Repo: https://github.com/denoland/deno
+- Install / download: https://docs.deno.com/runtime/getting_started/installation/
+
+## Install / setup
+macOS & Linux (from the official installation page):
+
+```bash
+curl -fsSL https://deno.land/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://deno.land/install.ps1 | iex
+```
+
+Verify the install:
+
+```bash
+deno --version
+```
+
+## Core concepts
+- Secure by default: file, network, and env access require explicit flags (e.g. `--allow-net`, `--allow-read`).
+- First-class TypeScript — run `.ts` directly with no separate build step.
+- Built-in tooling: `deno fmt`, `deno lint`, `deno test`, `deno bundle`, and `deno compile`.
+- Web-standard APIs (`fetch`, `URL`, Web Streams) plus a Node.js compatibility layer (`node:` specifiers, npm specifiers).
+- Modules are loaded by URL/specifier; dependencies and tasks are configured in `deno.json`.
+
+## Best practices
+- Grant the narrowest permissions needed (specific paths/hosts) rather than blanket `--allow-all`.
+- Pin dependency versions and use a lockfile for reproducible builds.
+- Use the built-in `deno fmt`/`deno lint`/`deno test` instead of adding external tooling where possible.
+- Prefer web-standard APIs for portability across runtimes and edge platforms.
+
+## Common pitfalls
+- Running with `--allow-all` and losing the security benefit → scope permissions explicitly.
+- Expecting full Node API parity → consult the Node compatibility docs for unsupported modules.
+- Forgetting that remote imports execute with the granted permissions → review and pin third-party module sources.
+
+## Examples
+```ts
+// run with: deno run --allow-net server.ts
+Deno.serve({ port: 3000 }, (_req) => {
+  return new Response('Hello from Deno');
+});
+```
+
+## Further reading
+- Getting started: https://docs.deno.com/runtime/getting_started/
+- Permissions: https://docs.deno.com/runtime/fundamentals/security/
+
+## Related skills
+- ../node — the runtime Deno's Node-compat layer targets
+- ../bun — alternative fast JS/TS runtime

package/skills/stacks/runtime/dotnet/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: dotnet
+description: .NET — Microsoft's free, cross-platform, open-source runtime (CoreCLR) for C#/F#/VB apps and services. Consult for installing, running, and deploying .NET.
+domain: stack
+category: runtime
+tags: [dotnet, csharp, coreclr, runtime, cli, cross-platform]
+official_sources:
+  - https://learn.microsoft.com/dotnet/
+  - https://github.com/dotnet/runtime
+verified: 2026-06-16
+---
+
+# .NET
+
+## Overview
+.NET is a free, cross-platform, open-source development platform from Microsoft for building web, cloud, desktop, mobile, AI, and IoT applications. The runtime (CoreCLR) executes Intermediate Language compiled from C#, F#, or Visual Basic, with a large class library. Read this when installing the SDK/runtime, using the `dotnet` CLI, or deploying a .NET service.
+
+## Official sources
+- Docs: https://learn.microsoft.com/dotnet/
+- Repo: https://github.com/dotnet/runtime
+- Install / download: https://dotnet.microsoft.com/download
+
+## Install / setup
+Download the SDK (which includes the runtime) for your platform from https://dotnet.microsoft.com/download (current LTS shown there is the .NET 10.0 line). On Linux, follow the package-manager instructions linked from the page. Verify and scaffold:
+
+```bash
+dotnet --version
+dotnet new console -o hello
+dotnet run --project hello
+```
+
+## Core concepts
+- The `dotnet` CLI drives the workflow: `new`, `restore`, `build`, `run`, `test`, `publish`.
+- The SDK contains build tooling plus the runtime; the runtime-only package just executes apps.
+- CoreCLR is the execution engine; the Base Class Library provides core APIs.
+- Source compiles to Intermediate Language (IL), JIT-compiled to native code at runtime (AOT also available).
+- NuGet is the package manager; project/dependency metadata lives in `.csproj`/`.fsproj` files.
+- Release lifecycle alternates LTS (even majors, longer support) and STS releases.
+
+## Best practices
+- Target an LTS release (e.g. .NET 10 LTS) for production longevity.
+- Install the SDK for development; ship the runtime-only package (or self-contained/AOT) to servers.
+- Commit `packages.lock.json` or pin versions for reproducible NuGet restores.
+- Use `dotnet publish` with the right runtime identifier for framework-dependent or self-contained deploys.
+
+## Common pitfalls
+- Installing only the runtime when you need to build → install the SDK for `dotnet build`.
+- Mismatched target framework vs installed runtime version → align `TargetFramework` with an installed runtime.
+- Assuming Windows-only → .NET runs cross-platform; verify platform-specific APIs before relying on them.
+
+## Examples
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+var app = builder.Build();
+app.MapGet("/", () => "Hello from .NET");
+app.Run();
+```
+
+## Further reading
+- .NET documentation: https://learn.microsoft.com/dotnet/
+- Linux install guide: https://learn.microsoft.com/dotnet/core/install/linux
+
+## Related skills
+- ../jvm — comparable managed bytecode runtime

package/skills/stacks/runtime/jvm/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: jvm
+description: The Java Virtual Machine — the runtime executing Java/Kotlin/Scala bytecode. Consult for JDK selection, deployment, and JVM tuning. OpenJDK builds via Temurin.
+domain: stack
+category: runtime
+tags: [jvm, java, openjdk, temurin, bytecode, runtime]
+official_sources:
+  - https://docs.oracle.com/en/java/javase/
+  - https://github.com/openjdk/jdk
+verified: 2026-06-16
+---
+
+# JVM (Java Virtual Machine)
+
+## Overview
+The Java Virtual Machine executes platform-independent bytecode produced from Java, Kotlin, Scala, Clojure, and other JVM languages. OpenJDK is the open-source reference implementation; Eclipse Temurin (Adoptium) provides free, TCK-certified prebuilt OpenJDK binaries. Read this when selecting a JDK, packaging a JVM service, or reasoning about runtime/GC behavior.
+
+## Official sources
+- Docs: https://docs.oracle.com/en/java/javase/
+- Repo: https://github.com/openjdk/jdk
+- Install / download: https://adoptium.net/
+
+## Install / setup
+Download a prebuilt, TCK-certified OpenJDK (Eclipse Temurin) for your platform from https://adoptium.net/ ("Download Temurin"). Verify the install:
+
+```bash
+java -version
+javac -version
+```
+
+## Core concepts
+- Bytecode + JIT: source compiles to `.class` bytecode; the JVM interprets then JIT-compiles hot paths to native code.
+- The JVM is a spec; OpenJDK is the reference implementation and Temurin is a certified distribution of it.
+- Automatic memory management with a garbage collector (G1 by default on recent JDKs; alternatives like ZGC exist).
+- LTS release lines (e.g. JDK 8, 11, 17, 21) get extended support; non-LTS releases are shorter-lived.
+- The classpath/module path locate compiled classes and dependencies; the Java Platform Module System organizes modules.
+- "Write once, run anywhere": the same bytecode runs on any conformant JVM/OS.
+
+## Best practices
+- Target an LTS release (e.g. 17 or 21) for production; check active versions at https://docs.oracle.com/en/java/javase/.
+- Use a certified distribution (Temurin) for production to ensure TCK compliance.
+- Size the heap explicitly (`-Xms`/`-Xmx`) for predictable memory behavior in containers.
+- Select a GC appropriate to latency vs throughput needs rather than relying solely on defaults.
+
+## Common pitfalls
+- Running an unsupported/EOL JDK → upgrade to a supported LTS line.
+- Leaving heap unbounded in containers → set `-Xmx` (or container-aware flags) to avoid OOM kills.
+- Confusing the JRE-only runtime with the full JDK when you need `javac`/tooling → install the JDK.
+
+## Examples
+```java
+public class Main {
+    public static void main(String[] args) {
+        System.out.println("Hello from the JVM");
+    }
+}
+// javac Main.java && java Main
+```
+
+## Further reading
+- Java SE documentation: https://docs.oracle.com/en/java/javase/
+- OpenJDK project: https://openjdk.org/
+
+## Related skills
+- ../dotnet — comparable managed runtime on the .NET platform
+- ../beam — alternative VM (Erlang/Elixir) for concurrent systems

package/skills/stacks/runtime/node/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: node
+description: Node.js — the standard cross-platform JavaScript/TypeScript server runtime built on V8; consult for server/CLI/tooling work in JS.
+domain: stack
+category: runtime
+tags: [nodejs, javascript, typescript, v8, runtime, npm]
+official_sources:
+  - https://nodejs.org/docs/latest/api/
+  - https://github.com/nodejs/node
+verified: 2026-06-16
+---
+
+# Node.js
+
+## Overview
+Node.js is an open-source, cross-platform JavaScript runtime environment built on the V8 engine. It runs JavaScript (and, via loaders/transpilers, TypeScript) outside the browser to build servers, CLIs, and tooling. Read this when choosing or configuring the runtime for a JS/TS backend, scripts, or build tooling. The project is governed under the OpenJS Foundation.
+
+## Official sources
+- Docs: https://nodejs.org/docs/latest/api/
+- Repo: https://github.com/nodejs/node
+- Install / download: https://nodejs.org/en/download
+
+## Install / setup
+The official download page provides prebuilt installers and binaries plus a version-manager flow. To verify a manual install, download the platform installer/binary from the download page, then confirm:
+
+```bash
+node --version
+npm --version
+```
+
+For multiple versions, the download page recommends a Node version manager (e.g. `nvm`); follow the exact script shown on https://nodejs.org/en/download/package-manager.
+
+## Core concepts
+- Single-threaded event loop with non-blocking async I/O — long synchronous work blocks all requests.
+- CommonJS (`require`) and ECMAScript Modules (`import`); `.mjs`/`"type": "module"` select ESM behavior.
+- Built-in core modules (`fs`, `http`, `path`, `crypto`, `worker_threads`, etc.) documented in the API reference.
+- `npm` is the bundled package manager; `package.json` declares dependencies, scripts, and module type.
+- Release lines: even-numbered majors become Long Term Support (LTS); odd majors are "Current" only.
+- `worker_threads` and the cluster model offload CPU-bound work off the main event loop.
+
+## Best practices
+- Pin to an active LTS release for production stability (see https://nodejs.org/en/about/previous-releases).
+- Keep CPU-heavy tasks off the event loop using worker threads or external services.
+- Commit a lockfile (`package-lock.json`) and prefer `npm ci` for reproducible installs.
+- Handle async errors explicitly; attach handlers for `unhandledRejection`/`uncaughtException` only for logging and graceful shutdown.
+
+## Common pitfalls
+- Blocking the event loop with synchronous/CPU-bound code → offload to worker threads or break work into async chunks.
+- Mixing CommonJS and ESM incorrectly (e.g. `require` of an ESM-only package) → align `"type"` and import style per the modules docs.
+- Relying on an end-of-life Node version → track the release schedule and upgrade to a supported LTS.
+
+## Examples
+```js
+import http from 'node:http';
+
+const server = http.createServer((req, res) => {
+  res.writeHead(200, { 'Content-Type': 'text/plain' });
+  res.end('Hello from Node.js');
+});
+
+server.listen(3000, () => console.log('listening on :3000'));
+```
+
+## Further reading
+- API reference: https://nodejs.org/docs/latest/api/
+- Release schedule: https://nodejs.org/en/about/previous-releases
+
+## Related skills
+- ../bun — alternative JS/TS runtime and toolkit
+- ../deno — secure JS/TS runtime with built-in tooling

package/skills/stacks/runtime/pypy/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: pypy
+description: PyPy — a fast, compliant alternative Python implementation with a tracing JIT. Consult when CPython performance is a bottleneck for long-running Python.
+domain: stack
+category: runtime
+tags: [pypy, python, jit, runtime, rpython, performance]
+official_sources:
+  - https://doc.pypy.org/
+  - https://github.com/pypy/pypy
+verified: 2026-06-16
+---
+
+# PyPy
+
+## Overview
+PyPy is a fast and compliant alternative implementation of the Python language, built with the RPython framework. Its tracing just-in-time (JIT) compiler can make long-running, CPU-bound pure-Python code substantially faster than CPython. Read this when CPython performance is the bottleneck and the workload is dominated by Python-level code rather than C extensions.
+
+## Official sources
+- Docs: https://doc.pypy.org/
+- Repo: https://github.com/pypy/pypy
+- Install / download: https://pypy.org/download.html
+
+## Install / setup
+PyPy distributes pre-compiled binaries per platform/architecture from https://pypy.org/download.html (hosted at downloads.python.org). Download and extract the build for your OS, then verify:
+
+```bash
+pypy3 --version
+pypy3 -m ensurepip
+pypy3 -m pip install -r requirements.txt
+```
+
+On macOS, the download page notes signed packages are also available via Homebrew.
+
+## Core concepts
+- Tracing JIT: PyPy compiles hot loops to machine code at runtime, speeding up repeated Python-level execution.
+- High CPython compatibility: PyPy3 targets a specific CPython language version (e.g. PyPy3.11) and runs most pure-Python code unchanged.
+- Built with RPython, a restricted subset of Python from which the interpreter and JIT are generated.
+- Best speedups come from long-running, CPU-bound, pure-Python workloads where the JIT can warm up.
+- `cpyext` provides C-extension compatibility, but C-API-heavy code can run slower than on CPython.
+
+## Best practices
+- Benchmark your actual workload before committing — PyPy helps most on long-running pure-Python hot loops.
+- Match the PyPy3 release to the CPython language version your code targets.
+- Prefer pure-Python or PyPy-friendly libraries; minimize reliance on heavy C-extension paths.
+- Allow JIT warm-up time; short scripts may not benefit and can even start slower.
+
+## Common pitfalls
+- Expecting speedups on C-extension-heavy code → `cpyext` overhead can negate gains; test first.
+- Using PyPy for tiny short-lived scripts → JIT warm-up cost may outweigh benefits.
+- Assuming binary wheels built for CPython work directly → some packages need PyPy-specific builds.
+
+## Examples
+```python
+# Run with: pypy3 sum.py  — JIT accelerates the hot loop
+def total(n):
+    s = 0
+    for i in range(n):
+        s += i * i
+    return s
+
+print(total(10_000_000))
+```
+
+## Further reading
+- Documentation: https://doc.pypy.org/
+- Compatibility notes: https://doc.pypy.org/en/latest/cpython_differences.html
+
+## Related skills
+- ../python3 — the reference CPython runtime PyPy is compatible with