constellai 0.3.0

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

@@ -0,0 +1,64 @@
+---
+name: mongoose
+description: MongoDB object modeling (ODM) for Node.js with schemas, validation, and middleware; consult for structured MongoDB access in JS/TS.
+domain: stack
+category: orm
+tags: [odm, mongodb, nodejs, javascript, typescript, schema]
+official_sources:
+  - https://mongoosejs.com/docs/
+  - https://github.com/Automattic/mongoose
+verified: 2026-06-16
+---
+
+# Mongoose
+
+## Overview
+Mongoose is an Object Data Modeling (ODM) library for MongoDB designed to work in an asynchronous environment. It adds schemas, type casting, validation, query building, and middleware on top of the MongoDB driver. Read this when you want structure and validation around an otherwise schemaless MongoDB database in Node.js (or Deno).
+
+## Official sources
+- Docs: https://mongoosejs.com/docs/
+- Repo: https://github.com/Automattic/mongoose
+- Install / index: https://mongoosejs.com/docs/index.html
+
+## Install / setup
+```bash
+npm install mongoose
+```
+
+## Core concepts
+- **Schema**: defines document shape, types, defaults, and validation rules for a collection.
+- **Model**: a constructor compiled from a schema (`mongoose.model()`) used to create and query documents.
+- **Documents**: model instances with getters/setters, validation, and `.save()`.
+- **Queries**: chainable query builder (`Model.find().where()...`) returning thenable queries.
+- **Middleware (hooks)**: `pre`/`post` hooks on operations like `save`/`validate` for cross-cutting logic.
+- **Population**: `populate()` resolves referenced documents across collections (Mongoose's join-like feature).
+
+## Best practices
+- Call `mongoose.connect()` once at startup and reuse the connection; Mongoose buffers operations until connected.
+- Define validation and required fields in the schema so invalid documents are rejected before write.
+- Use `lean()` for read-only queries to skip hydrating full Mongoose documents and improve performance.
+- Use `populate()` selectively (with field selection) to avoid pulling large referenced documents.
+
+## Common pitfalls
+- Relying on `populate()` like a SQL join for heavy relational workloads → it issues extra queries; model data access patterns accordingly.
+- Expecting MongoDB to enforce the schema → only Mongoose enforces it; writes via the raw driver bypass validation.
+
+## Examples
+```js
+const mongoose = require('mongoose')
+await mongoose.connect(process.env.MONGODB_URI)
+
+const userSchema = new mongoose.Schema({ name: { type: String, required: true } })
+const User = mongoose.model('User', userSchema)
+
+const ada = await User.create({ name: 'Ada' })
+const users = await User.find({ name: 'Ada' }).lean()
+```
+
+## Further reading
+- https://mongoosejs.com/docs/guide.html — schemas guide
+- https://mongoosejs.com/docs/populate.html — population
+
+## Related skills
+- ../prisma — also supports MongoDB with a typed client
+- ../sequelize — ORM for SQL databases (contrast: relational vs document)

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

@@ -0,0 +1,64 @@
+---
+name: prisma
+description: Type-safe TS/JS ORM with a declarative schema DSL, auto-generated client, and migrations; consult when modeling data in Node.js.
+domain: stack
+category: orm
+tags: [orm, typescript, nodejs, database, migrations, postgresql]
+official_sources:
+  - https://www.prisma.io/docs
+  - https://github.com/prisma/prisma
+verified: 2026-06-16
+---
+
+# Prisma ORM
+
+## Overview
+Prisma is a next-generation ORM for Node.js and TypeScript. You declare your data model in a single `schema.prisma` file using its schema DSL, then Prisma generates a fully type-safe query client and manages SQL migrations. Read this when you need ergonomic, type-checked database access against PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB, or CockroachDB.
+
+## Official sources
+- Docs: https://www.prisma.io/docs
+- Repo: https://github.com/prisma/prisma
+- Install / quickstart: https://www.prisma.io/docs/getting-started/quickstart
+
+## Install / setup
+```bash
+npm install prisma @types/pg --save-dev
+npm install @prisma/client @prisma/adapter-pg pg dotenv
+npx prisma init --output ../generated/prisma
+```
+
+## Core concepts
+- **Prisma schema (`schema.prisma`)**: the single source of truth — declares the datasource, generator, and `model` definitions in Prisma's DSL.
+- **Prisma Client**: an auto-generated, type-safe query builder; regenerate it with `npx prisma generate` after schema changes.
+- **Prisma Migrate**: turns schema changes into SQL migration files via `npx prisma migrate dev`.
+- **Models, fields, and relations**: each `model` maps to a table; relation fields and `@relation` express foreign keys.
+- **Prisma Studio**: a GUI to browse and edit data, launched with `npx prisma studio`.
+
+## Best practices
+- Keep the schema as the source of truth and commit migration files; use `migrate dev` in development and `migrate deploy` in production (per Prisma docs).
+- Run `prisma generate` whenever the schema changes so the client's types stay in sync.
+- Instantiate a single `PrismaClient` and reuse it; avoid creating many instances which exhausts the connection pool.
+- Use `select`/`include` to fetch only needed fields and relations rather than over-fetching.
+
+## Common pitfalls
+- Instantiating `PrismaClient` per request (common in serverless/hot-reload) → exhausts connections; use a shared singleton.
+- Forgetting to run `prisma generate` after editing the schema → stale types and runtime mismatches; regenerate after every change.
+
+## Examples
+```ts
+import { PrismaClient } from './generated/prisma'
+const prisma = new PrismaClient()
+
+const user = await prisma.user.create({
+  data: { email: 'a@example.com', name: 'Ada' },
+})
+const users = await prisma.user.findMany({ where: { name: 'Ada' } })
+```
+
+## Further reading
+- https://www.prisma.io/docs/orm/prisma-schema — Prisma schema reference
+- https://www.prisma.io/docs/orm/prisma-migrate — Prisma Migrate guide
+
+## Related skills
+- ../drizzle — lighter-weight TypeScript SQL ORM alternative
+- ../typeorm — decorator-based TS/JS ORM alternative

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

@@ -0,0 +1,65 @@
+---
+name: sequelize
+description: Mature promise-based JS/TS ORM for SQL databases with models, associations, and transactions; consult for established Node.js relational data access.
+domain: stack
+category: orm
+tags: [orm, nodejs, javascript, typescript, sql, transactions]
+official_sources:
+  - https://sequelize.org/docs/v6/
+  - https://github.com/sequelize/sequelize
+verified: 2026-06-16
+---
+
+# Sequelize
+
+## Overview
+Sequelize is a mature, promise-based ORM for Node.js that targets SQL databases including PostgreSQL, MySQL, MariaDB, SQLite, and SQL Server. It provides model definitions, associations, eager/lazy loading, transactions, and read replication. Read this when working in an established JavaScript/TypeScript codebase that uses Sequelize or when you want a battle-tested relational ORM.
+
+## Official sources
+- Docs: https://sequelize.org/docs/v6/
+- Repo: https://github.com/sequelize/sequelize
+- Install / getting started: https://sequelize.org/docs/v6/getting-started/
+
+## Install / setup
+```bash
+npm install --save sequelize
+```
+
+## Core concepts
+- **Sequelize instance**: the connection object created with a connection URI or options, plus the chosen dialect driver.
+- **Models**: defined via `sequelize.define()` or by extending `Model`; map to tables with typed attributes.
+- **Associations**: `hasOne`, `hasMany`, `belongsTo`, `belongsToMany` express relationships and generate helper methods.
+- **Querying**: finder methods (`findAll`, `findOne`, `findByPk`) with `where` operators and `include` for eager loading.
+- **Transactions**: managed (`sequelize.transaction(async t => …)`) or unmanaged, for atomic multi-statement work.
+- **Migrations & seeders**: managed via the separate Sequelize CLI.
+
+## Best practices
+- Install the dialect-specific driver alongside Sequelize (e.g. `pg`, `mysql2`, `sqlite3`) as the docs require.
+- Use managed transactions so commit/rollback is handled automatically on success/error.
+- Prefer migrations over `sync({ force: true })` in production, which drops and recreates tables.
+- Use `include` deliberately and select only needed attributes to avoid N+1 and over-fetching.
+
+## Common pitfalls
+- Running `sequelize.sync({ force: true })` against a real database → drops all tables; use migrations instead.
+- Forgetting to install the dialect driver → connection fails at startup; install the matching driver package.
+
+## Examples
+```js
+const { Sequelize, DataTypes } = require('sequelize')
+const sequelize = new Sequelize(process.env.DATABASE_URL)
+
+const User = sequelize.define('User', {
+  name: { type: DataTypes.STRING },
+})
+
+await sequelize.authenticate()
+const ada = await User.create({ name: 'Ada' })
+```
+
+## Further reading
+- https://sequelize.org/docs/v6/core-concepts/model-basics/ — model basics
+- https://sequelize.org/docs/v6/other-topics/transactions/ — transactions
+
+## Related skills
+- ../typeorm — decorator-based TS/JS ORM alternative
+- ../knex — lower-level SQL query builder Sequelize sits above

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

@@ -0,0 +1,71 @@
+---
+name: sqlalchemy
+description: The de-facto Python SQL toolkit and ORM with Core expression language and full ORM layer; consult for relational data access in Python.
+domain: stack
+category: orm
+tags: [orm, python, sql, database, core, session]
+official_sources:
+  - https://docs.sqlalchemy.org/
+  - https://github.com/sqlalchemy/sqlalchemy
+verified: 2026-06-16
+---
+
+# SQLAlchemy
+
+## Overview
+SQLAlchemy is the de-facto Python SQL toolkit and Object Relational Mapper. It offers two layers: **Core**, a Python SQL expression language and database abstraction, and the **ORM**, which maps classes to tables using the unit-of-work and identity-map patterns. Read this for relational database access in Python when you want full control over SQL alongside high-level ORM mapping.
+
+## Official sources
+- Docs: https://docs.sqlalchemy.org/
+- Repo: https://github.com/sqlalchemy/sqlalchemy
+- Install: https://docs.sqlalchemy.org/en/20/intro.html#installation
+
+## Install / setup
+```bash
+pip install SQLAlchemy
+```
+
+## Core concepts
+- **Engine**: the starting point created with `create_engine()`; manages DBAPI connections and the connection pool.
+- **Core vs ORM**: Core exposes the SQL Expression Language (`Table`, `select()`); the ORM maps classes via declarative models.
+- **Declarative models**: classes inheriting from a `DeclarativeBase` with `Mapped`/`mapped_column` (2.0 style) map to tables.
+- **Session**: the ORM's unit of work — tracks changes and flushes them in a transaction; obtain via `Session`/`sessionmaker`.
+- **2.0 unified query API**: `select()` with `session.execute()` / `session.scalars()` is the modern querying style.
+- **Relationships**: `relationship()` defines associations with configurable lazy/eager loading strategies.
+
+## Best practices
+- Create one `Engine` per database and reuse it; do not create engines per request (per docs, the engine owns the pool).
+- Scope `Session` to a logical unit of work and use it as a context manager / `session.begin()` so transactions commit or roll back cleanly.
+- Use the 2.0-style `select()` API and `Mapped`/`mapped_column` typing for new code.
+- Configure relationship loading (`selectin`, `joined`) deliberately to control eager vs lazy loading and avoid N+1.
+
+## Common pitfalls
+- Sharing a single `Session` across threads/requests → it is not thread-safe; use a fresh session per unit of work (or `scoped_session`).
+- Triggering lazy loads after the session closes → `DetachedInstanceError`; load needed relationships eagerly or keep the session open.
+
+## Examples
+```python
+from sqlalchemy import create_engine, String
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session
+
+class Base(DeclarativeBase): ...
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(50))
+
+engine = create_engine("postgresql+psycopg://localhost/app")
+Base.metadata.create_all(engine)
+with Session(engine) as session:
+    session.add(User(name="Ada"))
+    session.commit()
+```
+
+## Further reading
+- https://docs.sqlalchemy.org/en/20/orm/quickstart.html — ORM quickstart
+- https://docs.sqlalchemy.org/en/20/tutorial/index.html — unified tutorial
+
+## Related skills
+- ../django-orm — Python ORM bundled with Django
+- ../prisma — type-safe ORM in the TS ecosystem

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