constella 0.1.0

package/skills/stacks/infra/fly-io/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: fly-io
+description: Run full-stack apps and databases on a global edge using flyctl and Fly Machines; consult for deploys, regions, and scaling.
+domain: stack
+category: infra
+tags: [hosting, edge, containers, deploy, flyctl, global]
+official_sources:
+  - https://fly.io/docs/
+  - https://github.com/superfly/flyctl
+verified: 2026-06-16
+---
+
+# Fly.io
+
+## Overview
+Fly.io runs your app as containers (Fly Machines) on hardware in many regions, placing instances close to users worldwide. It deploys apps, databases, and background workers driven by the `flyctl` CLI and a `fly.toml` config. Read this when you need to deploy a containerized full-stack app with low latency across regions.
+
+## Official sources
+- Docs: https://fly.io/docs/
+- Repo (flyctl): https://github.com/superfly/flyctl
+- Install: https://fly.io/docs/flyctl/install/
+
+## Install / setup
+```bash
+curl -L https://fly.io/install.sh | sh
+```
+
+## Core concepts
+- Fly Machines: fast-starting micro-VMs running your container image; the unit of compute you deploy and scale.
+- `fly.toml`: per-app configuration declaring services, ports, regions, health checks, and scaling.
+- Regions: apps run in chosen regions; Fly's edge routes each request to a nearby instance.
+- Volumes: persistent local disks attached to a Machine for stateful workloads.
+- Apps & deploys: `fly deploy` builds/pushes an image and rolls Machines to the new release.
+- Private networking: apps in an organization share a private IPv6 (6PN) network for service-to-service traffic.
+
+## Best practices
+- Define health checks in `fly.toml` so rolling deploys only shift traffic to healthy Machines.
+- Co-locate stateful storage (volumes/databases) in the same region as the app instances that use them to avoid cross-region latency.
+- Use secrets (`fly secrets set`) for credentials instead of baking them into the image or committing them.
+- Scale by region to match where your users are rather than over-provisioning a single region.
+
+## Common pitfalls
+- Assuming volumes follow the app across regions → a volume is pinned to one region/Machine; plan placement and replication.
+- Forgetting health checks → a broken release can receive traffic before failing.
+- Treating Machines as long-lived pets → they can be recreated; persist state in volumes or external databases.
+
+## Examples
+```bash
+# Authenticate, scaffold config, and deploy
+fly auth login
+fly launch
+fly deploy
+
+# Store a secret used by the app at runtime
+fly secrets set DATABASE_URL=postgres://...
+```
+
+## Further reading
+- https://fly.io/docs/reference/configuration/ — fly.toml reference
+- https://fly.io/docs/volumes/ — persistent volumes
+
+## Related skills
+- ../railway — similar deploy-anything platform for apps and databases

package/skills/stacks/infra/gcp/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: gcp
+description: Google Cloud Platform and the gcloud CLI; consult for compute, storage, networking, IAM, and scripting GCP resources.
+domain: stack
+category: infra
+tags: [cloud, gcp, gcloud, iam, compute, cli]
+official_sources:
+  - https://cloud.google.com/docs
+  - https://cloud.google.com/sdk/docs/install
+verified: 2026-06-16
+---
+
+# GCP (Google Cloud Platform)
+
+## Overview
+Google Cloud Platform offers compute (Compute Engine, Cloud Run, GKE), storage (Cloud Storage), databases, networking, and IAM across Google's global infrastructure. The Google Cloud CLI (`gcloud`, part of the Google Cloud SDK) is the unified tool for managing and scripting these resources. Read this when you need to provision, manage, or automate GCP infrastructure.
+
+## Official sources
+- Docs: https://cloud.google.com/docs
+- CLI install: https://cloud.google.com/sdk/docs/install
+- Note: the gcloud CLI / Google Cloud SDK is a Google-distributed product without a single canonical public source repo; install from the official download above. The GoogleCloudPlatform GitHub org (https://github.com/GoogleCloudPlatform) hosts samples and tooling such as the cloud-sdk-docker image.
+
+## Install / setup
+Linux, copied verbatim from the official install page:
+```bash
+curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
+tar -xf google-cloud-cli-linux-x86_64.tar.gz
+./google-cloud-sdk/install.sh
+```
+
+## Core concepts
+- Projects: the top-level container for resources, billing, and permissions; nearly everything belongs to a project.
+- IAM: roles and policies binding members (users, service accounts) to permissions on resources.
+- Service accounts: non-human identities used by workloads to call GCP APIs.
+- Regions & zones: resources are deployed to zones within regions for locality and redundancy.
+- Compute options: Compute Engine (VMs), Cloud Run (containers, serverless), and GKE (managed Kubernetes).
+- gcloud config: the active project, account, and region/zone are stored in a CLI configuration.
+
+## Best practices
+- Set the active project/region in your gcloud config (or pass `--project`) so commands target the intended resources.
+- Grant least-privilege IAM roles and use service accounts for workloads instead of personal credentials (per GCP IAM docs).
+- Use Workload Identity / short-lived credentials for CI rather than downloading long-lived service-account key files.
+- Separate environments into distinct projects to isolate billing, quotas, and blast radius.
+
+## Common pitfalls
+- Forgetting to set the active project → commands fail or hit the wrong project.
+- Downloading and committing service-account JSON keys → credential leakage; prefer keyless/short-lived auth.
+- Over-broad primitive roles (Owner/Editor) → use predefined or custom least-privilege roles instead.
+
+## Examples
+```bash
+# Authenticate and select the active project
+gcloud auth login
+gcloud config set project my-project-id
+
+# List compute instances
+gcloud compute instances list
+```
+
+## Further reading
+- https://cloud.google.com/sdk/gcloud — gcloud command reference
+- https://cloud.google.com/iam/docs — IAM documentation
+
+## Related skills
+- ../aws — comparable hyperscale cloud platform
+- ../kubernetes — container orchestration often run on GCP (GKE)

package/skills/stacks/infra/jenkins/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: jenkins
+description: Jenkins is an open-source automation server for building, testing, and deploying software via CI/CD pipelines; consult when configuring Jenkinsfile pipelines, declarative vs scripted syntax, agents/nodes, plugins, stages, credentials, or running a Jenkins controller in Docker.
+domain: stack
+category: infra
+tags: [jenkins, ci-cd, automation, pipeline, devops, infrastructure, build]
+official_sources:
+  - https://www.jenkins.io/doc/
+  - https://github.com/jenkinsci/jenkins
+  - https://www.jenkins.io/doc/book/installing/
+verified: 2026-06-17
+---
+
+# Jenkins
+
+## Overview
+Jenkins is a self-hosted, open-source automation server that orchestrates continuous integration and continuous delivery (CI/CD) pipelines. Pipelines are defined as code in a `Jenkinsfile` and executed across a controller and distributed agents, with thousands of plugins extending its capabilities. Read this when you need to author pipelines, configure build agents, manage credentials, or stand up a Jenkins instance.
+
+## Official sources
+- Docs: https://www.jenkins.io/doc/
+- Repo: https://github.com/jenkinsci/jenkins
+- Install: https://www.jenkins.io/doc/book/installing/
+
+## Install / setup
+```bash
+docker run --name jenkins --restart=on-failure --detach \
+  --publish 8080:8080 --publish 50000:50000 \
+  --volume jenkins-data:/var/jenkins_home \
+  jenkins/jenkins:lts-jdk21
+```
+Source: https://www.jenkins.io/doc/book/installing/docker/
+
+## Core concepts
+- **Controller** — central Jenkins server that stores config, schedules builds, and dispatches work to agents.
+- **Agent (node)** — worker machine/container that executes build steps; isolates workloads from the controller.
+- **Pipeline** — end-to-end automated process defined in a `Jenkinsfile` (declarative or scripted Groovy).
+- **Stage / step** — `stage` groups related work; `step` is a single task (e.g. `sh 'make'`).
+- **Job/project** — a configured unit of work (freestyle, pipeline, or multibranch).
+- **Plugin** — installable extension adding integrations, tools, and pipeline steps.
+- **Credentials** — securely stored secrets injected into builds via the Credentials plugin.
+- **Executor** — a slot on a node that runs one build at a time.
+
+## Best practices
+- Define pipelines as code in a versioned `Jenkinsfile` rather than configuring jobs in the UI (https://www.jenkins.io/doc/book/pipeline/).
+- Prefer the Declarative Pipeline syntax for readability and built-in validation (https://www.jenkins.io/doc/book/pipeline/syntax/).
+- Run builds on agents, keeping the controller free of heavy workloads (https://www.jenkins.io/doc/book/using/using-agents/).
+- Store secrets in the Credentials store and reference via `credentials()`/`withCredentials` (https://www.jenkins.io/doc/book/using/using-credentials/).
+- Pin the LTS release line and update plugins regularly for stability and security (https://www.jenkins.io/doc/book/managing/plugins/).
+
+## Common pitfalls
+- Running heavy builds on the controller → configure dedicated agents and set controller executors to 0.
+- Hardcoding secrets in the Jenkinsfile → use the Credentials plugin and masked bindings.
+- Losing config on container restart → mount a persistent volume at `/var/jenkins_home`.
+
+## Examples
+```groovy
+pipeline {
+    agent any
+    stages {
+        stage('Build') { steps { sh 'make' } }
+        stage('Test')  { steps { sh 'make test' } }
+    }
+}
+```
+
+## Further reading
+- https://www.jenkins.io/doc/book/pipeline/syntax/ — Declarative & Scripted pipeline syntax reference
+- https://plugins.jenkins.io/ — official plugin index
+- https://www.jenkins.io/doc/book/security/ — securing a Jenkins instance
+
+## Related skills
+- ../circleci — managed CI/CD alternative using YAML config
+- ../ansible — provision and configure Jenkins agents

package/skills/stacks/infra/kubernetes/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: kubernetes
+description: Container orchestration for deploying, scaling, and managing containerized apps; consult for Pods, Deployments, Services, and kubectl.
+domain: stack
+category: infra
+tags: [kubernetes, k8s, containers, orchestration, kubectl, cncf]
+official_sources:
+  - https://kubernetes.io/docs/
+  - https://github.com/kubernetes/kubernetes
+verified: 2026-06-16
+---
+
+# Kubernetes
+
+## Overview
+Kubernetes (K8s) is an open-source system, hosted by the CNCF, for automating the deployment, scaling, and management of containerized applications across a cluster of hosts. It exposes a declarative API where you describe desired state and controllers continuously reconcile actual state toward it. Read this when you need to run, scale, or operate containerized workloads on a cluster.
+
+## Official sources
+- Docs: https://kubernetes.io/docs/
+- Repo: https://github.com/kubernetes/kubernetes
+- Install tools: https://kubernetes.io/docs/tasks/tools/
+
+## Install / setup
+Install `kubectl` on Linux, copied verbatim from the official install page:
+```bash
+curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
+sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
+```
+
+## Core concepts
+- Pod: the smallest deployable unit, wrapping one or more containers that share network and storage.
+- Deployment: declares a desired replica count and manages rolling updates of stateless Pods via ReplicaSets.
+- Service: a stable network endpoint and load balancer for a set of Pods selected by labels.
+- ConfigMap & Secret: inject non-secret config and sensitive data into Pods separately from images.
+- Namespace: a virtual cluster partition for isolating and scoping resources.
+- Controllers & reconciliation: control loops continuously drive actual state toward declared desired state.
+- Ingress: rules for routing external HTTP(S) traffic to Services.
+
+## Best practices
+- Manage resources declaratively with version-controlled manifests applied via `kubectl apply`, not imperative one-off edits.
+- Set resource requests and limits on containers so the scheduler can place Pods and prevent noisy-neighbor exhaustion (per the docs).
+- Define liveness and readiness probes so Kubernetes restarts unhealthy Pods and only routes traffic to ready ones.
+- Store sensitive values in Secrets (and a real secrets manager) rather than baking them into images or ConfigMaps.
+
+## Common pitfalls
+- Omitting resource requests/limits → unschedulable Pods or nodes overcommitted and OOM-killed.
+- Missing readiness probe → traffic is sent to Pods before they can serve, causing errors during rollouts.
+- Treating Secrets as encrypted by default → base64 is encoding, not encryption; enable encryption at rest and restrict RBAC access.
+
+## Examples
+```bash
+# Apply a manifest and inspect the rollout
+kubectl apply -f deployment.yaml
+kubectl get pods -n my-namespace
+kubectl rollout status deployment/my-app -n my-namespace
+```
+
+## Further reading
+- https://kubernetes.io/docs/concepts/ — concepts overview
+- https://kubernetes.io/docs/reference/kubectl/ — kubectl reference
+
+## Related skills
+- ../aws — managed Kubernetes via EKS
+- ../gcp — managed Kubernetes via GKE

package/skills/stacks/infra/netlify/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: netlify
+description: Managed hosting for web apps with Git deploys, functions, and edge; consult for deploys, redirects, env vars, and the Netlify CLI.
+domain: stack
+category: infra
+tags: [hosting, serverless, frontend, deploy, cli, jamstack]
+official_sources:
+  - https://docs.netlify.com/
+  - https://github.com/netlify/cli
+verified: 2026-06-16
+---
+
+# Netlify
+
+## Overview
+Netlify is a managed platform for building and hosting web apps, providing Git-connected continuous deployment, serverless and edge functions, and per-deploy preview URLs. It targets static sites and frontend frameworks plus their attached backend functions. Read this when you need to deploy a web app, configure redirects/headers, or drive deploys with the CLI.
+
+## Official sources
+- Docs: https://docs.netlify.com/
+- Repo (CLI): https://github.com/netlify/cli
+- CLI install: https://docs.netlify.com/cli/get-started/
+
+## Install / setup
+```bash
+npm install -g netlify-cli
+```
+
+## Core concepts
+- Continuous deployment: connecting a Git repo triggers a build and deploy on each push.
+- Deploy previews: pull requests/branches get isolated preview URLs before merging to production.
+- Functions: serverless (and edge) functions deployed alongside the site for backend logic.
+- `netlify.toml`: project configuration for build settings, redirects, headers, and function paths.
+- Redirects & rewrites: rule-based routing (including SPA fallback and proxying) defined in config or a `_redirects` file.
+- Environment variables: configured per site/context (production, deploy-preview, branch) and used during build and at runtime.
+
+## Best practices
+- Keep build, publish directory, redirects, and headers in `netlify.toml` so configuration is versioned with the code.
+- For CI environments, install the CLI as a local dev dependency (`npm install netlify-cli --save-dev`) rather than relying on a global install (per the docs).
+- Use an SPA catch-all redirect (`/* /index.html 200`) for client-side routed apps so deep links resolve.
+- Scope environment variables to the correct deploy context to avoid leaking production secrets into previews.
+
+## Common pitfalls
+- Missing SPA redirect → client-side routes 404 on direct navigation.
+- Setting a wrong publish directory → the build succeeds but the deployed site is empty or shows the wrong root.
+- Expecting functions to hold state between invocations → they are stateless and short-lived; use external storage.
+
+## Examples
+```bash
+# Authenticate, link the repo, and deploy to production
+netlify login
+netlify link
+netlify deploy --prod
+```
+
+## Further reading
+- https://docs.netlify.com/routing/redirects/ — redirects and rewrites
+- https://docs.netlify.com/functions/overview/ — functions overview
+
+## Related skills
+- ../vercel — comparable managed frontend hosting platform

package/skills/stacks/infra/railway/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: railway
+description: Deploy apps, databases, and services with Git-driven builds; consult for services, variables, environments, and the Railway CLI.
+domain: stack
+category: infra
+tags: [hosting, paas, deploy, database, cli]
+official_sources:
+  - https://docs.railway.com/
+  - https://github.com/railwayapp/cli
+verified: 2026-06-16
+---
+
+# Railway
+
+## Overview
+Railway is a platform-as-a-service for deploying applications, databases, and supporting services from a Git repo or template, with minimal infrastructure configuration. It groups resources into projects and environments and provisions managed databases (Postgres, Redis, etc.) alongside your app. Read this when you need to stand up an app plus its backing services quickly.
+
+## Official sources
+- Docs: https://docs.railway.com/
+- Repo (CLI): https://github.com/railwayapp/cli
+- CLI install: https://docs.railway.com/guides/cli
+
+## Install / setup
+```bash
+npm i -g @railway/cli
+```
+
+## Core concepts
+- Project: the top-level container that groups related services and environments.
+- Service: a deployable unit (your app, a worker, or a managed database) within a project.
+- Environments: isolated copies of a project's services (e.g. production, staging) with their own variables.
+- Variables: environment variables per service/environment, including auto-injected connection strings from linked databases.
+- Deployments: builds triggered from Git pushes or the CLI, producing a running instance with logs.
+- Plugins/databases: managed datastores provisioned into a project and connected via reference variables.
+
+## Best practices
+- Use separate environments for staging and production rather than reusing one environment for both.
+- Reference database connection details via Railway-provided variables instead of hardcoding credentials.
+- Link the local project with the CLI (`railway link`) so commands and `railway run` use the right environment's variables.
+- Keep service config and variables in Railway/version-controlled config rather than ad hoc dashboard edits where possible.
+
+## Common pitfalls
+- Hardcoding a database URL instead of using the injected reference variable → breaks when the database is recreated or rotated.
+- Running commands against the wrong environment → unlink/relink or confirm the active environment before deploying.
+- Forgetting the CLI requires Node.js 16+ for the npm install method (per the docs).
+
+## Examples
+```bash
+# Authenticate, link a project, and deploy
+railway login
+railway link
+railway up
+
+# Run a local command with the project's env vars injected
+railway run npm start
+```
+
+## Further reading
+- https://docs.railway.com/guides/variables — variables and references
+- https://docs.railway.com/guides/environments — environments
+
+## Related skills
+- ../fly-io — similar deploy platform for apps and databases

package/skills/stacks/infra/tailscale/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: tailscale
+description: Zero-config WireGuard mesh VPN; consult for private networking, ACLs, subnet routing, and secure device-to-device connectivity.
+domain: stack
+category: infra
+tags: [vpn, wireguard, networking, mesh, zero-trust]
+official_sources:
+  - https://tailscale.com/kb/
+  - https://github.com/tailscale/tailscale
+verified: 2026-06-16
+---
+
+# Tailscale
+
+## Overview
+Tailscale builds a private mesh network ("tailnet") between your devices using the WireGuard protocol, with automatic NAT traversal and key distribution handled by a coordination server. It removes the need to manually configure WireGuard keys, firewall holes, or a central VPN concentrator. Read this when you need secure, encrypted connectivity between machines, services, or users without exposing public ports.
+
+## Official sources
+- Docs: https://tailscale.com/kb/
+- Repo: https://github.com/tailscale/tailscale
+- Install / download: https://tailscale.com/download
+
+## Install / setup
+```bash
+curl -fsSL https://tailscale.com/install.sh | sh
+```
+
+## Core concepts
+- Tailnet: the private network of all devices logged into your Tailscale account/organization; each device gets a stable 100.x.y.z address.
+- WireGuard data plane: traffic is end-to-end encrypted directly between peers; the coordination server only brokers keys and metadata, not user traffic.
+- NAT traversal: Tailscale establishes direct peer connections where possible and falls back to encrypted DERP relays when direct paths are blocked.
+- ACLs: a centrally managed policy file defines which devices and identity groups may reach which others, defaulting to deny.
+- Subnet routers: a node can advertise routes so the tailnet reaches non-Tailscale hosts (e.g. an on-prem subnet or cloud VPC).
+- Exit nodes: a node can route all internet traffic for other devices, acting like a traditional full-tunnel VPN egress.
+- MagicDNS: assigns memorable DNS names to devices so you connect by hostname instead of IP.
+
+## Best practices
+- Define least-privilege ACLs rather than relying on the default "allow all" tailnet policy (see Tailscale KB on access control).
+- Use tagged ACL identities (`tag:server`) for servers and CI nodes instead of personal user logins, so access survives staff changes.
+- Apply key expiry and device approval for sensitive tailnets to limit the blast radius of a leaked node.
+- Prefer ephemeral nodes for short-lived/CI workloads so stale devices do not accumulate in the tailnet.
+
+## Common pitfalls
+- Forgetting to enable IP forwarding and `--advertise-routes` on a subnet router → the advertised subnet is unreachable; routes must also be approved in the admin console.
+- Leaving devices with non-expiring keys → revoking access later is harder; set key expiry per the docs.
+- Assuming all connections are direct → behind strict NATs traffic relays through DERP, adding latency; check `tailscale status` for the relay indicator.
+
+## Examples
+```bash
+# Bring a node onto the tailnet
+sudo tailscale up
+
+# Advertise a local subnet so the tailnet can reach it
+sudo tailscale up --advertise-routes=10.0.0.0/24
+
+# Inspect connectivity and peer relay status
+tailscale status
+```
+
+## Further reading
+- https://tailscale.com/kb/1019/subnets/ — subnet routers
+- https://tailscale.com/kb/1018/acls/ — access control policy
+
+## Related skills
+- ../cloudflare — alternative for tunnels and zero-trust access to private services

package/skills/stacks/infra/terraform/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: terraform
+description: Terraform is HashiCorp's declarative infrastructure-as-code tool using HCL to provision cloud and on-prem resources; consult when writing .tf configs, managing state, using providers/modules, planning and applying changes, or working with variables, outputs, and remote backends.
+domain: stack
+category: infra
+tags: [terraform, iac, hashicorp, hcl, devops, infrastructure, provisioning]
+official_sources:
+  - https://developer.hashicorp.com/terraform/docs
+  - https://github.com/hashicorp/terraform
+  - https://developer.hashicorp.com/terraform/install
+verified: 2026-06-17
+---
+
+# Terraform
+
+## Overview
+Terraform is HashiCorp's infrastructure-as-code tool that lets you define cloud and on-prem infrastructure declaratively in HashiCorp Configuration Language (HCL). It computes an execution plan to reach the desired state and applies it through provider plugins, tracking real-world resources in a state file. Read this when authoring `.tf` configuration, managing state, or running the plan/apply lifecycle.
+
+## Official sources
+- Docs: https://developer.hashicorp.com/terraform/docs
+- Repo: https://github.com/hashicorp/terraform
+- Install: https://developer.hashicorp.com/terraform/install
+
+## Install / setup
+```bash
+brew tap hashicorp/tap
+brew install hashicorp/tap/terraform
+```
+Source: https://developer.hashicorp.com/terraform/install
+
+## Core concepts
+- **HCL** — declarative configuration language used in `.tf` files to describe resources.
+- **Provider** — plugin (e.g. `aws`, `azurerm`) that maps HCL to a target API.
+- **Resource** — a single infrastructure object (`resource "aws_instance" "web" {}`).
+- **State** — recorded mapping of config to real resources (`terraform.tfstate`); source of truth for diffs.
+- **Plan / apply** — `plan` previews changes; `apply` enacts them to converge to desired state.
+- **Module** — reusable, parameterized grouping of resources for composition.
+- **Variable / output** — inputs (`variable`) and exported values (`output`) for configurability.
+- **Backend** — where state is stored (local, S3, Terraform Cloud) enabling remote/locked state.
+
+## Best practices
+- Store state remotely with locking (e.g. S3 + DynamoDB, Terraform Cloud) for team safety (https://developer.hashicorp.com/terraform/language/backend).
+- Always review `terraform plan` output before `apply` (https://developer.hashicorp.com/terraform/cli/commands/plan).
+- Pin provider and module versions with constraints to ensure reproducible runs (https://developer.hashicorp.com/terraform/language/providers/requirements).
+- Structure reusable infrastructure as modules with explicit inputs/outputs (https://developer.hashicorp.com/terraform/language/modules).
+- Run `terraform fmt` and `terraform validate` in CI before merging (https://developer.hashicorp.com/terraform/cli/commands/fmt).
+
+## Common pitfalls
+- Committing `terraform.tfstate` (often with secrets) to git → use a remote backend and gitignore local state.
+- Manual ("click-ops") changes drift from config → run `terraform plan` to detect drift and reconcile.
+- Unpinned versions cause surprise upgrades → set `required_providers` and `required_version` constraints.
+
+## Examples
+```hcl
+terraform {
+  required_providers {
+    aws = { source = "hashicorp/aws", version = "~> 5.0" }
+  }
+}
+
+provider "aws" { region = "us-east-1" }
+
+resource "aws_s3_bucket" "data" {
+  bucket = "my-app-data-bucket"
+}
+```
+
+## Further reading
+- https://developer.hashicorp.com/terraform/language — HCL language reference
+- https://registry.terraform.io/ — providers and modules registry
+- https://developer.hashicorp.com/terraform/cli/commands — full CLI command reference
+
+## Related skills
+- ../ansible — configure resources after Terraform provisions them
+- ../azure — target cloud provisioned with the azurerm provider

package/skills/stacks/infra/vagrant/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: vagrant
+description: Vagrant is HashiCorp's tool for building and managing reproducible virtual machine development environments via a Vagrantfile; consult when configuring boxes, providers (VirtualBox/libvirt/Hyper-V), provisioners, synced folders, networking, or running vagrant up/ssh/destroy.
+domain: stack
+category: infra
+tags: [vagrant, hashicorp, virtualization, devops, infrastructure, vm, dev-environment]
+official_sources:
+  - https://developer.hashicorp.com/vagrant/docs
+  - https://github.com/hashicorp/vagrant
+  - https://developer.hashicorp.com/vagrant/install
+verified: 2026-06-17
+---
+
+# Vagrant
+
+## Overview
+Vagrant is HashiCorp's command-line tool for building and managing portable, reproducible virtual machine environments. A single `Vagrantfile` describes the box, provider, networking, and provisioning so any team member can run `vagrant up` to get an identical dev environment. Read this when configuring local VMs, defining provisioners, or scripting the VM lifecycle.
+
+## Official sources
+- Docs: https://developer.hashicorp.com/vagrant/docs
+- Repo: https://github.com/hashicorp/vagrant
+- Install: https://developer.hashicorp.com/vagrant/install
+
+## Install / setup
+```bash
+# macOS via Homebrew
+brew tap hashicorp/tap
+brew install hashicorp/tap/hashicorp-vagrant
+```
+Source: https://developer.hashicorp.com/vagrant/install
+
+## Core concepts
+- **Vagrantfile** — Ruby-based config (one per project) describing how to build and provision the VM.
+- **Box** — packaged base image (e.g. `hashicorp/bionic64`) used as the VM starting point.
+- **Provider** — virtualization backend that runs the VM (VirtualBox, libvirt, Hyper-V, VMware).
+- **Provisioner** — installs/configures software on `up` (shell, Ansible, Chef, Puppet, Docker).
+- **Synced folder** — host directory mounted into the guest (defaults to project dir at `/vagrant`).
+- **Box lifecycle** — `vagrant up` creates/boots, `ssh` connects, `halt` stops, `destroy` removes.
+- **Networking** — forwarded ports, private (host-only), or public (bridged) networks.
+- **Multi-machine** — define several VMs in one Vagrantfile via `config.vm.define`.
+
+## Best practices
+- Commit the `Vagrantfile` to version control so environments are reproducible (https://developer.hashicorp.com/vagrant/docs/vagrantfile).
+- Use provisioners to bake setup into the box rather than manual SSH steps (https://developer.hashicorp.com/vagrant/docs/provisioning).
+- Pin box versions to avoid unexpected base-image changes (https://developer.hashicorp.com/vagrant/docs/boxes/versioning).
+- Source boxes from the official Vagrant Cloud catalog (https://portal.cloud.hashicorp.com/vagrant/discover).
+- Keep provider-specific tweaks in a `config.vm.provider` block for portability (https://developer.hashicorp.com/vagrant/docs/providers).
+
+## Common pitfalls
+- `vagrant` not on PATH after install on Windows → log out and back in so PATH refreshes.
+- Slow or failing synced folders on VirtualBox → enable NFS or rsync for large codebases.
+- Stale VM state after Vagrantfile edits → run `vagrant reload --provision` to re-apply.
+
+## Examples
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.box = "hashicorp/bionic64"
+  config.vm.network "forwarded_port", guest: 80, host: 8080
+  config.vm.provision "shell", inline: "apt-get update && apt-get install -y nginx"
+end
+```
+
+## Further reading
+- https://developer.hashicorp.com/vagrant/docs/vagrantfile — Vagrantfile reference
+- https://developer.hashicorp.com/vagrant/docs/provisioning — provisioners guide
+- https://portal.cloud.hashicorp.com/vagrant/discover — public box catalog
+
+## Related skills
+- ../ansible — provision Vagrant VMs with playbooks
+- ../terraform — provision real infrastructure beyond local VMs