constellai 0.3.0

package/skills/stacks/aiml/numpy/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: numpy
+description: NumPy is the foundational Python package for scientific and numerical computing, providing the n-dimensional ndarray plus fast vectorized math, broadcasting, linear algebra, FFT, and random number generation. Consult this when working with arrays and dtypes, vectorizing loops, using broadcasting and slicing/fancy indexing, doing matrix math or reductions along axes, generating random data with the Generator API, or interoperating with pandas, scikit-learn, PyTorch, and TensorFlow.
+domain: stack
+category: aiml
+tags: [numpy, ndarray, scientific-computing, linear-algebra, vectorization, arrays, python]
+official_sources:
+  - https://numpy.org/doc/stable/
+  - https://github.com/numpy/numpy
+  - https://numpy.org/install/
+verified: 2026-06-17
+---
+
+# NumPy
+
+## Overview
+NumPy is the fundamental package for scientific computing with Python, centered on a fast, memory-efficient n-dimensional array object (`ndarray`) and a large library of vectorized mathematical functions. It is the numerical bedrock that pandas, scikit-learn, SciPy, PyTorch, and TensorFlow build on or interoperate with. Read this when manipulating arrays, vectorizing computation, using broadcasting, or doing linear algebra and random sampling.
+
+## Official sources
+- Docs: https://numpy.org/doc/stable/
+- Repo: https://github.com/numpy/numpy
+- Install: https://numpy.org/install/
+
+## Install / setup
+```bash
+pip install numpy
+```
+Command from the official install page: https://numpy.org/install/
+
+## Core concepts
+- **ndarray** — fixed-size, homogeneous n-dimensional array; the core data structure.
+- **dtype** — explicit element type (e.g. `int64`, `float32`) controlling memory and precision.
+- **Broadcasting** — rules that let arrays of different shapes combine elementwise without copies.
+- **Vectorization** — elementwise ufuncs replace Python loops for C-speed computation.
+- **Indexing** — basic slicing (views), plus boolean masks and fancy (integer-array) indexing (copies).
+- **Axes & reductions** — operations like `sum`/`mean`/`max` reduce along a chosen `axis`.
+- **Generator (random)** — modern RNG via `np.random.default_rng()` (preferred over legacy `np.random.*`).
+
+## Best practices
+- Replace Python loops with vectorized ufuncs and broadcasting for speed (https://numpy.org/doc/stable/user/basics.broadcasting.html).
+- Use `np.random.default_rng()` instead of the legacy global random functions (https://numpy.org/doc/stable/reference/random/index.html).
+- Be aware that basic slices return views (mutations propagate); copy with `.copy()` when needed (https://numpy.org/doc/stable/user/basics.copies.html).
+- Pick the smallest sufficient dtype (e.g. `float32`) to cut memory for large arrays (https://numpy.org/doc/stable/reference/arrays.dtypes.html).
+
+## Common pitfalls
+- Mutating a slice view unexpectedly changes the parent array → use `.copy()` for independent data.
+- Integer overflow with fixed-width dtypes wraps silently → cast to a wider dtype before large sums.
+- Comparing floats with `==` fails due to precision → use `np.isclose`/`np.allclose`.
+
+## Examples
+```python
+import numpy as np
+
+rng = np.random.default_rng(0)
+a = rng.standard_normal((1000, 3))          # 1000x3 array
+norms = np.linalg.norm(a, axis=1)           # per-row L2 norm (vectorized)
+unit = a / norms[:, None]                    # broadcasting to normalize rows
+print(unit.shape, np.allclose(np.linalg.norm(unit, axis=1), 1.0))
+```
+
+## Further reading
+- https://numpy.org/doc/stable/user/absolute_beginners.html — beginner's guide
+- https://numpy.org/doc/stable/user/basics.broadcasting.html — broadcasting rules
+- https://numpy.org/doc/stable/reference/ — full API reference
+
+## Related skills
+- ../pandas — built on top of NumPy arrays
+- ../scikit-learn — consumes ndarrays as X/y
+- ../pytorch — tensors convert to/from NumPy

package/skills/stacks/aiml/pandas/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: pandas
+description: pandas is the standard Python library for labeled tabular data analysis and manipulation, providing the DataFrame and Series structures for loading, cleaning, reshaping, grouping, joining, and aggregating data. Consult this when reading/writing CSV/Parquet/Excel/SQL, filtering and selecting rows/columns with loc/iloc, handling missing data, doing groupby aggregations, merging/joining tables, pivoting/melting, working with time series and datetime indexes, or understanding Copy-on-Write (the default in pandas 3.0) and why chained assignment never modifies the original.
+domain: stack
+category: aiml
+tags: [pandas, dataframe, data-analysis, data-wrangling, etl, time-series, python]
+official_sources:
+  - https://pandas.pydata.org/docs/
+  - https://github.com/pandas-dev/pandas
+  - https://pandas.pydata.org/docs/getting_started/install.html
+verified: 2026-06-17
+---
+
+# pandas
+
+## Overview
+pandas is a fast, flexible, and expressive Python library providing labeled data structures (`Series`, `DataFrame`) for working with relational and time-series data. It is the de facto tool for data loading, cleaning, transformation, and exploratory analysis, and feeds most ML and analytics workflows. Read this when wrangling tabular data, doing groupby/merge/pivot operations, or handling missing values and datetime indexes.
+
+## Official sources
+- Docs: https://pandas.pydata.org/docs/
+- Repo: https://github.com/pandas-dev/pandas
+- Install: https://pandas.pydata.org/docs/getting_started/install.html
+
+## Install / setup
+```bash
+pip install pandas
+```
+Command from the official install guide: https://pandas.pydata.org/docs/getting_started/install.html
+
+## Core concepts
+- **DataFrame** — 2D labeled table with heterogeneous typed columns; the central data structure.
+- **Series** — 1D labeled array; a single DataFrame column.
+- **Index** — row/column labels enabling alignment; includes `DatetimeIndex` and `MultiIndex`.
+- **Label vs position selection** — `.loc[]` selects by label, `.iloc[]` by integer position.
+- **groupby** — split-apply-combine for aggregation and transformation over groups.
+- **merge / join / concat** — SQL-style joins and stacking of DataFrames.
+- **reshape** — `pivot`/`pivot_table`, `melt`, `stack`/`unstack` to move between wide and long forms.
+
+## Best practices
+- Assign via `.loc`/`.iloc` (`df.loc[mask, 'col'] = x`) rather than chained indexing (`df[a][b] = x`); under Copy-on-Write (default in pandas 3.0) chained assignment silently does nothing to the original (https://pandas.pydata.org/docs/user_guide/copy_on_write.html).
+- Use vectorized operations and built-in methods instead of `.iterrows()` loops (https://pandas.pydata.org/docs/user_guide/enhancingperf.html).
+- Parse dates explicitly (`pd.to_datetime`, `parse_dates=`) and set a `DatetimeIndex` for time-series work (https://pandas.pydata.org/docs/user_guide/timeseries.html).
+- Prefer columnar formats like Parquet over CSV for large data round-trips (https://pandas.pydata.org/docs/user_guide/io.html).
+
+## Common pitfalls
+- Chained assignment (`df[mask]['col'] = x`) consistently never modifies the original under Copy-on-Write (default in pandas 3.0); no warning is raised (`SettingWithCopyWarning` was removed in 3.0) → use `df.loc[mask, 'col'] = x`.
+- The `inplace=` keyword is being deprecated (PDEP-8) for methods where it is only syntactic sugar for reassignment → prefer reassigning the result. It is retained for value-mutating methods (`fillna`, `replace`, `ffill`, `bfill`, `interpolate`, `where`, `mask`, `clip`), which in pandas 3.0 now return `self` instead of `None`.
+- Mixing label and position with `.ix` (removed) → use `.loc`/`.iloc`.
+
+## Examples
+```python
+import pandas as pd
+
+df = pd.read_csv("sales.csv", parse_dates=["date"])
+df = df.dropna(subset=["amount"])
+monthly = (
+    df.assign(month=df["date"].dt.to_period("M"))
+      .groupby(["month", "region"], as_index=False)["amount"]
+      .sum()
+)
+print(monthly.head())
+```
+
+## Further reading
+- https://pandas.pydata.org/docs/user_guide/index.html — full user guide
+- https://pandas.pydata.org/docs/getting_started/intro_tutorials/index.html — getting-started tutorials
+- https://pandas.pydata.org/docs/reference/index.html — API reference
+
+## Related skills
+- ../numpy — array engine underlying pandas
+- ../scikit-learn — consumes DataFrames for ML
+- ../jupyter — interactive notebooks for data exploration

package/skills/stacks/aiml/pytorch/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: pytorch
+description: PyTorch is an open-source deep learning framework with Pythonic tensors, dynamic (define-by-run) autograd, and strong GPU/CUDA acceleration, widely used for research and production. Consult this when building neural networks with torch.nn, writing training loops with autograd and optimizers, moving tensors between CPU/GPU/MPS devices, loading data with Dataset/DataLoader, compiling with torch.compile, doing distributed/DDP training, or saving/loading state_dict checkpoints, and when debugging device mismatches, gradient/requires_grad issues, or CUDA installs.
+domain: stack
+category: aiml
+tags: [pytorch, deep-learning, machine-learning, autograd, neural-networks, gpu, python]
+official_sources:
+  - https://docs.pytorch.org/docs/stable/index.html
+  - https://github.com/pytorch/pytorch
+  - https://pytorch.org/get-started/locally/
+verified: 2026-06-17
+---
+
+# PyTorch
+
+## Overview
+PyTorch is a Python-first deep learning framework offering GPU-accelerated tensors and a tape-based automatic differentiation system (autograd) with dynamic computation graphs. It is the dominant framework for ML research and is widely deployed in production via TorchScript, `torch.compile`, and ExecuTorch. Read this when defining models, writing custom training loops, managing devices, or building data pipelines.
+
+## Official sources
+- Docs: https://docs.pytorch.org/docs/stable/index.html
+- Repo: https://github.com/pytorch/pytorch
+- Install: https://pytorch.org/get-started/locally/
+
+## Install / setup
+```bash
+# CPU-only (pip). For CUDA/ROCm builds, use the selector to get the right index URL.
+pip install torch torchvision torchaudio
+```
+Command from the official install selector: https://pytorch.org/get-started/locally/
+
+## Core concepts
+- **Tensor** — n-dimensional array with a dtype and `.device`; supports GPU acceleration and NumPy-like ops.
+- **autograd** — tensors with `requires_grad=True` record ops on a dynamic graph; `.backward()` computes gradients.
+- **torch.nn.Module** — base class for models/layers; holds parameters and defines `forward()`.
+- **Optimizer + loss** — `torch.optim` (SGD, Adam) updates parameters from gradients; losses live in `torch.nn`.
+- **Dataset / DataLoader** — abstractions for sampling, batching, shuffling, and parallel data loading.
+- **Device model** — explicitly move tensors/modules with `.to(device)` (`cuda`, `mps`, `cpu`).
+- **torch.compile** — JIT graph capture + kernel fusion for speedups without changing model code.
+
+## Best practices
+- Zero gradients each step (`optimizer.zero_grad()`) before `loss.backward()` (https://docs.pytorch.org/tutorials/beginner/basics/optimization_tutorial.html).
+- Save the `state_dict`, not the whole pickled model, for portable checkpoints (https://docs.pytorch.org/tutorials/beginner/saving_loading_models.html).
+- Wrap eval/inference in `with torch.no_grad():` and call `model.eval()` to disable dropout/batchnorm updates (https://docs.pytorch.org/docs/stable/notes/autograd.html).
+- Use `DataLoader(num_workers=...)` and `pin_memory=True` to overlap loading with compute (https://docs.pytorch.org/docs/stable/data.html).
+
+## Common pitfalls
+- "Expected all tensors on same device" → move both model and inputs with `.to(device)`.
+- Accumulating graphs/memory by appending live tensors to a list → call `.item()` or `.detach()` for logging.
+- Forgetting `model.train()` after `model.eval()` → batchnorm/dropout behave wrong in the next epoch.
+
+## Examples
+```python
+import torch
+from torch import nn
+
+device = "cuda" if torch.cuda.is_available() else "cpu"
+model = nn.Sequential(nn.Linear(784, 128), nn.ReLU(), nn.Linear(128, 10)).to(device)
+opt = torch.optim.Adam(model.parameters(), lr=1e-3)
+loss_fn = nn.CrossEntropyLoss()
+
+x, y = torch.randn(32, 784, device=device), torch.randint(0, 10, (32,), device=device)
+for _ in range(3):
+    opt.zero_grad()
+    loss = loss_fn(model(x), y)
+    loss.backward()
+    opt.step()
+```
+
+## Further reading
+- https://docs.pytorch.org/tutorials/ — official tutorials and recipes
+- https://docs.pytorch.org/docs/stable/notes/autograd.html — autograd mechanics
+- https://pytorch.org/get-started/locally/ — install selector for CPU/CUDA/ROCm
+
+## Related skills
+- ../tensorflow — alternative deep learning framework
+- ../keras — high-level API that can run on a PyTorch backend (Keras 3)
+- ../numpy — array library PyTorch tensors convert to/from

package/skills/stacks/aiml/scikit-learn/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: scikit-learn
+description: scikit-learn is the standard Python library for classical (non-deep) machine learning, offering consistent fit/predict/transform APIs for classification, regression, clustering, dimensionality reduction, model selection, and preprocessing built on NumPy/SciPy. Consult this when choosing an estimator, building Pipelines and ColumnTransformers, doing cross-validation and GridSearchCV/hyperparameter tuning, computing metrics, encoding/scaling features, or avoiding data leakage in train/test splits.
+domain: stack
+category: aiml
+tags: [scikit-learn, machine-learning, sklearn, classification, regression, clustering, python]
+official_sources:
+  - https://scikit-learn.org/stable/
+  - https://github.com/scikit-learn/scikit-learn
+  - https://scikit-learn.org/stable/install.html
+verified: 2026-06-17
+---
+
+# scikit-learn
+
+## Overview
+scikit-learn is a Python machine learning library built on NumPy, SciPy, and matplotlib, providing simple and efficient tools for predictive data analysis. It implements a huge range of classical algorithms behind a uniform estimator API (`fit`, `predict`, `transform`) plus utilities for preprocessing, model selection, and evaluation. Read this when doing tabular/classical ML, building reproducible Pipelines, or tuning and validating models.
+
+## Official sources
+- Docs: https://scikit-learn.org/stable/
+- Repo: https://github.com/scikit-learn/scikit-learn
+- Install: https://scikit-learn.org/stable/install.html
+
+## Install / setup
+```bash
+pip install -U scikit-learn
+```
+Command from the official install guide: https://scikit-learn.org/stable/install.html
+
+## Core concepts
+- **Estimator** — any object with `.fit(X, y)`; the unifying abstraction across all algorithms.
+- **Transformer** — estimator with `.transform()` (scalers, encoders, vectorizers) for feature engineering.
+- **Predictor** — estimator with `.predict()` (and often `.predict_proba`/`.score`) for inference.
+- **Pipeline** — chains transformers + a final estimator so fit/transform happen in order and only on training folds.
+- **ColumnTransformer** — applies different transformers to different column subsets in one object.
+- **Model selection** — `train_test_split`, `cross_val_score`, `GridSearchCV`/`RandomizedSearchCV` for evaluation and tuning.
+- **Metrics** — `sklearn.metrics` for accuracy, precision/recall, ROC AUC, RMSE, R², etc.
+
+## Best practices
+- Put all preprocessing in a `Pipeline` so cross-validation refits transforms per fold and prevents leakage (https://scikit-learn.org/stable/modules/compose.html).
+- Fit scalers/encoders on training data only; never fit on the full dataset before splitting (https://scikit-learn.org/stable/common_pitfalls.html).
+- Use `GridSearchCV`/`RandomizedSearchCV` with a `cv` strategy rather than manual loops (https://scikit-learn.org/stable/modules/grid_search.html).
+- Set `random_state` for reproducible splits and estimators (https://scikit-learn.org/stable/common_pitfalls.html).
+
+## Common pitfalls
+- Data leakage from scaling/encoding before the split → wrap preprocessing in a Pipeline and fit inside CV.
+- Using accuracy on imbalanced classes → prefer precision/recall, F1, or ROC/PR AUC.
+- Passing pandas columns of mixed dtypes → encode categoricals (e.g. `OneHotEncoder`) via ColumnTransformer first.
+
+## Examples
+```python
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.linear_model import LogisticRegression
+from sklearn.model_selection import cross_val_score
+from sklearn.datasets import load_iris
+
+X, y = load_iris(return_X_y=True)
+pipe = Pipeline([
+    ("scale", StandardScaler()),
+    ("clf", LogisticRegression(max_iter=1000)),
+])
+print(cross_val_score(pipe, X, y, cv=5).mean())
+```
+
+## Further reading
+- https://scikit-learn.org/stable/user_guide.html — comprehensive user guide
+- https://scikit-learn.org/stable/auto_examples/index.html — runnable example gallery
+- https://scikit-learn.org/stable/common_pitfalls.html — common pitfalls and recommended practices
+
+## Related skills
+- ../pandas — DataFrames feeding scikit-learn estimators
+- ../numpy — array backbone for X/y inputs
+- ../jupyter — interactive environment for ML experiments

package/skills/stacks/aiml/tensorflow/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: tensorflow
+description: TensorFlow is Google's open-source end-to-end machine learning and deep learning framework for building, training, and deploying models across CPUs, GPUs, and TPUs. Consult this when working with tf.keras models, tf.data input pipelines, tf.function/autograph graph execution, SavedModel export, TensorFlow Serving/Lite/.js deployment, or distributed training (tf.distribute), and when debugging tensor shapes, eager vs graph mode, or GPU/CUDA setup.
+domain: stack
+category: aiml
+tags: [tensorflow, deep-learning, machine-learning, keras, neural-networks, gpu, python]
+official_sources:
+  - https://www.tensorflow.org/learn
+  - https://github.com/tensorflow/tensorflow
+  - https://www.tensorflow.org/install/pip
+verified: 2026-06-17
+---
+
+# TensorFlow
+
+## Overview
+TensorFlow is an end-to-end open-source platform for machine learning, with a comprehensive ecosystem of tools, libraries, and community resources. It centers on tensors flowing through computational graphs and ships the high-level `tf.keras` API for model building plus tooling for production deployment. Read this when building/training deep learning models, optimizing input pipelines, exporting SavedModels, or deploying with TF Serving, Lite, or .js.
+
+## Official sources
+- Docs: https://www.tensorflow.org/learn
+- Repo: https://github.com/tensorflow/tensorflow
+- Install: https://www.tensorflow.org/install/pip
+
+## Install / setup
+```bash
+# CPU-only
+python3 -m pip install tensorflow
+
+# GPU/CUDA (Linux)
+python3 -m pip install 'tensorflow[and-cuda]'
+```
+Commands from the official install guide: https://www.tensorflow.org/install/pip
+
+## Core concepts
+- **Tensor** — immutable n-dimensional array with a dtype and shape; the unit of data that flows through ops.
+- **tf.keras** — the official high-level API for layers, models (`Sequential`, Functional, subclassing), training loops, and metrics.
+- **Eager vs graph execution** — ops run imperatively by default; `@tf.function` traces Python into an optimized graph (AutoGraph) for speed.
+- **tf.data** — composable, performant input pipelines (`map`, `batch`, `shuffle`, `prefetch`) for streaming data into training.
+- **tf.Variable / GradientTape** — variables hold trainable state; `tf.GradientTape` records ops for automatic differentiation.
+- **tf.distribute.Strategy** — abstraction for multi-GPU/multi-host/TPU training (e.g. `MirroredStrategy`).
+- **SavedModel** — language-neutral serialization format for export, serving, and TFLite/TF.js conversion.
+
+## Best practices
+- Use `tf.data` with `.cache()` and `.prefetch(tf.data.AUTOTUNE)` to keep accelerators fed (https://www.tensorflow.org/guide/data_performance).
+- Wrap hot training steps in `@tf.function` rather than running everything eagerly (https://www.tensorflow.org/guide/function).
+- Use `tf.distribute.MirroredStrategy` for multi-GPU instead of manual device placement (https://www.tensorflow.org/guide/distributed_training).
+- Export a SavedModel for serving with `model.export("path")` (or `tf.saved_model.save(model, "path")`); use `model.save("model.keras")` for the native Keras checkpoint format. In Keras 3 (TF 2.16+), `model.save()` requires a `.keras` extension and no longer writes a SavedModel (https://www.tensorflow.org/guide/saved_model).
+
+## Common pitfalls
+- Mixing NumPy ops inside `@tf.function` creates Python side effects that get traced once → use TF ops or `tf.numpy_function`.
+- Forgetting `.prefetch`/`.batch` ordering starves the GPU → batch then prefetch with AUTOTUNE.
+- GPU not detected → verify with `tf.config.list_physical_devices('GPU')` and match CUDA/cuDNN to the install matrix.
+
+## Examples
+```python
+import tensorflow as tf
+
+model = tf.keras.Sequential([
+    tf.keras.layers.Dense(128, activation="relu"),
+    tf.keras.layers.Dense(10),
+])
+model.compile(optimizer="adam",
+              loss=tf.keras.losses.SparseCategoricalCrossentropy(from_logits=True),
+              metrics=["accuracy"])
+
+(x, y), _ = tf.keras.datasets.mnist.load_data()
+ds = tf.data.Dataset.from_tensor_slices((x / 255.0, y)).batch(32).prefetch(tf.data.AUTOTUNE)
+model.fit(ds, epochs=3)
+```
+
+## Further reading
+- https://www.tensorflow.org/tutorials — official tutorials (beginner to advanced)
+- https://www.tensorflow.org/guide — in-depth guides on tf.data, tf.function, distribution
+- https://www.tensorflow.org/api_docs/python/tf — full Python API reference
+
+## Related skills
+- ../keras — high-level model API; tf.keras is TensorFlow's bundled Keras
+- ../pytorch — alternative deep learning framework
+- ../numpy — array foundation TensorFlow interops with

package/skills/stacks/auth/auth0/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: auth0
+description: Auth0 — hosted identity platform built on OAuth 2.0 and OpenID Connect for adding login, SSO, and M2M auth via Universal Login and SDKs.
+domain: stack
+category: auth
+tags: [auth, identity, oauth2, oidc, sso, universal-login, jwt, saml]
+official_sources:
+  - https://auth0.com/docs
+  - https://github.com/auth0
+verified: 2026-06-16
+---
+
+# Auth0
+
+## Overview
+Auth0 is a hosted identity and access management platform that adds authentication and authorization to applications using OAuth 2.0 and OpenID Connect (plus SAML). It provides Universal Login, quickstarts and SDKs for many frameworks, and supports flows for web, single-page, native, machine-to-machine, and device apps. Read this when you want a managed IdP rather than self-hosting auth.
+
+## Official sources
+- Docs: https://auth0.com/docs
+- Repo (org): https://github.com/auth0
+- Install / quickstarts: https://auth0.com/docs/quickstarts
+
+## Install / setup
+```bash
+npm install @auth0/nextjs-auth0
+```
+(Auth0 publishes per-framework SDKs from its official, domain-verified GitHub org — e.g. `nextjs-auth0`, `auth0-react`, `auth0-spa-js`, `node-auth0`. Pick the SDK matching your stack from https://auth0.com/docs/quickstarts.)
+
+## Core concepts
+- Tenant: your isolated Auth0 environment with its own users, applications, and configuration.
+- Application (client): a registered app type — Single Page, Regular Web, Native, or Machine-to-Machine — each mapped to an appropriate OAuth flow.
+- Universal Login: Auth0-hosted login page that centralizes authentication and enables SSO across apps.
+- OAuth 2.0 / OIDC flows: Auth0 documents Authorization Code, Authorization Code with PKCE, Client Credentials (M2M), Device Authorization, and more, each suited to an app type.
+- Tokens: Auth0 issues ID tokens (OIDC) and access tokens (often JWTs) that apps and APIs validate.
+- APIs & scopes: protect your backend by registering it as an API with an audience and scopes/permissions.
+
+## Best practices
+- Use Authorization Code Flow with PKCE for SPAs and native/mobile apps; Auth0 documents PKCE as the recommended public-client flow (https://auth0.com/docs/get-started/authentication-and-authorization-flow).
+- Use the Client Credentials flow for machine-to-machine access, not user-facing flows.
+- Prefer Universal Login over embedding login forms, to get SSO, attack protection, and consistent UX.
+- Validate access tokens at your API by audience and issuer; don't trust ID tokens for API authorization.
+
+## Common pitfalls
+- Choosing the wrong application type → mismatched flow (e.g. SPA configured as a Regular Web App) breaks token handling; pick the type that matches your app.
+- Using the Resource Owner Password flow for normal logins → Auth0 marks it as not recommended and only for highly-trusted clients.
+- Treating the ID token as an API access token → use the access token (with the right audience/scopes) to authorize API calls.
+
+## Examples
+```ts
+// Next.js (App Router) with @auth0/nextjs-auth0
+import { Auth0Client } from "@auth0/nextjs-auth0/server"
+
+export const auth0 = new Auth0Client()
+// Configure AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_SECRET, APP_BASE_URL in env.
+```
+
+## Further reading
+- https://auth0.com/docs/get-started/authentication-and-authorization-flow — choosing the right flow
+- https://auth0.com/docs/quickstarts — framework quickstarts
+
+## Related skills
+- ../keycloak — self-hosted open-source IdP alternative
+- ../clerk — hosted auth with prebuilt UI components

package/skills/stacks/auth/authjs/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: authjs
+description: Framework-agnostic authentication for JS/TS apps (Auth.js, formerly NextAuth.js) — consult when adding OAuth/OIDC, email, or credentials sign-in.
+domain: stack
+category: auth
+tags: [auth, oauth, oidc, nextauth, nextjs, sveltekit, sessions]
+official_sources:
+  - https://authjs.dev/
+  - https://github.com/nextauthjs/next-auth
+verified: 2026-06-16
+---
+
+# Auth.js (NextAuth.js)
+
+## Overview
+Auth.js is an open-source set of packages for authentication built on standard Web APIs, usable with any framework on any JS runtime. It was formerly known as NextAuth.js; the `next-auth` package serves Next.js, while sibling packages (`@auth/sveltekit`, `@auth/express`, Qwik, etc.) target other frameworks. Read this when wiring sign-in flows, OAuth providers, or sessions into a JS/TS app.
+
+## Official sources
+- Docs: https://authjs.dev/
+- Repo: https://github.com/nextauthjs/next-auth
+- Install / download: https://authjs.dev/getting-started/installation
+
+## Install / setup
+```bash
+npm install next-auth@beta
+```
+After installing, generate the required secret:
+```bash
+npx auth secret
+```
+(For other frameworks the official install page lists `@auth/sveltekit`, `@auth/express`, and the Qwik `qwik add auth` flow.)
+
+## Core concepts
+- Providers: pluggable sign-in methods — OAuth/OIDC providers, email (magic link), and credentials. Configure them in the Auth.js config object.
+- Sessions: Auth.js issues a session that can be a JWT (default, stateless) or database-backed via an adapter; you read it on server and client.
+- Adapters: connect Auth.js to your database (Prisma, Drizzle, etc.) to persist users, accounts, and sessions.
+- Callbacks: hooks (`signIn`, `jwt`, `session`, `redirect`) let you customize token contents, authorization, and redirects.
+- `AUTH_SECRET`: required environment variable used to encrypt tokens and sign cookies; generated with `npx auth secret`.
+- Framework packages: the core is framework-agnostic; you install the package matching your framework (`next-auth`, `@auth/sveltekit`, `@auth/express`).
+
+## Best practices
+- Always set a strong `AUTH_SECRET` (use `npx auth secret`) and keep it out of source control. See https://authjs.dev/getting-started/installation.
+- Prefer OAuth/OIDC or email providers over the Credentials provider; the docs note credentials are inherently less secure and bypass much of Auth.js's built-in protection.
+- Use an adapter when you need to persist users/accounts or link multiple providers to one user.
+- Restrict access using the `signIn`/`authorized` callbacks rather than ad-hoc checks scattered through your app.
+
+## Common pitfalls
+- Installing the stable major when following current docs → the v5 (Auth.js) getting-started uses `next-auth@beta`; mixing v4 docs with v5 config breaks setup.
+- Forgetting `AUTH_SECRET` in production → sign-in fails or sessions cannot be decrypted; set it in the deployment environment.
+- Assuming Auth.js is Next.js-only → it is framework-agnostic; use the correct package for your framework.
+
+## Examples
+```ts
+// auth.ts (Next.js, Auth.js v5)
+import NextAuth from "next-auth"
+import GitHub from "next-auth/providers/github"
+
+export const { handlers, signIn, signOut, auth } = NextAuth({
+  providers: [GitHub],
+})
+```
+
+## Further reading
+- https://authjs.dev/getting-started — official getting-started guides per framework
+- https://authjs.dev/getting-started/providers — provider catalog
+
+## Related skills
+- ../auth0 — hosted OAuth/OIDC platform you can plug in as a provider
+- ../clerk — alternative hosted auth with prebuilt UI

package/skills/stacks/auth/clerk/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: clerk
+description: Hosted authentication and user management with prebuilt React/JS UI components — consult when adding sign-up, sign-in, and profile flows fast.
+domain: stack
+category: auth
+tags: [auth, user-management, react, nextjs, components, sessions, mfa]
+official_sources:
+  - https://clerk.com/docs
+  - https://github.com/clerk/javascript
+verified: 2026-06-16
+---
+
+# Clerk
+
+## Overview
+Clerk is a hosted authentication and user-management platform that ships prebuilt, customizable UI components (sign-up, sign-in, user profile, organization switcher) plus SDKs for frameworks like Next.js and React. It handles sessions, MFA, and organizations so you don't build user storage yourself. Read this when you want production auth with minimal UI work.
+
+## Official sources
+- Docs: https://clerk.com/docs
+- Repo: https://github.com/clerk/javascript
+- Install / download: https://clerk.com/docs/quickstarts/setup-clerk
+
+## Install / setup
+```bash
+npm install @clerk/nextjs
+```
+(Command from the official Next.js quickstart, https://clerk.com/docs/quickstarts/nextjs. Other frameworks use the matching `@clerk/*` package, e.g. `@clerk/clerk-react`.)
+
+## Core concepts
+- Prebuilt components: `<SignIn />`, `<SignUp />`, `<UserButton />`, `<UserProfile />`, and `<OrganizationSwitcher />` provide drop-in, themeable auth UI.
+- Application / instance: Clerk apps have a development and production instance, each with publishable and secret keys.
+- Sessions & JWTs: Clerk manages user sessions and can issue JWTs/templates to authenticate requests to your backend.
+- Organizations: built-in multi-tenancy — users belong to organizations with roles and memberships.
+- Control components: `<SignedIn>`, `<SignedOut>`, and helpers gate UI based on auth state; middleware protects routes (e.g. `clerkMiddleware` in Next.js).
+- SDK packages: the `@clerk/javascript` monorepo provides environment-specific SDKs under the `@clerk` namespace.
+
+## Best practices
+- Keep the secret key server-side only; expose only the publishable key to the client. See https://clerk.com/docs.
+- Use Clerk middleware to protect routes centrally rather than checking auth in each handler.
+- Use Organizations for B2B/multi-tenant apps instead of rolling your own tenancy model.
+- Customize the prebuilt components via appearance props rather than rebuilding flows from scratch.
+
+## Common pitfalls
+- Installing the wrong SDK package → use `@clerk/nextjs` for Next.js, `@clerk/clerk-react` for plain React; mixing them breaks the integration.
+- Leaking the secret key into client bundles → only the publishable key is safe client-side.
+- Forgetting to wrap the app in the Clerk provider / middleware → components throw because there's no Clerk context.
+
+## Examples
+```tsx
+// app/layout.tsx (Next.js App Router)
+import { ClerkProvider, SignedIn, SignedOut, SignInButton, UserButton } from "@clerk/nextjs"
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <ClerkProvider>
+      <html><body>
+        <SignedOut><SignInButton /></SignedOut>
+        <SignedIn><UserButton /></SignedIn>
+        {children}
+      </body></html>
+    </ClerkProvider>
+  )
+}
+```
+
+## Further reading
+- https://clerk.com/docs/quickstarts/nextjs — Next.js quickstart
+- https://clerk.com/docs/references/nextjs/clerk-middleware — route protection
+
+## Related skills
+- ../auth0 — alternative hosted identity platform (OAuth/OIDC focused)
+- ../authjs — open-source, self-hosted alternative for JS/TS

package/skills/stacks/auth/keycloak/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: keycloak
+description: Keycloak — open-source identity and access management server (OIDC, OAuth 2.0, SAML) for adding SSO, federation, and user management to apps.
+domain: stack
+category: auth
+tags: [auth, iam, sso, oidc, oauth2, saml, self-hosted, identity-provider]
+official_sources:
+  - https://www.keycloak.org/documentation
+  - https://github.com/keycloak/keycloak
+verified: 2026-06-16
+---
+
+# Keycloak
+
+## Overview
+Keycloak is open-source Identity and Access Management for modern applications and services. It lets you add authentication and secure services with minimal effort, so you don't store users or write login flows yourself. It is an identity provider speaking OpenID Connect, OAuth 2.0, and SAML, with built-in SSO, identity brokering, and user federation. Read this when you need a self-hosted IAM/IdP.
+
+## Official sources
+- Docs: https://www.keycloak.org/documentation
+- Repo: https://github.com/keycloak/keycloak
+- Install / download: https://www.keycloak.org/getting-started/getting-started-docker
+
+## Install / setup
+```bash
+docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.6.3 start-dev
+```
+(Verbatim from the official Docker getting-started page. `start-dev` runs Keycloak in development mode and creates an initial admin user `admin`/`admin`. Do not use `start-dev` in production.)
+
+## Core concepts
+- Realm: an isolated tenant that owns its own users, clients, roles, and configuration; the `master` realm is admin-only.
+- Client: an application or service registered with Keycloak that requests authentication (confidential or public).
+- Protocols: Keycloak speaks OpenID Connect, OAuth 2.0, and SAML so standard apps can integrate without custom code.
+- Roles & groups: authorization is modeled with realm/client roles assigned directly or via groups.
+- Identity brokering & federation: Keycloak can delegate login to external IdPs (social, SAML, OIDC) and federate users from LDAP/Active Directory.
+- Tokens: after login Keycloak issues ID, access, and refresh tokens (JWTs) that apps validate.
+
+## Best practices
+- Never run `start-dev` in production — it uses dev defaults; use `start` with a production database and proper hostname/TLS config (https://www.keycloak.org/server/configuration-production).
+- Create a dedicated realm per environment/tenant; don't put applications in the `master` realm.
+- Use confidential clients with a secret for server-side apps and public clients with PKCE for SPAs/native apps.
+- Front Keycloak with TLS and set the correct hostname so issued token issuer URLs are valid.
+
+## Common pitfalls
+- Using `start-dev` or the bootstrap admin credentials in production → insecure defaults and no proper persistence; switch to `start` and a real DB.
+- Putting client apps in the `master` realm → mixes admin and app users; create a separate realm.
+- Public client without PKCE for browser/native apps → vulnerable to code interception; enable PKCE.
+
+## Examples
+```bash
+# Start a development server (creates admin/admin), then visit http://localhost:8080
+docker run -p 127.0.0.1:8080:8080 \
+  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
+  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
+  quay.io/keycloak/keycloak:26.6.3 start-dev
+```
+
+## Further reading
+- https://www.keycloak.org/guides — task-oriented guides (server, securing apps, operator)
+- https://www.keycloak.org/server/configuration-production — production configuration
+
+## Related skills
+- ../auth0 — hosted alternative to a self-managed IdP
+- ../authjs — JS/TS app library that can use Keycloak as an OIDC provider