constella 0.1.0

package/skills/stacks/orm/typeorm/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: typeorm
+description: Decorator-based TS/JS ORM supporting Active Record and Data Mapper patterns across many databases; consult for entity-driven Node.js data access.
+domain: stack
+category: orm
+tags: [orm, typescript, nodejs, decorators, database, migrations]
+official_sources:
+  - https://typeorm.io/
+  - https://github.com/typeorm/typeorm
+verified: 2026-06-16
+---
+
+# TypeORM
+
+## Overview
+TypeORM is an ORM for TypeScript and JavaScript that runs on Node.js (and other platforms) and supports both the Active Record and Data Mapper patterns. You define entities as decorated classes, and TypeORM maps them to tables across PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Oracle, CockroachDB, MongoDB, and more. Read this when you prefer a class/decorator entity model influenced by Hibernate and Entity Framework.
+
+## Official sources
+- Docs: https://typeorm.io/
+- Repo: https://github.com/typeorm/typeorm
+- Install / getting started: https://typeorm.io/docs/getting-started/
+
+## Install / setup
+```bash
+npm install typeorm
+npm install reflect-metadata
+npm install @types/node --save-dev
+```
+
+## Core concepts
+- **Entities**: classes decorated with `@Entity()` whose properties (`@Column`, `@PrimaryGeneratedColumn`) map to table columns.
+- **DataSource**: the connection/configuration object you initialize before running any queries.
+- **Repositories & EntityManager**: APIs for CRUD on entities; the Data Mapper pattern.
+- **Active Record vs Data Mapper**: choose entity methods (Active Record) or repositories (Data Mapper) per project style.
+- **Relations & QueryBuilder**: `@OneToMany`/`@ManyToOne` etc. for associations; `createQueryBuilder` for complex SQL.
+- **Migrations**: schema versioning generated and run via the TypeORM CLI.
+
+## Best practices
+- Import `reflect-metadata` once at app startup (a global location) as the docs require for decorators to work.
+- Initialize a single `DataSource` and reuse it across the app rather than reconnecting per request.
+- Prefer explicit migrations over `synchronize: true` in production to avoid unintended schema changes (per docs).
+- Use `QueryBuilder` for complex queries and to control joins and selected columns.
+
+## Common pitfalls
+- Forgetting to import `reflect-metadata` or enable `experimentalDecorators`/`emitDecoratorMetadata` in tsconfig → decorators silently fail at runtime.
+- Leaving `synchronize: true` on in production → can drop or alter columns unexpectedly; use migrations instead.
+
+## Examples
+```ts
+import 'reflect-metadata'
+import { Entity, PrimaryGeneratedColumn, Column, DataSource } from 'typeorm'
+
+@Entity()
+class User {
+  @PrimaryGeneratedColumn() id!: number
+  @Column() name!: string
+}
+
+const ds = new DataSource({ type: 'postgres', url: process.env.DB_URL, entities: [User] })
+await ds.initialize()
+await ds.getRepository(User).save({ name: 'Ada' })
+```
+
+## Further reading
+- https://typeorm.io/docs/entity/entities/ — entity reference
+- https://typeorm.io/docs/advanced-topics/migrations/ — migrations guide
+
+## Related skills
+- ../prisma — schema-DSL ORM alternative
+- ../sequelize — mature JS/TS ORM alternative

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

@@ -0,0 +1,69 @@
+---
+name: bullmq
+description: Redis-backed distributed job queue for Node.js; consult when adding background jobs, retries, delays, or scheduled work to a Node service.
+domain: stack
+category: queue
+tags: [bullmq, queue, jobs, nodejs, redis, background-jobs]
+official_sources:
+  - https://docs.bullmq.io/
+  - https://github.com/taskforcesh/bullmq
+verified: 2026-06-16
+---
+
+# BullMQ
+
+## Overview
+BullMQ is a fast, Redis-backed distributed queue for Node.js (with Python, Rust, and other ports) used to offload work to background workers: emails, image processing, webhooks, scheduled jobs. It provides retries, delays, priorities, rate limiting, and parent-child job dependencies with atomic, Lua-backed operations. Read this when a Node service needs reliable background processing instead of doing work inside the request cycle.
+
+## Official sources
+- Docs: https://docs.bullmq.io/
+- Repo: https://github.com/taskforcesh/bullmq
+- Install / quick start: https://docs.bullmq.io/readme-1
+
+## Install / setup
+```bash
+npm install bullmq
+```
+Requires a running Redis instance (the examples assume a local Redis on `localhost:6379`).
+
+## Core concepts
+- **Queue**: a named queue you add jobs to (`new Queue('foo')`); producers enqueue, consumers process independently.
+- **Worker**: a process that pulls jobs from a queue and runs a processor function; multiple workers scale horizontally across the same queue.
+- **Job**: a unit of work with data and options (attempts, backoff, delay, priority); BullMQ tracks its lifecycle (waiting, active, completed, failed).
+- **Connection**: BullMQ talks to Redis via ioredis; workers require `maxRetriesPerRequest: null` on the connection.
+- **Flows (parent-child)**: jobs can depend on child jobs and only run after children complete, enabling fan-out/fan-in pipelines.
+- **QueueEvents**: a separate listener stream for observing job state changes (completed, failed, progress) across processes.
+
+## Best practices
+- Make job processors idempotent — BullMQ targets reliable delivery, and retries/replays mean the same job may run more than once.
+- Configure `attempts` and `backoff` per job so transient failures retry with exponential delay instead of failing permanently.
+- Reuse a single Redis connection (ioredis instance) across queues/workers where appropriate rather than opening one per object.
+- Run dedicated worker processes separate from your web/API process so heavy jobs do not compete with request handling.
+
+## Common pitfalls
+- Creating the Worker connection without `maxRetriesPerRequest: null` → BullMQ requires this and will warn/error otherwise.
+- Doing long blocking work in a processor without concurrency or rate limits → set worker `concurrency` and rate limiting to control throughput against downstream systems.
+- Assuming jobs run in the web process → without a separate Worker actually consuming the queue, jobs sit in "waiting" forever.
+
+## Examples
+```typescript
+import { Queue, Worker } from 'bullmq';
+import IORedis from 'ioredis';
+
+const connection = new IORedis({ maxRetriesPerRequest: null });
+
+const myQueue = new Queue('foo', { connection });
+await myQueue.add('myJobName', { foo: 'bar' }, { attempts: 3, backoff: 5000 });
+
+new Worker('foo', async job => {
+  console.log(job.data);
+}, { connection });
+```
+
+## Further reading
+- https://docs.bullmq.io/guide/workers — workers, concurrency, rate limiting
+- https://docs.bullmq.io/guide/flows — parent-child job flows
+
+## Related skills
+- ../redis — the data store BullMQ runs on; understand TTLs and persistence
+- ../celery — equivalent task-queue pattern for Python services

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

@@ -0,0 +1,68 @@
+---
+name: celery
+description: Distributed task queue for Python that runs background jobs via a broker (Redis/RabbitMQ); consult for async tasks, scheduling, and worker fan-out.
+domain: stack
+category: queue
+tags: [celery, python, task-queue, background-jobs, redis, rabbitmq]
+official_sources:
+  - https://docs.celeryq.dev/
+  - https://github.com/celery/celery
+verified: 2026-06-16
+---
+
+# Celery
+
+## Overview
+Celery is a distributed task queue for Python that distributes work across processes and machines using a message broker (commonly RabbitMQ or Redis). It runs background and scheduled jobs outside the request cycle and integrates with Django, Flask, and FastAPI. Read this when a Python service needs async tasks, periodic jobs, retries, or horizontal worker scaling.
+
+## Official sources
+- Docs: https://docs.celeryq.dev/
+- Repo: https://github.com/celery/celery
+- Install: https://docs.celeryq.dev/en/stable/getting-started/introduction.html#installation
+
+## Install / setup
+```bash
+pip install -U Celery
+```
+Celery also needs a broker (e.g. RabbitMQ or Redis) running; install broker extras with bundles like `pip install "celery[redis]"`.
+
+## Core concepts
+- **Task**: a unit of work defined with the `@app.task` decorator; called asynchronously with `.delay()` / `.apply_async()`.
+- **Broker**: the message transport (RabbitMQ, Redis, SQS) that carries tasks from producers to workers; required to run Celery.
+- **Worker**: a process started with `celery -A <app> worker` that consumes and executes queued tasks.
+- **Result backend**: optional store (Redis, DB, etc.) that holds task return values and state when you need to retrieve results.
+- **Beat (scheduler)**: a separate process that sends scheduled/periodic tasks to the broker on a cron-like schedule.
+- **Routing & queues**: tasks can be routed to named queues so workers can specialize and scale independently.
+
+## Best practices
+- Make tasks idempotent and keep them small/focused, since Celery may retry or redeliver work.
+- Set explicit `acks_late` / time limits and retry policies so a crashed worker re-queues its task instead of losing it.
+- Use a dedicated result backend only when you actually need results; otherwise disabling it reduces overhead.
+- Run Celery Beat as a single instance to avoid duplicate scheduled-task dispatch, and route heavy tasks to dedicated queues/workers.
+
+## Common pitfalls
+- Calling a task function directly (`add(2, 2)`) instead of `add.delay(2, 2)` → it runs synchronously in-process and never reaches a worker.
+- Forgetting to start a worker or broker → tasks queue (or fail to enqueue) and never execute.
+- Passing large or non-serializable objects as task arguments → arguments must serialize through the broker; pass IDs and reload inside the task.
+
+## Examples
+```python
+from celery import Celery
+
+app = Celery('tasks', broker='pyamqp://guest@localhost//')
+
+@app.task
+def add(x, y):
+    return x + y
+```
+```bash
+celery -A tasks worker --loglevel=INFO
+```
+
+## Further reading
+- https://docs.celeryq.dev/en/stable/getting-started/first-steps-with-celery.html — first steps tutorial
+- https://docs.celeryq.dev/en/stable/userguide/periodic-tasks.html — periodic tasks with Beat
+
+## Related skills
+- ../redis — common Celery broker/result backend
+- ../rabbitmq — default, fully-featured Celery broker

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

@@ -0,0 +1,66 @@
+---
+name: kafka
+description: Distributed event streaming platform with durable, replayable logs; consult for high-throughput data pipelines, event sourcing, and stream processing.
+domain: stack
+category: queue
+tags: [kafka, streaming, events, log, pubsub, distributed]
+official_sources:
+  - https://kafka.apache.org/documentation/
+  - https://github.com/apache/kafka
+verified: 2026-06-16
+---
+
+# Apache Kafka
+
+## Overview
+Apache Kafka is an open-source distributed event streaming platform used for high-performance data pipelines, streaming analytics, data integration, and mission-critical applications. Unlike a traditional broker, Kafka stores events in durable, partitioned, append-only logs that consumers replay at their own offset. Read this when you need high-throughput event ingestion, event sourcing, or stream processing across many consumers.
+
+## Official sources
+- Docs: https://kafka.apache.org/documentation/
+- Repo: https://github.com/apache/kafka
+- Install / quickstart: https://kafka.apache.org/quickstart
+
+## Install / setup
+```bash
+tar -xzf kafka_2.13-4.3.0.tgz
+cd kafka_2.13-4.3.0
+KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
+bin/kafka-storage.sh format --standalone -t $KAFKA_CLUSTER_ID -c config/server.properties
+bin/kafka-server-start.sh config/server.properties
+```
+
+## Core concepts
+- **Topic**: a named, append-only log of events that producers write to and consumers read from.
+- **Partition**: topics are split into partitions for parallelism and ordering; order is guaranteed only within a partition.
+- **Offset**: each consumer tracks its position (offset) per partition, so events can be replayed and consumers progress independently.
+- **Producer / Consumer**: producers publish records (optionally keyed for partition routing); consumers read them.
+- **Consumer group**: consumers in a group share partitions so each partition is processed by exactly one member, enabling horizontal scaling.
+- **Retention + replication**: events are retained for a configured time/size (not deleted on read) and replicated across brokers for durability.
+- **KRaft**: modern Kafka manages metadata internally via KRaft, removing the legacy ZooKeeper dependency.
+
+## Best practices
+- Choose partition counts up front based on target throughput and consumer parallelism — it dictates how many consumers can work in parallel.
+- Use a meaningful record key when ordering per entity matters, since all records with the same key land in the same partition.
+- Set retention deliberately; Kafka keeps events until retention expires, so consumers can replay and recover from offsets.
+- Run with replication (replication factor >= 3 in production) so partition leaders can fail over without data loss.
+
+## Common pitfalls
+- Treating Kafka like a queue where reading deletes the message → it does not; messages persist per retention and consumers advance offsets instead.
+- Expecting global ordering across a topic → ordering holds only within a partition; cross-partition order is not guaranteed.
+- Adding too many or too few partitions → too few caps parallelism; too many strains the cluster. Size them to throughput needs.
+
+## Examples
+```bash
+# produce events to a topic
+bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhost:9092
+# consume from the beginning
+bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092
+```
+
+## Further reading
+- https://kafka.apache.org/documentation/#design — design and storage internals
+- https://kafka.apache.org/documentation/streams/ — Kafka Streams processing library
+
+## Related skills
+- ../rabbitmq — broker-style alternative when you need routing and per-message acks
+- ../nats — lighter-weight streaming/messaging system (JetStream) for similar use cases

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

@@ -0,0 +1,66 @@
+---
+name: nats
+description: Lightweight high-performance messaging system with pub/sub and JetStream persistence; consult for cloud-native, edge, and microservice messaging.
+domain: stack
+category: queue
+tags: [nats, messaging, pubsub, jetstream, cloud-native, streaming]
+official_sources:
+  - https://docs.nats.io/
+  - https://github.com/nats-io/nats-server
+verified: 2026-06-16
+---
+
+# NATS
+
+## Overview
+NATS is a simple, secure, high-performance messaging system for cloud-native applications, edge devices, and microservices, and is a CNCF project. Core NATS provides fast at-most-once pub/sub and request-reply; the JetStream layer adds persistence, replay, and stronger delivery guarantees plus key/value and object stores. Read this when you want lightweight, low-latency messaging with optional durability without operating a heavier broker.
+
+## Official sources
+- Docs: https://docs.nats.io/
+- Repo: https://github.com/nats-io/nats-server
+- Install: https://docs.nats.io/running-a-nats-service/introduction/installation
+
+## Install / setup
+```bash
+docker pull nats:latest
+docker run -p 4222:4222 -ti nats:latest
+```
+```bash
+# macOS (Homebrew)
+brew install nats-server
+```
+
+## Core concepts
+- **Subjects**: hierarchical, dot-delimited addresses (e.g. `orders.us.new`) that messages are published to and subscribed against, with `*` and `>` wildcards.
+- **Publish / Subscribe**: many subscribers can receive messages on a subject; Core NATS delivery is at-most-once and fire-and-forget.
+- **Request-Reply**: built-in RPC pattern where a publisher gets a direct reply on a temporary inbox subject.
+- **Queue groups**: subscribers sharing a queue group load-balance messages so each message goes to one member — work-queue semantics over pub/sub.
+- **JetStream**: the persistence engine adding streams, durable consumers, replay, and up to exactly-once delivery on top of Core NATS.
+- **KV and Object stores**: higher-level abstractions built on JetStream for key/value and large-object storage.
+
+## Best practices
+- Design subject hierarchies intentionally and use wildcards for flexible subscriptions rather than hard-coding many concrete subjects.
+- Use queue groups for scalable work distribution so adding subscribers spreads load automatically.
+- Use JetStream (not Core NATS) whenever you need messages to survive subscriber downtime, replay, or acknowledgements.
+- Run a clustered nats-server for high availability rather than a single node in production.
+
+## Common pitfalls
+- Expecting Core NATS to retain messages → it is at-most-once and drops messages with no active subscriber; use JetStream for persistence.
+- Forgetting to ack JetStream messages → unacked messages are redelivered per the consumer's ack policy, causing duplicate processing.
+- Overly broad `>` wildcard subscriptions → can flood a subscriber with far more traffic than intended.
+
+## Examples
+```bash
+# subscribe to a subject (NATS CLI)
+nats sub "orders.>"
+# publish a message
+nats pub orders.us.new '{"id":99}'
+```
+
+## Further reading
+- https://docs.nats.io/nats-concepts/jetstream — JetStream persistence concepts
+- https://docs.nats.io/nats-concepts/core-nats — Core NATS messaging patterns
+
+## Related skills
+- ../kafka — log-based streaming for very high-throughput, replay-heavy pipelines
+- ../rabbitmq — broker with rich routing when you need protocol breadth and per-message acks

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