constellai 0.3.0

package/skills/stacks/backend/spring-boot/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: spring-boot
+description: Convention-over-configuration JVM framework for production-grade Spring apps with auto-configuration and embedded servers; consult for Java/Kotlin backends.
+domain: stack
+category: backend
+tags: [spring-boot, java, kotlin, jvm, dependency-injection, backend]
+official_sources:
+  - https://docs.spring.io/spring-boot/
+  - https://github.com/spring-projects/spring-boot
+verified: 2026-06-16
+---
+
+# Spring Boot
+
+## Overview
+Spring Boot helps you create Spring-powered, production-grade applications and services with absolute minimum fuss — no code generation and no XML configuration required. It layers opinionated auto-configuration, starter dependencies, and embedded servers on top of the Spring Framework so apps run standalone. Read this when building JVM (Java/Kotlin) web services or APIs and you want convention over configuration.
+
+## Official sources
+- Docs: https://docs.spring.io/spring-boot/
+- Repo: https://github.com/spring-projects/spring-boot
+- Quickstart: https://spring.io/quickstart
+
+## Install / setup
+The official quickstart scaffolds a project at https://start.spring.io (choose the "web" dependency), then builds and runs it with the bundled Gradle wrapper:
+```bash
+./gradlew bootRun
+```
+On Windows the docs show `.\gradlew.bat bootRun`. (Source: https://spring.io/quickstart)
+
+## Core concepts
+- **Auto-configuration** — Spring Boot configures beans automatically based on the classpath and properties, overridable when needed.
+- **Starters** — curated dependency descriptors (e.g. `spring-boot-starter-web`) pull in a coherent set of libraries.
+- **Inversion of Control / DI** — the Spring container manages beans and injects dependencies (`@Component`, `@Autowired`, constructor injection).
+- **Embedded server** — apps package an embedded Tomcat/Jetty/Netty and run as a standalone executable jar.
+- **Externalized configuration** — `application.properties` / `application.yml`, environment variables, and profiles configure the app.
+- **Actuator** — production-ready endpoints for health, metrics, and monitoring.
+
+## Best practices
+- Use starter dependencies and Spring Initializr (start.spring.io) to get a coherent, version-aligned setup (https://spring.io/quickstart).
+- Prefer constructor injection for required dependencies; it makes beans immutable and easier to test (https://docs.spring.io/spring-framework/reference/core/beans/dependencies/factory-collaborators.html).
+- Externalize configuration and use profiles for environment-specific settings rather than hardcoding (https://docs.spring.io/spring-boot/reference/features/external-config.html).
+- Add Actuator and expose only the endpoints you need for health/metrics in production (https://docs.spring.io/spring-boot/reference/actuator/index.html).
+
+## Common pitfalls
+- Placing components outside the main application class's package → component scanning misses them; keep `@SpringBootApplication` at a root package above your components (https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html).
+- Exposing all Actuator endpoints publicly → leaks sensitive operational data; restrict and secure exposed endpoints (https://docs.spring.io/spring-boot/reference/actuator/endpoints.html).
+
+## Examples
+```java
+@SpringBootApplication
+@RestController
+public class DemoApplication {
+
+  @GetMapping("/")
+  public String home() {
+    return "Hello World!";
+  }
+
+  public static void main(String[] args) {
+    SpringApplication.run(DemoApplication.class, args);
+  }
+}
+```
+
+## Further reading
+- https://docs.spring.io/spring-boot/tutorial/first-application/index.html — first application tutorial
+- https://docs.spring.io/spring-boot/reference/features/external-config.html — configuration reference
+
+## Related skills
+- ../nestjs — comparable DI/module-driven framework in the Node ecosystem

package/skills/stacks/backend/symfony/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: symfony
+description: Symfony — the PHP framework and set of reusable components for building web apps, REST APIs, and CLI tools with routing, dependency injection, Doctrine ORM, and Twig. Consult when scaffolding a Symfony project, defining controllers/routes with attributes, configuring services and bundles, building forms, or using the Symfony CLI / composer create-project.
+domain: stack
+category: backend
+tags: [symfony, php, doctrine, twig, mvc, composer, backend]
+official_sources:
+  - https://symfony.com/doc/current/index.html
+  - https://github.com/symfony/symfony
+  - https://symfony.com/doc/current/setup.html
+verified: 2026-06-17
+---
+
+# Symfony
+
+## Overview
+Symfony is a mature PHP framework built from decoupled, reusable components (HttpFoundation, Routing, DependencyInjection, Console). It powers full-stack web apps, APIs, and microservices, and many of its components underpin other PHP projects (including Laravel and Drupal). Read this when scaffolding a Symfony app, wiring services, defining attribute-based routes, or using Doctrine and Twig.
+
+## Official sources
+- Docs: https://symfony.com/doc/current/index.html
+- Repo: https://github.com/symfony/symfony
+- Install: https://symfony.com/doc/current/setup.html
+
+## Install / setup
+```bash
+# Full-featured web app (Symfony CLI):
+symfony new my_project_directory --version="8.1.*" --webapp
+# Or with Composer:
+composer create-project symfony/skeleton:"8.1.*" my_project_directory
+cd my_project_directory && composer require webapp
+```
+Source: https://symfony.com/doc/current/setup.html
+
+## Core concepts
+- **Front controller & kernel** — all requests route through `public/index.php` into the HTTP kernel.
+- **Routing** — `#[Route]` attributes on controller methods map URLs to actions.
+- **Controllers** — extend `AbstractController`; return a `Response` (or Twig `render()`).
+- **Service container & DI** — autowiring + autoconfiguration wire services; configured in `config/services.yaml`.
+- **Doctrine ORM** — entities, repositories, and migrations for database access.
+- **Twig** — templating engine for views (`templates/`).
+- **Bundles & Flex** — reusable plugins; Symfony Flex installs recipes that auto-configure them.
+- **Console** — `bin/console` runs commands (cache clear, migrations, custom commands).
+
+## Best practices
+- Use attribute-based routing and constructor injection (autowiring) for services (https://symfony.com/doc/current/best_practices.html).
+- Store config in environment variables via `.env`, never commit secrets; use the Secrets vault (https://symfony.com/doc/current/configuration/secrets.html).
+- Keep controllers thin; push logic into services (https://symfony.com/doc/current/controller.html).
+- Use Doctrine migrations rather than auto-updating the schema in production (https://symfony.com/doc/current/doctrine.html).
+
+## Common pitfalls
+- Editing `config/services.yaml` to register every class manually → rely on autowiring/autoconfiguration instead.
+- Forgetting to clear the prod cache after config changes → run `bin/console cache:clear --env=prod`.
+- Running `doctrine:schema:update --force` in prod → generate and run migrations instead.
+
+## Examples
+```php
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\Routing\Attribute\Route;
+
+class HelloController extends AbstractController
+{
+    #[Route('/hello/{name}', name: 'hello')]
+    public function index(string $name = 'World'): JsonResponse
+    {
+        return $this->json(['message' => "Hello $name"]);
+    }
+}
+```
+
+## Further reading
+- https://symfony.com/doc/current/best_practices.html — official best practices
+- https://symfony.com/components — the reusable Symfony components
+
+## Related skills
+- ../codeigniter — lighter-weight PHP MVC alternative
+- ../nginx — serve Symfony's public/ front controller behind Nginx + PHP-FPM

package/skills/stacks/container/containerd/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: containerd
+description: Industry-standard, CNCF-graduated container runtime that manages the full container lifecycle — consult for low-level runtime and Kubernetes CRI work.
+domain: stack
+category: container
+tags: [containerd, container-runtime, oci, cri, kubernetes, cncf]
+official_sources:
+  - https://containerd.io/docs/
+  - https://github.com/containerd/containerd
+verified: 2026-06-16
+---
+
+# containerd
+
+## Overview
+containerd is an industry-standard container runtime that manages the complete container lifecycle — image transfer and storage, container execution and supervision, low-level storage, and network attachments. It is a CNCF graduated project and the runtime that powers Docker and many Kubernetes installations (via the CRI plugin). Read this when working below the Docker/Podman layer, configuring a Kubernetes node runtime, or embedding container management in your own platform.
+
+## Official sources
+- Docs: https://containerd.io/docs/
+- Repo: https://github.com/containerd/containerd
+- Getting started: https://github.com/containerd/containerd/blob/main/docs/getting-started.md
+
+## Install / setup
+Install from the official release binaries, then enable the systemd service (https://github.com/containerd/containerd/blob/main/docs/getting-started.md). Download `containerd-<VERSION>-<OS>-<ARCH>.tar.gz` from https://github.com/containerd/containerd/releases and extract it:
+
+```bash
+tar Cxzvf /usr/local containerd-<VERSION>-<OS>-<ARCH>.tar.gz
+```
+
+Set up the systemd service unit:
+
+```bash
+# Place containerd.service in /usr/local/lib/systemd/system/
+systemctl daemon-reload
+systemctl enable --now containerd
+```
+
+containerd also requires a low-level OCI runtime (`runc`, from https://github.com/opencontainers/runc/releases) and, for networking, the CNI plugins (from https://github.com/containernetworking/plugins/releases).
+
+## Core concepts
+- **Daemon + clients**: a long-running `containerd` daemon exposes a gRPC API; the `ctr` CLI and higher-level tools (Docker, Kubernetes) are clients.
+- **OCI runtime delegation**: containerd does not run containers itself — it shells out to an OCI runtime such as `runc` to create the process.
+- **Namespaces**: API objects (images, containers, snapshots) are isolated into namespaces so multiple consumers (e.g. Docker and k8s) share one daemon without collisions.
+- **Snapshotters**: pluggable storage backends (overlayfs, etc.) that materialize image layers into a container rootfs.
+- **CRI plugin**: implements the Kubernetes Container Runtime Interface so kubelet can use containerd directly as a node runtime.
+- **Content + image store**: content-addressable storage for image layers and manifests, with image pull/push handled over the distribution API.
+
+## Best practices
+- Use higher-level tooling (Docker, nerdctl, Kubernetes) for everyday work; reserve `ctr` for debugging since it is intentionally low-level (https://github.com/containerd/containerd/blob/main/docs/getting-started.md).
+- Match the configured cgroup driver between containerd and kubelet (commonly `systemd`) to avoid node instability (https://github.com/containerd/containerd/blob/main/docs/getting-started.md).
+- Generate and customize the daemon config explicitly (`containerd config default > /etc/containerd/config.toml`) rather than relying on implicit defaults (https://github.com/containerd/containerd/blob/main/docs/getting-started.md).
+- Keep `runc` and CNI plugins installed and version-compatible, since containerd depends on them for execution and networking (https://github.com/containerd/containerd/blob/main/docs/getting-started.md).
+
+## Common pitfalls
+- Expecting a Docker-like UX from `ctr` → it is a debugging tool with no stable UX; use nerdctl or Docker for ergonomic workflows (https://github.com/containerd/containerd/blob/main/docs/getting-started.md).
+- Forgetting that containers from different clients live in separate namespaces → an image pulled in one namespace is not visible in another (https://github.com/containerd/containerd/blob/main/docs/namespaces.md).
+- Installing the containerd binary alone → containers fail to start without `runc`, and pods fail to network without CNI plugins (https://github.com/containerd/containerd/blob/main/docs/getting-started.md).
+
+## Examples
+```bash
+# Pull an image and run a container with the low-level ctr client
+sudo ctr image pull docker.io/library/redis:alpine
+sudo ctr run --rm -t docker.io/library/redis:alpine redis redis-server
+
+# Inspect objects within a specific namespace
+sudo ctr -n k8s.io containers list
+```
+
+## Further reading
+- Getting started guide: https://github.com/containerd/containerd/blob/main/docs/getting-started.md
+- Ops/admin docs: https://github.com/containerd/containerd/blob/main/docs/ops.md
+
+## Related skills
+- ../docker — uses containerd as its underlying runtime
+- ../podman — alternative engine in the same OCI ecosystem

package/skills/stacks/container/docker/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: docker
+description: Build, ship, and run applications in containers with Docker Engine — consult for Dockerfiles, images, and container runtime workflows.
+domain: stack
+category: container
+tags: [docker, containers, dockerfile, oci, image, container-runtime]
+official_sources:
+  - https://docs.docker.com/
+  - https://github.com/moby/moby
+verified: 2026-06-16
+---
+
+# Docker
+
+## Overview
+Docker packages an application and its dependencies into a portable, isolated container image that runs the same way across machines. It solves the "works on my machine" problem by standardizing build, ship, and run steps. Read this when authoring Dockerfiles, building images, or running containers locally and in CI. The upstream engine is the open-source Moby project.
+
+## Official sources
+- Docs: https://docs.docker.com/
+- Repo: https://github.com/moby/moby
+- Install / download: https://docs.docker.com/get-started/get-docker/
+
+## Install / setup
+Docker Desktop (macOS, Windows, Linux) and Docker Engine downloads are listed on the official Get Docker page: https://docs.docker.com/get-started/get-docker/
+
+Install Docker Engine on Ubuntu via the official apt repository (https://docs.docker.com/engine/install/ubuntu/):
+
+```bash
+sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+```
+
+Convenience script for non-production/development setups (https://docs.docker.com/engine/install/ubuntu/):
+
+```bash
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+```
+
+Verify the installation:
+
+```bash
+sudo docker run hello-world
+```
+
+## Core concepts
+- **Image**: a read-only, layered template built from a Dockerfile; each instruction adds a cache-able layer.
+- **Container**: a running (or stopped) instance of an image with its own writable layer and isolated process/network/filesystem namespaces.
+- **Dockerfile**: the declarative build recipe (`FROM`, `RUN`, `COPY`, `CMD`, `ENTRYPOINT`, ...) consumed by the builder.
+- **Registry**: a store for distributing images (e.g. Docker Hub); you `pull`/`push` tagged images by `name:tag`.
+- **Volume / bind mount**: mechanisms for persisting or sharing data outside the container's ephemeral writable layer.
+- **Network**: virtual networks (bridge, host, none, user-defined) that connect containers and control reachability.
+- **BuildKit**: the default modern build backend enabling parallelism, build caching, and multi-stage builds.
+
+## Best practices
+- Use multi-stage builds so the final image ships only runtime artifacts, not build tooling (https://docs.docker.com/build/building/multi-stage/).
+- Order Dockerfile instructions from least- to most-frequently changing and copy dependency manifests before source to maximize layer-cache hits (https://docs.docker.com/build/building/best-practices/).
+- Pin base images to specific tags/digests and keep them minimal (slim/alpine/distroless) to shrink attack surface and size (https://docs.docker.com/build/building/best-practices/).
+- Add a `.dockerignore` to exclude `.git`, `node_modules`, and secrets from the build context (https://docs.docker.com/build/concepts/context/#dockerignore-files).
+- Run containers as a non-root user where possible (`USER`) (https://docs.docker.com/build/building/best-practices/).
+
+## Common pitfalls
+- Baking secrets into image layers via `ENV`/`ARG`/`COPY` → use BuildKit build secrets or runtime env/secret injection instead (https://docs.docker.com/build/building/secrets/).
+- Storing important data only in the container's writable layer → it is lost when the container is removed; use a volume (https://docs.docker.com/engine/storage/volumes/).
+- Using the convenience script in production → it is intended for development; follow the platform-specific install for production (https://docs.docker.com/engine/install/ubuntu/).
+
+## Examples
+```dockerfile
+# Multi-stage build keeps the final image small
+FROM node:22-slim AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-slim
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+USER node
+CMD ["node", "dist/server.js"]
+```
+
+## Further reading
+- Dockerfile reference: https://docs.docker.com/reference/dockerfile/
+- Building best practices: https://docs.docker.com/build/building/best-practices/
+
+## Related skills
+- ../podman — daemonless, Docker-CLI-compatible alternative
+- ../containerd — the runtime Docker uses under the hood

package/skills/stacks/container/podman/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: podman
+description: Daemonless, rootless OCI container and pod engine with a Docker-compatible CLI — consult for running containers without a root daemon.
+domain: stack
+category: container
+tags: [podman, containers, rootless, daemonless, oci, pods]
+official_sources:
+  - https://docs.podman.io/
+  - https://github.com/containers/podman
+verified: 2026-06-16
+---
+
+# Podman
+
+## Overview
+Podman is a daemonless, open-source, Linux-native tool for finding, running, building, sharing, and deploying applications using OCI containers and pods. Unlike Docker it runs without a long-lived root daemon and supports rootless containers, making it attractive for security-sensitive and multi-user environments. Its CLI is largely Docker-compatible, so most `docker` commands map directly to `podman`. Read this when running containers without a daemon or migrating Docker workflows.
+
+## Official sources
+- Docs: https://docs.podman.io/
+- Repo: https://github.com/containers/podman
+- Install / download: https://podman.io/docs/installation
+
+## Install / setup
+Install commands per platform from the official installation page (https://podman.io/docs/installation):
+
+```bash
+# Fedora / CentOS Stream / RHEL
+sudo dnf -y install podman
+
+# Debian
+sudo apt-get -y install podman
+
+# Ubuntu
+sudo apt-get update
+sudo apt-get -y install podman
+
+# Arch / Manjaro
+sudo pacman -S podman
+
+# Alpine
+sudo apk add podman
+
+# openSUSE
+sudo zypper install podman
+```
+
+On macOS and Windows, Podman runs containers inside a managed Linux VM. Initialize and start the machine (https://podman.io/docs/installation):
+
+```bash
+podman machine init
+podman machine start
+podman info
+```
+
+## Core concepts
+- **Daemonless architecture**: each `podman` command is a short-lived process; there is no central root daemon mediating requests.
+- **Rootless containers**: containers can run under an unprivileged user via user namespaces, reducing the blast radius of a container escape.
+- **Pods**: Podman groups one or more containers that share namespaces (e.g. network) into a pod, mirroring the Kubernetes pod concept.
+- **OCI compliance**: images and runtime conform to Open Containers Initiative standards, so images are interchangeable with other OCI tools.
+- **Docker-compatible CLI**: command syntax largely matches Docker; `alias docker=podman` works for many workflows.
+- **libpod**: the underlying library that manages pods, containers, images, and volumes.
+
+## Best practices
+- Prefer rootless mode for everyday use to limit privileges; reserve rootful mode for cases that genuinely require it (https://docs.podman.io/en/latest/markdown/podman.1.html).
+- Generate Kubernetes YAML from running pods/containers with `podman kube generate` to bridge local development and cluster deployment (https://docs.podman.io/en/latest/markdown/podman-kube-generate.1.html).
+- Use `podman generate systemd` / Quadlet to run containers as managed systemd services for reliable startup and restart (https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html).
+- Build images with the bundled Buildah-backed `podman build`, consuming standard Dockerfiles (https://docs.podman.io/en/latest/markdown/podman-build.1.html).
+
+## Common pitfalls
+- Expecting a background daemon/socket like Docker → Podman is daemonless; tools needing the Docker API require enabling the Podman socket service (https://docs.podman.io/en/latest/markdown/podman-system-service.1.html).
+- Privileged-port or low-level networking surprises in rootless mode → rootless containers have restricted capabilities and use slirp/pasta networking by default (https://docs.podman.io/en/latest/markdown/podman-network.1.html).
+- Assuming containers persist across host reboot → use systemd/Quadlet units to auto-restart them (https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html).
+
+## Examples
+```bash
+# Run a rootless container, mapping a host port
+podman run -d --name web -p 8080:80 docker.io/library/nginx:latest
+
+# Create a pod and add a container to it
+podman pod create --name app -p 8000:8000
+podman run -d --pod app docker.io/library/python:3.12 python -m http.server 8000
+
+# Export a running pod to Kubernetes YAML
+podman kube generate app -f app.yaml
+```
+
+## Further reading
+- Podman command reference: https://docs.podman.io/en/latest/Commands.html
+- Tutorials (incl. Docker-to-Podman transition): https://docs.podman.io/en/latest/Tutorials.html
+
+## Related skills
+- ../docker — the daemon-based engine Podman mirrors at the CLI level
+- ../containerd — lower-level OCI runtime used by other container stacks

package/skills/stacks/database/cassandra/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: cassandra
+description: Distributed wide-column NoSQL database for high write throughput and linear scalability; consult for partition-key data modeling with CQL.
+domain: stack
+category: database
+tags: [cassandra, nosql, wide-column, distributed, cql]
+official_sources:
+  - https://cassandra.apache.org/doc/latest/
+  - https://github.com/apache/cassandra
+verified: 2026-06-16
+---
+
+# Apache Cassandra
+
+## Overview
+Apache Cassandra is a distributed, wide-column NoSQL database designed for high write throughput, linear scalability, and no single point of failure across many nodes and data centers. Read this when modeling query-driven schemas with CQL, choosing partition keys, or tuning replication and consistency.
+
+## Official sources
+- Docs: https://cassandra.apache.org/doc/latest/
+- Repo (official, Apache Software Foundation): https://github.com/apache/cassandra
+- Download: https://cassandra.apache.org/_/download.html
+
+## Install / setup
+On Debian/Ubuntu via the official Apache APT repository (from cassandra.apache.org/_/download.html; replace `41x` with the desired series):
+
+```bash
+curl -o /etc/apt/keyrings/apache-cassandra.asc https://downloads.apache.org/cassandra/KEYS
+echo "deb [signed-by=/etc/apt/keyrings/apache-cassandra.asc] https://debian.cassandra.apache.org 41x main" | sudo tee -a /etc/apt/sources.list.d/cassandra.sources.list
+sudo apt-get update
+sudo apt-get install cassandra
+```
+
+A tarball binary is also available from the same download page.
+
+## Core concepts
+- Wide-column model: data is organized in tables with partition keys and clustering columns; query with CQL.
+- Partition key: determines which node(s) store a row's partition; the foundation of data distribution.
+- Clustering columns: define row ordering within a partition.
+- Tunable consistency: per-query consistency levels (e.g., ONE, QUORUM, ALL) trade latency vs. consistency.
+- Replication: replication factor and strategy (e.g., NetworkTopologyStrategy) control copies across racks/data centers.
+- Masterless/peer-to-peer architecture: every node is equal; there is no single point of failure.
+
+## Best practices
+- Design tables per query: denormalize and create one table per access pattern rather than normalizing.
+- Choose partition keys that spread data evenly and keep partitions bounded in size.
+- Use QUORUM reads and writes when you need strong-ish consistency; understand the consistency-level tradeoffs.
+- Avoid unbounded partitions and very wide rows; they cause hotspots and slow queries.
+- Prefer prepared statements in application code for efficiency and safety.
+
+## Common pitfalls
+- Modeling like a relational database (normalization, ad-hoc joins) → Cassandra has no joins; model by query.
+- Picking a low-cardinality partition key → uneven distribution and hotspots.
+- Allowing partitions to grow unbounded → degraded performance and node pressure.
+- Using `ALLOW FILTERING` to make arbitrary queries work → full scans; redesign the table instead.
+
+## Examples
+```sql
+CREATE TABLE messages_by_user (
+  user_id uuid,
+  created_at timestamp,
+  message_id timeuuid,
+  body text,
+  PRIMARY KEY ((user_id), created_at, message_id)
+) WITH CLUSTERING ORDER BY (created_at DESC);
+```
+
+## Further reading
+- Data modeling: https://cassandra.apache.org/doc/latest/cassandra/developing/data-modeling/index.html
+- CQL reference: https://cassandra.apache.org/doc/latest/cassandra/developing/cql/index.html
+
+## Related skills
+- ../cockroachdb — distributed SQL alternative with strong consistency
+- ../mongodb — document NoSQL alternative
+- ../dynamodb — managed key-value/wide-column alternative

package/skills/stacks/database/cockroachdb/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: cockroachdb
+description: Distributed, strongly-consistent SQL database with Postgres wire compatibility; consult for horizontally scalable, survivable SQL backends.
+domain: stack
+category: database
+tags: [cockroachdb, distributed-sql, postgres-compatible, newsql, acid]
+official_sources:
+  - https://www.cockroachlabs.com/docs/
+  - https://github.com/cockroachdb/cockroach
+verified: 2026-06-16
+---
+
+# CockroachDB
+
+## Overview
+CockroachDB is a cloud-native distributed SQL database built on a transactional, strongly-consistent key-value store; it scales horizontally and survives node, zone, and region failures while offering familiar SQL. Read this when you need a resilient, geo-distributed SQL backend that speaks the PostgreSQL wire protocol.
+
+## Official sources
+- Docs: https://www.cockroachlabs.com/docs/
+- Repo (official, Cockroach Labs; CockroachDB Software License for v24.3+): https://github.com/cockroachdb/cockroach
+- Install: https://www.cockroachlabs.com/docs/stable/install-cockroachdb
+
+## Install / setup
+On macOS via Homebrew (from the official install page; note macOS is documented as experimental, not for production):
+
+```bash
+brew install cockroachdb/tap/cockroach
+```
+
+For Linux/Windows or production deployments, download the binary from the official Releases page linked at https://www.cockroachlabs.com/docs/stable/install-cockroachdb.
+
+## Core concepts
+- Distributed SQL: data is automatically split into ranges and replicated across nodes using the Raft consensus protocol.
+- Strong consistency and serializable isolation by default for ACID transactions across the cluster.
+- PostgreSQL wire compatibility: existing Postgres drivers and many SQL features work against CockroachDB.
+- Survivability: configure replication and locality so the cluster tolerates node/zone/region failures.
+- Horizontal scaling: add nodes to increase capacity and throughput without manual sharding.
+- Multi-region features: regional and global tables to control data placement and latency.
+
+## Best practices
+- Choose primary keys that distribute writes (avoid sequential keys that create hotspots); consider hash-sharded indexes for sequential patterns.
+- Run at least three nodes so Raft can tolerate a node failure; set replication factor accordingly.
+- Use the multi-region abstractions (table localities, region survival goals) instead of hand-rolling placement.
+- Retry transactions on serialization errors (40001) — required under serializable isolation.
+- Test against a local cluster that mirrors production replication, not a single insecure node.
+
+## Common pitfalls
+- Using monotonically increasing primary keys → write hotspots on a single range; use UUIDs or hash-sharded indexes.
+- Not handling transaction retry errors → serializable isolation can abort transactions that must be retried.
+- Treating macOS Homebrew installs as production-ready → documented as experimental; use Linux binaries/containers in production.
+- Assuming full Postgres feature parity → most features map, but verify unsupported/different behaviors in the docs.
+
+## Examples
+```sql
+CREATE TABLE events (
+  id UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY,
+  user_id UUID NOT NULL,
+  payload JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+## Further reading
+- Performance best practices: https://www.cockroachlabs.com/docs/stable/performance-best-practices-overview
+- Transactions & retries: https://www.cockroachlabs.com/docs/stable/transactions
+
+## Related skills
+- ../postgresql — wire-compatible single-node relational database
+- ../cassandra — distributed wide-column alternative (different consistency model)

package/skills/stacks/database/dynamodb/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: dynamodb
+description: AWS fully managed serverless key-value and document NoSQL database; consult for single-digit-ms scale, key design, and access-pattern modeling.
+domain: stack
+category: database
+tags: [dynamodb, aws, nosql, key-value, serverless]
+official_sources:
+  - https://docs.aws.amazon.com/dynamodb/
+  - https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html
+verified: 2026-06-16
+---
+
+# Amazon DynamoDB
+
+## Overview
+Amazon DynamoDB is a serverless, fully managed, distributed NoSQL database offering single-digit-millisecond performance at any scale, supporting both key-value and document models. Read this when designing tables, primary keys, and secondary indexes around access patterns for a managed AWS NoSQL backend.
+
+## Official sources
+- Docs: https://docs.aws.amazon.com/dynamodb/
+- Local development (DynamoDB Local): https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html
+
+> Note: DynamoDB is a managed AWS service with no public source repository. There is no open-source server to clone; cite the AWS documentation as the authoritative source.
+
+## Core concepts
+- Tables, items, and attributes: a table holds items (rows); each item is a set of attributes.
+- Primary key: either a partition key alone, or a composite of partition key + sort key.
+- Partition key: hashed to distribute items across storage partitions; central to performance.
+- Sort key: orders items within a partition and enables range queries.
+- Secondary indexes: Global Secondary Indexes (GSI) and Local Secondary Indexes (LSI) enable queries on alternate keys.
+- Capacity modes: on-demand (pay-per-request, auto-scaling, scale to zero) vs. provisioned (set RCU/WCU).
+- No JOINs: DynamoDB has no join operator; denormalize and model around queries.
+
+## Best practices
+- Model around access patterns first; design keys and indexes to serve known queries (often single-table design).
+- Choose high-cardinality partition keys that spread traffic evenly to avoid hot partitions.
+- Use `Query` (which targets a partition key) rather than `Scan` (which reads the whole table) for efficiency.
+- Use on-demand capacity for unpredictable traffic; provisioned with auto-scaling for steady, cost-sensitive workloads.
+- Use DynamoDB Streams to react to item-level changes for event-driven architectures.
+
+## Common pitfalls
+- Designing the schema before the access patterns → leads to costly Scans and missing indexes; model queries first.
+- Using a low-cardinality partition key → hot partitions and throttling.
+- Relying on `Scan` for routine reads → expensive and slow; prefer `Query` with proper keys/indexes.
+- Expecting relational features (joins, ad-hoc queries) → denormalize and precompute instead.
+
+## Examples
+```bash
+# Run DynamoDB Local for development (Docker image)
+docker run -p 8000:8000 amazon/dynamodb-local
+
+# Point the AWS CLI at the local endpoint
+aws dynamodb list-tables --endpoint-url http://localhost:8000
+```
+
+## Further reading
+- Core components: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html
+- Best practices: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/best-practices.html
+
+## Related skills
+- ../mongodb — document NoSQL alternative (self-hostable)
+- ../cassandra — wide-column NoSQL alternative
+- ../redis — in-memory store for caching alongside DynamoDB