constella 0.1.0

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

@@ -0,0 +1,81 @@
+---
+name: postgresql
+description: Robust open-source relational database with strong SQL, ACID, and extensibility; consult for schema design, transactions, and indexing.
+domain: stack
+category: database
+tags: [postgresql, sql, rdbms, relational, acid]
+official_sources:
+  - https://www.postgresql.org/docs/
+  - https://github.com/postgres/postgres
+verified: 2026-06-16
+---
+
+# PostgreSQL
+
+## Overview
+PostgreSQL is a mature, open-source object-relational database emphasizing standards compliance, ACID transactions, and extensibility. Read this when choosing a relational store, designing schemas, writing SQL, or tuning indexes and queries for a Postgres backend.
+
+## Official sources
+- Docs: https://www.postgresql.org/docs/
+- Repo (official GitHub mirror; development uses the project's own git): https://github.com/postgres/postgres
+- Install / download: https://www.postgresql.org/download/
+
+## Install / setup
+Ubuntu, via the PostgreSQL Apt repository (from postgresql.org/download/linux/ubuntu/):
+
+```bash
+sudo apt install -y postgresql-common
+sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
+sudo apt update
+sudo apt install postgresql-18
+```
+
+The simplest path (distribution-included package) is:
+
+```bash
+apt install postgresql
+```
+
+## Core concepts
+- Relational model with ACID transactions; everything runs inside a transaction (explicit or implicit).
+- Rich type system: beyond standard SQL types, native JSON/JSONB, arrays, ranges, and user-defined types.
+- MVCC (Multi-Version Concurrency Control): readers don't block writers and vice versa; old row versions are cleaned by VACUUM.
+- Indexes: B-tree (default), plus GIN, GiST, BRIN, and Hash for specialized access patterns (e.g., GIN for JSONB/full-text).
+- Extensions: functionality like PostGIS or pg_trgm loaded via `CREATE EXTENSION`.
+- Roles and privileges: a unified role system handles both users and groups.
+- Schemas: namespaces within a database for organizing objects.
+
+## Best practices
+- Use the appropriate index type for the query; verify plans with `EXPLAIN ANALYZE` before adding indexes blindly.
+- Prefer `JSONB` over `JSON` when you need to index or query inside documents (binary form supports GIN indexing).
+- Let autovacuum run, and monitor for table bloat on high-churn tables (see docs on routine vacuuming).
+- Use connection pooling for high-concurrency apps; each connection is a backend process.
+- Define explicit constraints (NOT NULL, FOREIGN KEY, CHECK, UNIQUE) so the database enforces integrity.
+
+## Common pitfalls
+- Skipping `EXPLAIN ANALYZE` and assuming an index is used → confirm the planner actually chooses it.
+- Treating `JSON` and `JSONB` as interchangeable → `JSON` preserves text and is not efficiently indexable; use `JSONB` for querying.
+- Ignoring VACUUM/autovacuum on write-heavy tables → leads to bloat and transaction ID wraparound risk.
+- Opening one DB connection per request without pooling → process exhaustion under load.
+
+## Examples
+```sql
+CREATE TABLE users (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  profile JSONB NOT NULL DEFAULT '{}',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_users_profile ON users USING GIN (profile);
+```
+
+## Further reading
+- Indexes: https://www.postgresql.org/docs/current/indexes.html
+- Routine vacuuming: https://www.postgresql.org/docs/current/routine-vacuuming.html
+
+## Related skills
+- ../mysql — alternative open-source RDBMS
+- ../supabase — hosted Postgres with auth/storage/realtime
+- ../neon — serverless Postgres
+- ../cockroachdb — distributed, Postgres-wire-compatible SQL

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

@@ -0,0 +1,78 @@
+---
+name: redis
+description: In-memory data structure store for caching, queues, sessions, and pub/sub; canonical entry for using Redis as cache or fast key-value store.
+domain: stack
+category: database
+tags: [redis, cache, in-memory, key-value, pubsub]
+official_sources:
+  - https://redis.io/docs/latest/
+  - https://github.com/redis/redis
+verified: 2026-06-16
+---
+
+# Redis
+
+## Overview
+Redis is an in-memory data structure store used as a cache, key-value database, message broker, and data structure server. Read this as the canonical entry point when adding caching, session storage, rate limiting, queues, or pub/sub to an application.
+
+## Official sources
+- Docs: https://redis.io/docs/latest/
+- Repo (official; tri-licensed RSALv2/SSPLv1/AGPLv3 for v8.0+): https://github.com/redis/redis
+- Install guide: https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/
+
+## Install / setup
+Run via Docker (works on all platforms, per the official install docs):
+
+```bash
+docker run -d --name redis -p 6379:6379 redis
+```
+
+On Ubuntu/Debian via the official APT repository:
+
+```bash
+sudo apt-get install lsb-release curl gpg
+curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
+sudo chmod 644 /usr/share/keyrings/redis-archive-keyring.gpg
+echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
+sudo apt-get update
+sudo apt-get install redis
+```
+
+## Core concepts
+- In-memory storage: data lives in RAM for sub-millisecond access; persistence is optional.
+- Rich data types: strings, lists, sets, sorted sets, hashes, streams, bitmaps, and more.
+- Key expiration (TTL): set per-key expiry for caches and sessions.
+- Persistence options: RDB snapshots and AOF (append-only file) for durability across restarts.
+- Pub/Sub and Streams: messaging patterns for fan-out and durable, consumer-group-based queues.
+- Atomic operations and transactions (`MULTI`/`EXEC`) plus server-side Lua scripting.
+
+## Best practices
+- Set TTLs on cache keys so memory is reclaimed; choose an eviction policy (e.g., `allkeys-lru`) appropriate to a cache.
+- Use the right data type (e.g., sorted sets for leaderboards, streams for queues) rather than serializing blobs.
+- Enable persistence (RDB and/or AOF) if you cannot tolerate losing data on restart; disable it for pure caches.
+- Use pipelining or `MGET`/`MSET` to batch commands and cut round trips.
+- Avoid large single keys and `O(N)` commands (e.g., `KEYS`) on production; use `SCAN` instead.
+
+## Common pitfalls
+- Treating Redis as a durable system of record without persistence/replication → data loss on restart or eviction.
+- Running `KEYS *` in production → blocks the server; use `SCAN`.
+- Storing huge values or huge collections in one key → memory spikes and slow operations.
+- Forgetting eviction policy on a cache → out-of-memory errors when `maxmemory` is hit.
+
+## Examples
+```bash
+# Cache a value for 60 seconds
+SET session:abc "{...}" EX 60
+
+# Leaderboard with a sorted set
+ZADD scores 100 "ada"
+ZREVRANGE scores 0 9 WITHSCORES
+```
+
+## Further reading
+- Data types: https://redis.io/docs/latest/develop/data-types/
+- Persistence: https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/
+
+## Related skills
+- ../mongodb — document database for primary storage
+- ../postgresql — relational system of record to pair with a Redis cache

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

@@ -0,0 +1,70 @@
+---
+name: sqlite
+description: Embedded, serverless, file-based SQL database; consult for local/app storage, on-device data, tests, and zero-config single-file databases.
+domain: stack
+category: database
+tags: [sqlite, sql, embedded, serverless, file-based]
+official_sources:
+  - https://sqlite.org/docs.html
+  - https://github.com/sqlite/sqlite
+verified: 2026-06-16
+---
+
+# SQLite
+
+## Overview
+SQLite is a self-contained, serverless, zero-configuration, transactional SQL database engine where the entire database is stored in a single cross-platform file. Read this when you need embedded storage inside an application, on-device data, test fixtures, or a lightweight single-file database without a server process.
+
+## Official sources
+- Docs: https://sqlite.org/docs.html
+- Repo (official GitHub mirror; canonical development uses Fossil at sqlite.org/src): https://github.com/sqlite/sqlite
+- Download: https://sqlite.org/download.html
+
+## Install / setup
+SQLite is distributed as precompiled command-line tools and as the C "amalgamation" source from the official download page (sqlite.org/download.html). There is no package-manager install command on that page; you download the binary or amalgamation for your platform. On macOS, after downloading the precompiled binary you may need to clear the quarantine attribute:
+
+```bash
+xattr -d com.apple.quarantine <prog>
+```
+
+(Many language runtimes embed SQLite directly, so no separate install is required.)
+
+## Core concepts
+- Serverless and embedded: the library links into your application; there is no separate server process.
+- Single-file database: the whole database (tables, indexes, data) lives in one ordinary file.
+- ACID transactions: writes are atomic and durable even across crashes/power loss.
+- Dynamic typing with type affinity: columns have an affinity rather than rigid types.
+- Write-Ahead Logging (WAL): an alternative journaling mode that improves concurrency for readers during writes.
+- Public domain: the source code is dedicated to the public domain.
+
+## Best practices
+- Enable WAL mode (`PRAGMA journal_mode=WAL;`) for better read/write concurrency in most applications.
+- Use parameterized queries (bound parameters) to avoid SQL injection and improve plan reuse.
+- Wrap bulk inserts in a single transaction; per-statement autocommit is slow for many rows.
+- Use `STRICT` tables when you want rigid type enforcement instead of type affinity.
+- Keep the database file on local disk, not a network filesystem, to avoid locking issues.
+
+## Common pitfalls
+- Assuming rigid typing → SQLite uses type affinity by default; values may be stored as a different type than declared unless you use STRICT tables.
+- Expecting high write concurrency → SQLite serializes writers; it suits single-writer or low-write-concurrency workloads.
+- Running many inserts in autocommit mode → wrap them in a transaction for orders-of-magnitude speedup.
+- Placing the DB file on NFS/network shares → file locking is unreliable there.
+
+## Examples
+```sql
+PRAGMA journal_mode = WAL;
+
+CREATE TABLE notes (
+  id INTEGER PRIMARY KEY,
+  body TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+) STRICT;
+```
+
+## Further reading
+- Datatypes / type affinity: https://sqlite.org/datatype3.html
+- Write-Ahead Logging: https://sqlite.org/wal.html
+
+## Related skills
+- ../postgresql — full client/server RDBMS for larger workloads
+- ../mysql — client/server RDBMS alternative

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

@@ -0,0 +1,79 @@
+---
+name: supabase
+description: Open-source Firebase alternative built on Postgres with auth, storage, realtime, and edge functions; consult for full-stack Postgres backends.
+domain: stack
+category: database
+tags: [supabase, postgres, baas, auth, realtime]
+official_sources:
+  - https://supabase.com/docs
+  - https://github.com/supabase/supabase
+verified: 2026-06-16
+---
+
+# Supabase
+
+## Overview
+Supabase is an open-source backend-as-a-service that pairs a hosted PostgreSQL database with authentication, file storage, realtime subscriptions, edge functions, and auto-generated APIs. Read this when building a full-stack app that wants Postgres plus auth/storage/realtime without operating each piece yourself.
+
+## Official sources
+- Docs: https://supabase.com/docs
+- Repo (official): https://github.com/supabase/supabase
+- Local development: https://supabase.com/docs/guides/local-development
+
+## Install / setup
+Install the Supabase CLI and start the local stack (requires a Docker-compatible container runtime), from the official local-development guide:
+
+```sh
+npm install supabase --save-dev
+npx supabase init
+npx supabase start
+```
+
+Alternatively, via Homebrew:
+
+```sh
+brew install supabase/tap/supabase
+supabase init
+supabase start
+```
+
+The local Supabase Studio is available at http://localhost:54323.
+
+## Core concepts
+- Postgres-first: every project is a real PostgreSQL database; you can use full SQL and extensions.
+- Row Level Security (RLS): authorization is enforced in the database via Postgres RLS policies.
+- Auth: built-in user management with email/password, OAuth providers, and JWT-based sessions.
+- Auto-generated APIs: REST (PostgREST) and realtime subscriptions are derived from your schema.
+- Storage: S3-compatible object storage with access controlled by policies.
+- Edge Functions: serverless functions (Deno) for custom server-side logic.
+- Migrations and the CLI: manage schema changes and local-to-prod parity.
+
+## Best practices
+- Enable Row Level Security on all tables exposed to clients and write explicit policies; never rely on client-side checks.
+- Develop locally with the CLI and use migrations so schema changes are versioned and reproducible.
+- Keep the `service_role` key server-side only; use the `anon` key (subject to RLS) in clients.
+- Use the database directly for constraints and triggers rather than enforcing integrity in app code.
+- Generate types from your schema for end-to-end type safety in the client.
+
+## Common pitfalls
+- Forgetting to enable RLS, leaving tables world-readable/writable via the anon key → enable RLS and add policies.
+- Exposing the `service_role` key in frontend code → it bypasses RLS; keep it secret.
+- Making schema changes only in the dashboard → drift between environments; use migrations.
+- Treating it as a black box rather than Postgres → you can and should use SQL, indexes, and extensions.
+
+## Examples
+```sql
+-- Enable RLS and restrict rows to their owner
+alter table profiles enable row level security;
+
+create policy "owner can read" on profiles
+  for select using (auth.uid() = user_id);
+```
+
+## Further reading
+- Row Level Security: https://supabase.com/docs/guides/database/postgres/row-level-security
+- Auth: https://supabase.com/docs/guides/auth
+
+## Related skills
+- ../postgresql — the database engine underneath Supabase
+- ../neon — serverless Postgres alternative

package/skills/stacks/dataviz/chart-js/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: chart-js
+description: Chart.js is a popular open-source HTML5 Canvas charting library for the browser with built-in chart types (line, bar, pie, doughnut, radar, scatter, bubble, polar area). Consult when you need responsive, animated, framework-agnostic charts quickly without writing low-level SVG, or when integrating charts with React/Vue/Angular via official wrappers.
+domain: stack
+category: dataviz
+tags: [chart-js, chartjs, dataviz, javascript, canvas, charts, visualization]
+official_sources:
+  - https://www.chartjs.org/docs/latest/
+  - https://github.com/chartjs/Chart.js
+  - https://www.npmjs.com/package/chart.js
+verified: 2026-06-17
+---
+
+# Chart.js
+
+## Overview
+Chart.js is a simple, flexible open-source JavaScript charting library that renders to an HTML5 `<canvas>`. It ships eight core chart types plus animations, tooltips, and responsive resizing out of the box, with a plugin and scale system for extension. Read this when you need clean, interactive charts fast and don't require the fully custom control of a low-level library like D3.
+
+## Official sources
+- Docs: https://www.chartjs.org/docs/latest/
+- Repo: https://github.com/chartjs/Chart.js
+- Install: https://www.npmjs.com/package/chart.js
+
+## Install / setup
+```bash
+npm install chart.js
+```
+Command from the official installation guide (https://www.chartjs.org/docs/latest/getting-started/installation.html); CDN builds are available on jsDelivr (`https://cdn.jsdelivr.net/npm/chart.js`) and CDNJS.
+
+## Core concepts
+- **Chart instance** — `new Chart(ctx, config)` mounts a chart onto a canvas 2D context.
+- **Config object** — `{ type, data, options }` declaratively describes the chart.
+- **Datasets** — each `data.datasets[]` entry holds values, labels, colors, and per-dataset options.
+- **Scales** — cartesian (`x`/`y`) and radial axes configured under `options.scales`.
+- **Tree-shaking** — register only the controllers/elements you use, or import `chart.js/auto` for everything.
+- **Plugins** — lifecycle hooks (`beforeDraw`, `afterEvent`) extend rendering; many community plugins exist.
+- **Responsive** — charts resize to their container by default (`responsive: true`).
+- **Animations** — transitions are configurable per property under `options.animation`.
+
+## Best practices
+- Import from `chart.js/auto` for prototypes, but register components explicitly in production to tree-shake (https://www.chartjs.org/docs/latest/getting-started/integration.html).
+- Give the canvas a sized wrapper element and avoid hard-coding width/height for responsiveness (https://www.chartjs.org/docs/latest/configuration/responsive.html).
+- Call `chart.update()` after mutating `chart.data`, and `chart.destroy()` before recreating to avoid leaks (https://www.chartjs.org/docs/latest/developers/api.html).
+- Use official framework wrappers (react-chartjs-2, vue-chartjs) instead of manually bridging lifecycles.
+
+## Common pitfalls
+- "category is not a registered scale" error → you tree-shook too aggressively; register the needed scales/controllers or use `chart.js/auto`.
+- Chart grows infinitely tall in a flex/grid parent → set `maintainAspectRatio: false` and size the wrapper.
+- Re-rendering over an existing canvas → destroy the previous instance first (`chart.destroy()`).
+
+## Examples
+```js
+import { Chart } from "chart.js/auto";
+
+const ctx = document.getElementById("myChart").getContext("2d");
+new Chart(ctx, {
+  type: "bar",
+  data: {
+    labels: ["Jan", "Feb", "Mar", "Apr"],
+    datasets: [{ label: "Sales", data: [12, 19, 7, 15], backgroundColor: "steelblue" }]
+  },
+  options: { responsive: true, scales: { y: { beginAtZero: true } } }
+});
+```
+
+## Further reading
+- https://www.chartjs.org/docs/latest/charts/line.html — per-chart-type configuration reference.
+- https://www.chartjs.org/docs/latest/samples/ — official runnable samples.
+
+## Related skills
+- ../d3 — drop down to D3 when you need fully custom, non-standard charts.
+- ../plotly — alternative when you need scientific/3D/statistical chart types.

package/skills/stacks/dataviz/d3/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: d3
+description: D3.js (Data-Driven Documents) is a low-level JavaScript library for binding data to the DOM/SVG/Canvas and building bespoke, fully custom interactive data visualizations. Consult when you need hand-crafted charts, scales, axes, transitions, geo/map projections, force layouts, or custom SVG dataviz that off-the-shelf chart libraries can't express.
+domain: stack
+category: dataviz
+tags: [d3, d3js, dataviz, javascript, svg, charts, visualization]
+official_sources:
+  - https://d3js.org/getting-started
+  - https://github.com/d3/d3
+  - https://www.npmjs.com/package/d3
+verified: 2026-06-17
+---
+
+# D3.js
+
+## Overview
+D3.js (Data-Driven Documents) is a low-level JavaScript library for manipulating documents based on data. It gives you scales, selections, axes, shapes, transitions, layouts, and geo projections so you can build any visualization you can imagine—but you draw the marks yourself (SVG/Canvas). Read this when you need fully custom, interactive, or animated charts beyond what high-level libraries like Chart.js or Plotly offer.
+
+## Official sources
+- Docs: https://d3js.org/getting-started
+- Repo: https://github.com/d3/d3
+- Install: https://www.npmjs.com/package/d3
+
+## Install / setup
+```bash
+npm install d3
+```
+Command from the official getting-started guide (https://d3js.org/getting-started); for browser-only use, import the ESM bundle from `https://cdn.jsdelivr.net/npm/d3@7/+esm`.
+
+## Core concepts
+- **Selections** — `d3.select`/`selectAll` wrap DOM nodes for declarative manipulation and the enter/update/exit data-join pattern.
+- **Data join** — `selection.data(arr).join("rect")` binds data to elements, creating, updating, and removing nodes to match.
+- **Scales** — `d3.scaleLinear`, `scaleBand`, `scaleTime`, `scaleOrdinal` map data domains to visual ranges (pixels, colors).
+- **Axes** — `d3.axisBottom(scale)` renders ticks/labels from a scale into an SVG group.
+- **Shape generators** — `d3.line`, `d3.arc`, `d3.area`, `d3.pie` produce SVG path strings from data.
+- **Transitions** — `selection.transition().duration(...)` interpolates attributes/styles for animation.
+- **Modules** — D3 is a collection of independent packages (d3-array, d3-scale, d3-geo…) importable individually.
+- **Geo** — `d3-geo` projections + GeoJSON drive maps and choropleths.
+
+## Best practices
+- Cherry-pick submodules (`import {scaleLinear} from "d3-scale"`) to shrink bundle size (https://d3js.org/getting-started).
+- Use the enter/update/exit (or `.join()`) pattern for dynamic data rather than re-rendering everything (https://d3js.org/d3-selection/joining).
+- Prefer Canvas over SVG when rendering thousands of marks for performance (https://d3js.org/d3-selection).
+- Keep D3 for data/layout math and let a framework own the DOM when integrating with React/Vue.
+
+## Common pitfalls
+- Forgetting the data key function makes `.data()` rebind by index, breaking object constancy → pass a key: `.data(arr, d => d.id)`.
+- Mutating the DOM with both React and D3 causes conflicts → let D3 compute attrs, render via the framework, or isolate D3 in a ref.
+- Misreading scale direction for SVG `y` (origin top-left) → invert the range: `scaleLinear([0, max], [height, 0])`.
+
+## Examples
+```js
+import * as d3 from "d3";
+
+const data = [4, 8, 15, 16, 23, 42];
+const w = 420, h = 120;
+const x = d3.scaleBand().domain(data.map((_, i) => i)).range([0, w]).padding(0.1);
+const y = d3.scaleLinear().domain([0, d3.max(data)]).range([h, 0]);
+
+const svg = d3.select("body").append("svg").attr("width", w).attr("height", h);
+svg.selectAll("rect")
+  .data(data)
+  .join("rect")
+    .attr("x", (_, i) => x(i))
+    .attr("y", d => y(d))
+    .attr("width", x.bandwidth())
+    .attr("height", d => h - y(d))
+    .attr("fill", "steelblue");
+```
+
+## Further reading
+- https://d3js.org/ — module-by-module API reference and live examples.
+- https://observablehq.com/@d3/gallery — official gallery of D3 visualizations.
+
+## Related skills
+- ../chart-js — higher-level canvas charting when you don't need custom marks.
+- ../plotly — declarative interactive charts built on top of d3/WebGL.

package/skills/stacks/dataviz/grafana/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: grafana
+description: Grafana is an open-source observability and analytics platform for querying, visualizing, alerting on, and exploring metrics, logs, and traces from many data sources (Prometheus, Loki, InfluxDB, SQL, and more). Consult when you need to build operational dashboards, set up alerting, wire up data sources, or provision dashboards-as-code for monitoring and observability.
+domain: stack
+category: dataviz
+tags: [grafana, dataviz, observability, dashboards, monitoring, prometheus, alerting]
+official_sources:
+  - https://grafana.com/docs/grafana/latest/
+  - https://github.com/grafana/grafana
+  - https://grafana.com/docs/grafana/latest/setup-grafana/installation/
+verified: 2026-06-17
+---
+
+# Grafana
+
+## Overview
+Grafana is an open-source platform for monitoring and observability: it connects to dozens of data sources and lets you compose interactive dashboards, run ad-hoc queries (Explore), and define alerting—all without storing data itself. It is the de-facto visualization layer for Prometheus, Loki, and time-series stacks. Read this when you need operational dashboards, alert rules, data-source configuration, or dashboards provisioned as code.
+
+## Official sources
+- Docs: https://grafana.com/docs/grafana/latest/
+- Repo: https://github.com/grafana/grafana
+- Install: https://grafana.com/docs/grafana/latest/setup-grafana/installation/
+
+## Install / setup
+```bash
+docker run -d -p 3000:3000 --name grafana grafana/grafana-oss
+```
+Quick-start Docker command from the official install docs (https://grafana.com/docs/grafana/latest/setup-grafana/installation/docker/); browse to http://localhost:3000 and sign in with admin / admin. APT/RPM/Windows installers are documented under the install page.
+
+## Core concepts
+- **Data source** — a connection to a backend (Prometheus, Loki, InfluxDB, MySQL, etc.); Grafana queries it live, it stores nothing.
+- **Dashboard** — a collection of panels arranged on a grid, JSON-modeled and shareable.
+- **Panel** — one visualization (time series, gauge, table, stat, bar gauge…) backed by one or more queries.
+- **Query & transformations** — per-panel queries plus client-side transforms (joins, calculations, reshaping).
+- **Variables** — template variables make dashboards reusable/parameterized (e.g. `$instance`).
+- **Alerting** — unified alert rules evaluate queries and route notifications via contact points.
+- **Provisioning** — data sources and dashboards defined as YAML/JSON files for GitOps.
+- **Explore** — ad-hoc query/log/trace exploration outside dashboards.
+
+## Best practices
+- Provision data sources and dashboards as code (files under `provisioning/`) instead of clicking in the UI (https://grafana.com/docs/grafana/latest/administration/provisioning/).
+- Use template variables and repeating panels/rows to keep dashboards DRY (https://grafana.com/docs/grafana/latest/dashboards/variables/).
+- Move off the bundled SQLite to PostgreSQL/MySQL for production HA (https://grafana.com/docs/grafana/latest/setup-grafana/installation/).
+- Change the default admin password and configure proper auth/proxy before exposing (https://grafana.com/docs/grafana/latest/setup-grafana/configure-security/).
+
+## Common pitfalls
+- Editing dashboards in the UI when they're provisioned from files → changes are read-only/overwritten; edit the source files instead.
+- Relying on SQLite for production → it doesn't scale; migrate the Grafana database to Postgres/MySQL.
+- Dashboard "No data" → mismatched data-source UID or query time range; verify the data source and `$__range`/time picker.
+
+## Examples
+```yaml
+# provisioning/datasources/prometheus.yaml — provision a data source as code
+apiVersion: 1
+datasources:
+  - name: Prometheus
+    type: prometheus
+    access: proxy
+    url: http://prometheus:9090
+    isDefault: true
+```
+
+## Further reading
+- https://grafana.com/docs/grafana/latest/fundamentals/getting-started/ — build your first dashboard.
+- https://grafana.com/docs/grafana/latest/alerting/ — unified alerting reference.
+
+## Related skills
+- ../plotly — code-driven interactive charts when you control the rendering app.
+- ../d3 — fully custom one-off visualizations outside a dashboard tool.

package/skills/stacks/dataviz/plotly/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: plotly
+description: Plotly is an open-source interactive graphing library available for Python (plotly.py), JavaScript (plotly.js), and R, producing web-based charts including statistical, scientific, financial, 3D, and geographic plots. Consult when you need interactive, publication-quality charts in notebooks or web apps, Plotly Express one-liners, or the Dash framework for analytical web dashboards.
+domain: stack
+category: dataviz
+tags: [plotly, plotly-express, dataviz, python, javascript, charts, dash]
+official_sources:
+  - https://plotly.com/python/
+  - https://github.com/plotly/plotly.py
+  - https://plotly.com/python/getting-started/
+verified: 2026-06-17
+---
+
+# Plotly
+
+## Overview
+Plotly is an open-source interactive charting library with high-level APIs for Python, R, and JavaScript, all built on the plotly.js rendering engine (D3 + WebGL). It produces interactive HTML charts—zoom, pan, hover—across statistical, scientific, 3D, and map chart types, and embeds in Jupyter, standalone HTML, or Dash web apps. Read this when you need interactive, exploratory, or publication-quality charts, especially in Python notebooks.
+
+## Official sources
+- Docs: https://plotly.com/python/
+- Repo: https://github.com/plotly/plotly.py
+- Install: https://plotly.com/python/getting-started/
+
+## Install / setup
+```bash
+pip install plotly
+```
+Command from the official Python getting-started guide (https://plotly.com/python/getting-started/); use `pip install "plotly[express]"` for Plotly Express extras, `conda install -c conda-forge plotly`, or for the browser `npm install plotly.js-dist` (https://plotly.com/javascript/getting-started/).
+
+## Core concepts
+- **Figure** — the top-level object (`plotly.graph_objects.Figure`), serializable to JSON, containing `data` traces and a `layout`.
+- **Traces** — typed data series (scatter, bar, heatmap, surface, choropleth…) added to a figure.
+- **Plotly Express (px)** — high-level wrapper that builds whole figures from a dataframe in one call.
+- **Graph Objects (go)** — low-level, explicit figure construction for full control.
+- **Layout** — axes, titles, legends, annotations, and styling under `figure.layout`.
+- **Renderers** — where a figure displays (notebook, browser, static image via Kaleido).
+- **Dash** — Plotly's companion framework for building interactive analytic web apps in pure Python.
+- **plotly.js** — the underlying JS engine; the Python/R libraries emit configs it renders.
+
+## Best practices
+- Reach for Plotly Express first; drop to Graph Objects only when px can't express the chart (https://plotly.com/python/plotly-express/).
+- Use `fig.update_layout()` / `fig.update_traces()` to style rather than rebuilding figures (https://plotly.com/python/creating-and-updating-figures/).
+- Install Kaleido for static PNG/SVG/PDF export (`pip install kaleido`) (https://plotly.com/python/static-image-export/).
+- For large scatter data, use WebGL trace types (`scattergl`) for performance (https://plotly.com/python/webgl-vs-svg/).
+
+## Common pitfalls
+- Figures don't render in a plain script → call `fig.show()` and ensure a renderer; in some contexts write HTML with `fig.write_html()`.
+- `fig.write_image()` fails → Kaleido isn't installed; `pip install kaleido`.
+- Mixing px and go incorrectly → px returns a full `Figure`; add go traces with `fig.add_trace()` rather than reconstructing.
+
+## Examples
+```python
+import plotly.express as px
+
+df = px.data.iris()
+fig = px.scatter(
+    df, x="sepal_width", y="sepal_length",
+    color="species", size="petal_length",
+    title="Iris sepal dimensions",
+)
+fig.update_layout(legend_title_text="Species")
+fig.show()
+```
+
+## Further reading
+- https://plotly.com/python/reference/ — full figure/trace attribute reference.
+- https://dash.plotly.com/ — Dash framework for analytical web apps.
+
+## Related skills
+- ../d3 — the low-level layer beneath plotly.js for fully custom visualizations.
+- ../chart-js — lighter canvas charts when you don't need scientific/3D types.