constella 0.1.0

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

@@ -0,0 +1,77 @@
+---
+name: nginx
+description: Nginx — a high-performance HTTP server, reverse proxy, and load balancer for serving static files, terminating TLS, and proxying to app backends. Consult when writing nginx.conf, configuring server/location blocks, setting up reverse proxy (proxy_pass) or load balancing (upstream), serving static assets, enabling gzip/TLS, or installing from the official nginx.org repo.
+domain: stack
+category: backend
+tags: [nginx, web-server, reverse-proxy, load-balancer, http, tls, backend]
+official_sources:
+  - https://nginx.org/en/docs/
+  - https://github.com/nginx/nginx
+  - https://nginx.org/en/linux_packages.html
+verified: 2026-06-17
+---
+
+# Nginx
+
+## Overview
+Nginx is an event-driven HTTP server and reverse proxy known for high concurrency and low memory use. It serves static content, terminates TLS, load-balances across upstream app servers, and proxies dynamic requests (e.g. to PHP-FPM, Node, or a Spring app). Read this when authoring `nginx.conf`, defining server/location blocks, configuring reverse proxy or load balancing, or installing Nginx from the official repository.
+
+## Official sources
+- Docs: https://nginx.org/en/docs/
+- Repo: https://github.com/nginx/nginx
+- Install: https://nginx.org/en/linux_packages.html
+
+## Install / setup
+```bash
+# Ubuntu/Debian, from the official nginx.org repository (after adding the repo + key):
+sudo apt update && sudo apt install nginx
+```
+Source: https://nginx.org/en/linux_packages.html (add the nginx signing key and `deb ... nginx.org/packages/ubuntu` repo first, then install).
+
+## Core concepts
+- **Master/worker processes** — a master manages config; workers handle connections via an event loop.
+- **Contexts** — directives nest in `main`, `events`, `http`, `server`, and `location` blocks.
+- **server blocks** — virtual hosts matched by `listen` + `server_name`.
+- **location blocks** — match request URIs (prefix, `=`, `~` regex) to behavior.
+- **Reverse proxy** — `proxy_pass` forwards requests to a backend; set `proxy_set_header` for Host/X-Forwarded-*.
+- **upstream / load balancing** — group backends; round-robin, `least_conn`, `ip_hash`.
+- **Static serving** — `root`/`alias` + `try_files` resolve files on disk.
+- **TLS** — `ssl_certificate`/`ssl_certificate_key` on `listen 443 ssl`.
+
+## Best practices
+- Use `try_files $uri $uri/ =404;` (or to a front controller) instead of `if` for routing (https://nginx.org/en/docs/http/ngx_http_core_module.html#try_files).
+- Forward client info on proxies: set `Host`, `X-Forwarded-For`, `X-Forwarded-Proto` (https://nginx.org/en/docs/http/ngx_http_proxy_module.html).
+- Test config before reload: `nginx -t` then `nginx -s reload` (https://nginx.org/en/docs/beginners_guide.html).
+- Enable gzip and sensible `keepalive_timeout`/buffer tuning for throughput (https://nginx.org/en/docs/http/ngx_http_gzip_module.html).
+
+## Common pitfalls
+- Overusing `if` inside `location` causes surprising behavior → prefer `try_files`/`map` ("if is evil").
+- `proxy_pass` with a trailing slash vs none changes the rewritten URI → know the path-rewrite rule.
+- Editing config without `nginx -t` can take down the server on reload → always test first.
+
+## Examples
+```nginx
+upstream app { server 127.0.0.1:3000; }
+
+server {
+    listen 80;
+    server_name example.com;
+
+    location /static/ { root /var/www; }
+
+    location / {
+        proxy_pass http://app;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+## Further reading
+- https://nginx.org/en/docs/beginners_guide.html — beginner's guide to running and configuring nginx
+- https://nginx.org/en/docs/dirindex.html — alphabetical directive index
+
+## Related skills
+- ../spring — proxy a Spring Boot app behind Nginx
+- ../symfony — serve Symfony's front controller via Nginx + PHP-FPM

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

@@ -0,0 +1,68 @@
+---
+name: phoenix
+description: Elixir web framework with realtime channels, LiveView, and an MVC structure on the BEAM; consult when building Phoenix apps or realtime features.
+domain: stack
+category: backend
+tags: [elixir, phoenix, liveview, realtime, web-framework]
+official_sources:
+  - https://hexdocs.pm/phoenix/
+  - https://github.com/phoenixframework/phoenix
+verified: 2026-06-16
+---
+
+# Phoenix
+
+## Overview
+Phoenix is a web framework written in Elixir that aims for "peace of mind from prototype to production." Running on the Erlang VM (BEAM), it provides an MVC structure, realtime communication via Channels, and server-rendered interactive UIs via LiveView. Read this when building Phoenix web apps, APIs, or realtime features.
+
+## Official sources
+- Docs: https://hexdocs.pm/phoenix/ (canonical: https://phoenix.hexdocs.pm/)
+- Repo: https://github.com/phoenixframework/phoenix
+- Install / download: https://hexdocs.pm/phoenix/installation.html
+
+## Install / setup
+```bash
+# Install the Phoenix application generator
+mix archive.install hex phx_new
+
+# Create a new application (replace "hello" with your app name)
+mix phx.new hello
+```
+
+## Core concepts
+- Endpoint & Router: the Endpoint is the entry point handling all requests; the Router maps paths to controllers and pipelines.
+- Plugs & pipelines: composable request-processing functions; pipelines group plugs (e.g. `:browser`, `:api`) applied to route scopes.
+- Controllers, views, templates: controllers handle requests and render templates via view modules, following an MVC structure.
+- Contexts: modules that group related domain logic and data access, keeping the web layer thin.
+- Channels: bidirectional realtime messaging over WebSockets for features like chat and live updates.
+- LiveView: server-rendered, stateful interactive UIs without writing custom client-side JavaScript.
+- Ecto: the data-mapping/query library typically used with Phoenix for schemas and migrations.
+
+## Best practices
+- Organize domain logic into Contexts so the web layer (controllers/LiveViews) stays thin (https://hexdocs.pm/phoenix/contexts.html).
+- Use router pipelines (`:browser`, `:api`) to apply the right plugs per route group.
+- Use Channels/LiveView for realtime rather than polling, leveraging the BEAM's concurrency.
+- Use Ecto migrations and changesets for schema changes and validation.
+
+## Common pitfalls
+- Putting business logic in controllers or LiveViews → move it into Contexts for testability and reuse.
+- Applying the wrong pipeline to a route (e.g. CSRF-protected `:browser` plugs on an API) → scope routes under the matching pipeline.
+- Confusing the package on Hex (`phx_new` generator) with the runtime dependency (`phoenix`) → install the generator archive first, then generate the app.
+
+## Examples
+```elixir
+# lib/hello_web/router.ex
+scope "/", HelloWeb do
+  pipe_through :browser
+  get "/", PageController, :home
+end
+```
+
+## Further reading
+- https://hexdocs.pm/phoenix/up_and_running.html — Up and running
+- https://hexdocs.pm/phoenix/contexts.html — Contexts
+- https://hexdocs.pm/phoenix/channels.html — Channels (realtime)
+
+## Related skills
+- ../rails — another MVC, convention-driven web framework
+- ../laravel — full-stack framework with realtime broadcasting

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

@@ -0,0 +1,67 @@
+---
+name: rails
+description: Convention-driven full-stack Ruby MVC framework with Active Record; consult when building or maintaining a Ruby on Rails backend.
+domain: stack
+category: backend
+tags: [ruby, rails, mvc, active-record, web-framework]
+official_sources:
+  - https://guides.rubyonrails.org/
+  - https://github.com/rails/rails
+verified: 2026-06-16
+---
+
+# Ruby on Rails
+
+## Overview
+Ruby on Rails is a web application framework that includes everything needed to build database-backed apps using the Model-View-Controller pattern. It favors convention over configuration, with Active Record for persistence plus libraries for mail, jobs, WebSockets, file storage, and rich text. Read this when scaffolding, routing, modeling data, or organizing a Rails app.
+
+## Official sources
+- Docs: https://guides.rubyonrails.org/
+- Repo: https://github.com/rails/rails
+- Install / download: https://guides.rubyonrails.org/getting_started.html (install Ruby/Rails: https://guides.rubyonrails.org/install_ruby_on_rails.html)
+
+## Install / setup
+```bash
+# Install the Rails gem (Ruby must already be installed)
+gem install rails
+
+# Create a new application
+rails new store
+```
+
+## Core concepts
+- Convention over configuration: predictable file locations and naming reduce boilerplate; following conventions is what makes Rails productive.
+- MVC layers: Models (domain/data, usually Active Record), Views (templates, typically HTML with embedded Ruby), Controllers (handle HTTP requests and coordinate responses).
+- Active Record: maps classes to tables and provides associations, validations, and query methods; migrations evolve the schema.
+- Routing: `config/routes.rb` maps URLs to controller actions, with RESTful resource routing as the default idiom.
+- Generators: `rails generate` scaffolds models, controllers, and migrations following conventions.
+- Asset and frontend pipeline: Rails integrates view templates and bundled JS/CSS for full-stack rendering.
+
+## Best practices
+- Lean on RESTful resource routes and conventional naming so generators and helpers work as intended (https://guides.rubyonrails.org/getting_started.html).
+- Use migrations for every schema change so databases stay reproducible across environments.
+- Keep business logic in models/service objects rather than controllers (fat-model/skinny-controller idiom).
+- Use the built-in test framework (Minitest) and fixtures to cover models and controllers.
+
+## Common pitfalls
+- Fighting conventions (custom paths, non-standard names) → generators, autoloading, and helpers break; follow Rails naming.
+- Putting heavy logic in controllers or views → move it into models or plain Ruby objects for testability.
+- Editing the schema by hand instead of via migrations → environments drift; always generate and run migrations.
+
+## Examples
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  resources :articles
+  root "articles#index"
+end
+```
+
+## Further reading
+- https://guides.rubyonrails.org/getting_started.html — Getting started
+- https://guides.rubyonrails.org/active_record_basics.html — Active Record basics
+- https://guides.rubyonrails.org/routing.html — Rails routing
+
+## Related skills
+- ../laravel — analogous convention-driven full-stack framework in PHP
+- ../phoenix — MVC-style framework with realtime, in Elixir

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

@@ -0,0 +1,70 @@
+---
+name: spring
+description: Spring Framework and Spring Boot — the Java/Kotlin application framework for dependency injection, web/REST APIs, data access, and security. Consult when building Java backends, wiring beans, writing @RestController endpoints, configuring Spring Boot auto-configuration, JPA/JDBC data access, or bootstrapping a project from Spring Initializr (start.spring.io).
+domain: stack
+category: backend
+tags: [spring, spring-boot, java, kotlin, jvm, dependency-injection, rest]
+official_sources:
+  - https://docs.spring.io/spring-framework/reference/
+  - https://github.com/spring-projects/spring-framework
+  - https://start.spring.io/
+verified: 2026-06-17
+---
+
+# Spring Framework
+
+## Overview
+Spring is the dominant application framework for the JVM, providing an inversion-of-control (IoC) container, declarative transactions, web MVC, data access, and security. Spring Boot layers opinionated auto-configuration and an embedded server on top so apps run with `java -jar`. Read this when building Java/Kotlin backends, defining beans, writing REST controllers, or wiring Spring Data/Security.
+
+## Official sources
+- Docs: https://docs.spring.io/spring-framework/reference/
+- Repo: https://github.com/spring-projects/spring-framework
+- Install: https://start.spring.io/
+
+## Install / setup
+```bash
+# Generate a Spring Boot project from Spring Initializr (web dependency)
+curl https://start.spring.io/starter.zip -d dependencies=web -d type=gradle-project -o demo.zip
+unzip demo.zip && ./gradlew bootRun
+```
+Source: https://spring.io/quickstart/ (start.spring.io generates the project; `./gradlew bootRun` runs it on :8080).
+
+## Core concepts
+- **IoC container / ApplicationContext** — manages bean lifecycle and dependency injection.
+- **Beans & stereotypes** — `@Component`, `@Service`, `@Repository`, `@Controller` register beans; `@Autowired`/constructor injection wires them.
+- **Auto-configuration (Boot)** — `@SpringBootApplication` enables component scan + conditional config based on the classpath.
+- **Spring MVC** — `@RestController` + `@GetMapping`/`@PostMapping` map HTTP to handler methods.
+- **Spring Data** — repository interfaces (`JpaRepository`) generate queries from method names.
+- **Declarative transactions** — `@Transactional` manages commit/rollback boundaries.
+- **Profiles & config** — `application.yml`/`application.properties`, `@Profile`, externalized `@ConfigurationProperties`.
+- **Spring Security** — filter-chain based authn/authz via `SecurityFilterChain` beans.
+
+## Best practices
+- Prefer constructor injection over field injection for testability and immutability (https://docs.spring.io/spring-framework/reference/core/beans/dependencies/factory-collaborators.html).
+- Let Spring Boot starters manage versions; do not pin transitive deps manually (https://docs.spring.io/spring-boot/reference/using/build-systems.html).
+- Externalize config and use profiles instead of hardcoding env values (https://docs.spring.io/spring-boot/reference/features/external-config.html).
+- Keep `@Transactional` on the service layer, not controllers (https://docs.spring.io/spring-framework/reference/data-access/transaction.html).
+
+## Common pitfalls
+- Calling a `@Transactional`/`@Cacheable` method from within the same bean bypasses the proxy → split into a separate bean or use self-injection.
+- Field injection hides missing deps and breaks unit tests → use constructor injection.
+- `@SpringBootApplication` in the wrong package skips component scanning → place it at the root package.
+
+## Examples
+```java
+@RestController
+class HelloController {
+  @GetMapping("/hello")
+  String hello(@RequestParam(defaultValue = "World") String name) {
+    return "Hello " + name;
+  }
+}
+```
+
+## Further reading
+- https://docs.spring.io/spring-boot/index.html — Spring Boot reference docs
+- https://spring.io/guides — official task-focused getting-started guides
+
+## Related skills
+- ../graphql — expose a Spring backend via GraphQL (Spring for GraphQL)
+- ../nginx — reverse-proxy a Spring Boot app behind Nginx

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