@claude-code-mastery/starter-kit 1.2.1 → 1.3.1

package/.claude/skills/accessibility/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: accessibility
+description: Accessibility and screen-reader support, built in from the start rather than bolted on. Claude treats a11y as an afterthought and reaches for clickable divs, skips alt text and labels, and removes focus rings. Use when building or editing any UI, page, or interactive component. Covers semantic HTML before ARIA, real buttons and links, accessible names, keyboard operability and focus management, headings and landmarks, contrast and motion, and how to actually test it. Most of it is free if you use the right element.
+when_to_use: |
+  - Building or editing any UI, page, form, or interactive component, treat a11y as a default, not a later pass
+  - Anything with buttons, links, forms, modals, menus, tabs, or icons
+  - About to use a clickable `<div>`, skip `alt` or a label, remove a focus outline, or disable zoom
+  - Dynamic content that updates without a full page load (toasts, async results, SPA route changes)
+  - Do NOT skip this for "internal" tools, accessibility is not optional there either
+---
+
+# Accessibility: Build It In, Don't Bolt It On
+
+Accessibility is a current best practice, not a nice-to-have for later, and most of it costs nothing if you use the right elements from the start. Claude's defaults (clickable divs, missing labels, removed focus rings) are exactly what breaks screen readers and keyboards, and they're expensive to retrofit. Treat it as part of the build, like you would performance.
+
+## Semantic HTML first, ARIA last
+
+The native element gives you keyboard support, focus, the correct role, and screen-reader semantics for free. The first rule of ARIA is don't use ARIA when a native element already does the job, and bad ARIA is worse than none. Reach for the real element before reaching for a role.
+
+## Use the real element, not a clickable div
+
+`<button>` for actions (submit, toggle, open a menu), `<a href>` for navigation (it goes somewhere). A `<div onclick>` is none of these: it isn't focusable, doesn't fire on Enter or Space, and is announced as nothing. Recreating a button with `role`, `tabindex`, and keydown handlers is work you will get subtly wrong, the native `<button>` is already all of that. Same for `<nav>`, `<ul>`, `<table>`, `<label>`, `<input>`, use them.
+
+## Every interactive thing needs an accessible name
+
+- **Images:** a descriptive `alt`, or `alt=""` for purely decorative ones so screen readers skip them. Never omit the attribute, that makes the reader announce the filename.
+- **Form fields:** a real `<label>` tied to the input (`for`/`id` or wrapping). A `placeholder` is not a label, it vanishes on input, has poor contrast, and isn't reliably announced.
+- **Icon-only buttons** (hamburger, close X, search): an `aria-label`. This is the single most common missing name, an icon button with no text is silent to a screen reader.
+
+## Keyboard and focus
+
+Everything interactive must be reachable and operable by keyboard in a sensible order. Two things Claude breaks constantly:
+
+- **Never remove the focus ring** (`outline: none`) without replacing it, a keyboard user then can't see where they are. Use `:focus-visible` to show a clear ring for keyboard users without it appearing on mouse clicks.
+- **Manage focus on modals and route changes.** Prefer the native `<dialog>` with `showModal()`, it traps focus, closes on Escape, and restores focus to the trigger. If you build your own, replicate all of that. In a SPA, move focus to the new view's heading on navigation, or a screen-reader user never learns the page changed.
+
+## Structure: headings, landmarks, and sectioning
+
+Headings are the outline that screen readers and search engines navigate by, so get them right:
+
+- **One `<h1>` per page**, the page's title. Then `<h2>`/`<h3>` in order, don't skip levels for visual size (style with CSS, keep the order logical).
+- **Use real heading elements, not a styled `<span>` or `<div>`.** Something that just looks like a heading carries no meaning, assistive tech and crawlers don't see a heading at all. And don't wrap the heading text in a `<span>` to style it, style the heading element (or a class on it) directly, the heading's content should be the heading text.
+- **Keep a heading next to the content it labels.** A heading describes the block that immediately follows it, so the heading and its paragraph belong together, heading first, grouped. A heading stranded away from its content, or with unrelated markup wedged between, loses the relationship that gives it meaning to both a reader and a crawler.
+
+Then use the document-sectioning elements for what they mean, not as styled `<div>`s, so assistive tech can understand and navigate the page:
+
+- **Landmarks** wrap the page's regions: `<header>` (banner), `<nav>`, `<main>` (one per page), `<aside>` (complementary), `<footer>` (contentinfo). Add a skip-to-content link to `<main>` so keyboard and screen-reader users can jump straight in instead of tabbing through the nav every time.
+- **`<article>`** for a self-contained piece that stands on its own or repeats, a post, comment, card, product. It tells assistive tech "this is one discrete item," which is what makes a feed or list navigable.
+- **`<section>`** for a thematic group, but only when it has a heading. A bare `<section>` is not a landmark and adds nothing, it becomes a navigable region only when you give it an accessible name (`aria-labelledby` pointing at its heading). If it's just a styling wrapper with no heading, use a `<div>`.
+
+The rule both ways: reach for the element that describes the content, but overusing `<section>` and `<article>` as generic wrappers is as unhelpful as never using them.
+
+## Don't lock people out: contrast, color, zoom, motion
+
+- Text contrast at least 4.5:1 (3:1 for large text), and never convey meaning by color alone, pair it with text, an icon, or a pattern.
+- Never disable zoom (`user-scalable=no` / `maximum-scale=1`), see responsive-css.
+- Respect `prefers-reduced-motion` for animations and parallax.
+- Announce dynamic changes (toasts, async results, validation) with an `aria-live` region, or they happen silently for a screen reader.
+
+## Test it, don't assume it
+
+Do a keyboard-only pass (Tab through everything, operate it with Enter/Space/Escape, watch the focus ring) and run an actual screen reader on the key flows. Automated tools (axe, Lighthouse) are worth running but catch only a fraction of issues, the keyboard and screen-reader pass is what finds the rest.
+
+---
+
+This skill is built to grow. Add a rule when a real accessibility failure has a stable, defensible fix.

package/.claude/skills/api-conventions/SKILL.md

@@ -31,4 +31,4 @@ Every service is three layers, one direction: `server.ts` → `handlers/` → `a
 - A service owns its domain and is reached through its interface. A package does not reach into another package's internals or its data. Call the owning service.
 - Code two services both need is hoisted to a shared layer, never imported sideways from a sibling.
 
-The test: routes in `server.ts` read request-in, handler-call, response-out. Logic sits in `handlers/`. Anything that leaves the process goes through `adapters/`, and the data adapter is StrictDB.
+The test: routes in `server.ts` read request-in, handler-call, response-out. Logic sits in `handlers/`. Anything that leaves the process goes through `adapters/`, and the data adapter uses StrictDB if installed, the native driver otherwise.

package/.claude/skills/code-review/references/project-checks.md

@@ -13,7 +13,7 @@ Apply these to every diff. They are this codebase's hard rules. A violation is C
 ## Data access (lives in the adapter layer)
 
 - [ ] **No Mongoose.** Flag any Mongoose import, model, or schema.
-- [ ] **Data access goes through the adapter.** Flag raw collection access outside `adapters/`. Inside the adapter, StrictDB if installed else the native driver, the driver choice isn't a violation; Mongoose and raw access in feature code are.
+- [ ] **Data access goes through the adapter.** Flag raw collection access outside `adapters/`. Inside the adapter, StrictDB is preferred when installed and the native driver is fine when it isn't, the driver choice is not a violation; Mongoose and raw access in feature code are.
 - [ ] **One shared `MongoClient`.** Flag `new MongoClient` inside a request handler or per-call path; the client is created once and reused. In serverless, it must be at module scope, not inside the handler.
 - [ ] **No `_id` in a write body.** Flag any update or upsert payload containing `_id`; it belongs in the filter.
 - [ ] **Type-safe `_id`.** Flag a query comparing a string against an `ObjectId` `_id`; it silently returns nothing. For `$in`, every element must be converted.

package/.claude/skills/create-service/SKILL.md

@@ -24,7 +24,7 @@ server.ts      routes only, NEVER business logic
 handlers/      business logic, one file per domain
    │
    ▼
-adapters/      external wrappers (database via StrictDB, APIs, queues)
+adapters/      external wrappers (database via StrictDB or native driver, APIs, queues)
 ```
 
 This matches the `api-conventions` skill. Keep them in sync: if the layering changes, change both.
@@ -39,7 +39,7 @@ packages/{name}/
 │   │   └── index.ts
 │   ├── adapters/          # external wrappers
 │   │   ├── index.ts
-│   │   └── db.ts          # StrictDB data adapter (the only place the driver lives)
+│   │   └── db.ts          # data adapter — StrictDB or native driver, the only place the driver lives
 │   └── types.ts           # TypeScript types
 ├── tests/
 │   └── handlers.test.ts
@@ -121,7 +121,7 @@ app.listen(PORT, () => {
 The data adapter is the only place the driver is touched. Use StrictDB if it's installed, otherwise the native MongoDB driver. Never Mongoose. Handlers import this, never the driver.
 
 ```typescript
-// Wire to your StrictDB package/API. This is the data boundary for the service.
+// Wire to StrictDB if installed, otherwise the native MongoDB driver. The data boundary for the service.
 // Rules enforced here (see the mongodb-rules skill):
 //   - StrictDB if installed, else the native driver; never Mongoose
 //   - reads are aggregation pipelines, not find()

package/.claude/skills/css-structure/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: css-structure
+description: Where CSS should live. Claude defaults to dumping a giant <style> block or scattering style="..." attributes instead of putting styles in a .css file and linking it. Use when building or editing a web page or component, or whenever about to write a style attribute or an embedded style block. Covers defaulting to an external stylesheet, why inline style attributes are a trap, and the few cases where inline is actually correct (dynamic values via custom properties, critical CSS, single-file artifacts, email).
+when_to_use: |
+  - Building or editing a web page or component and deciding where the styles go
+  - About to write a `style="..."` attribute, a large embedded `<style>` block, or a per-element inline style object in JSX
+  - Reviewing or refactoring how a project's CSS is organized
+  - Do NOT use for native mobile styling or non-web code
+---
+
+# CSS Structure: Where Styles Live
+
+Claude's default is to pour everything into one HTML file, either a big `<style>` block or `style="..."` attributes on each element. In a real project that's the wrong default. Styles belong in a `.css` file.
+
+## Default: an external stylesheet, linked
+
+When building a page or component in a project that has a file structure, put the CSS in its own file and link it:
+
+```html
+<link rel="stylesheet" href="/styles/app.css" />
+```
+
+It's reusable across pages, cached separately by the browser, keeps the markup readable, and lets the cascade and media queries work. This is the default to reach for instead of an inline block, not the thing to do only when asked.
+
+## Avoid scattered inline `style="..."` attributes
+
+Inline style attributes are the worst of the three options, for concrete reasons, not style preference:
+
+- **They can't be responsive or interactive.** No media queries, no `:hover`/`:focus`, no `::before`/`::after`, no keyframes. An inline-styled element literally cannot be made responsive (see responsive-css), so it fights everything that skill is about.
+- **They have the highest specificity short of `!important`.** Overriding an inline style later means escalating to `!important`, which starts a specificity war.
+- **No reuse, no caching, noisy markup.** The same declarations get repeated on every element, ship on every page load, and bury the HTML structure.
+
+## A single `<style>` block is fine for a deliberately single-file deliverable
+
+Don't over-correct into "never embed." One `<style>` block in the head is the right call for a genuinely single-file thing: a standalone demo, a self-contained artifact, a quick reproduction. Email HTML is the opposite special case, mail clients strip `<style>` and external sheets, so email actually requires inline attributes. The rule is about defaults: the moment there's a project with folders, move the CSS into a file rather than defaulting to one big file because it's easier to paste.
+
+## When inline is actually correct: dynamic and critical
+
+Two cases where a value belongs inline:
+
+- **Runtime values.** A width, transform, or color computed from state (a progress bar, a drag position) can't live in a static sheet. Set a CSS custom property inline and consume it in the stylesheet, so only the value is inline and the styling stays in CSS:
+```html
+<div class="bar" style="--progress: 73%"></div>
+```
+```css
+.bar::after { width: var(--progress); }
+```
+- **Critical CSS.** Deliberately inlining the above-the-fold styles in `<head>` for first paint, then loading the rest, is a real performance technique, not the same mistake as scattering `style=`. Which styles are critical and what to defer is a first-paint decision, see web-performance.
+
+## In React/JSX
+
+Same split: dynamic values through `style={{}}` or a CSS variable, everything static in CSS Modules, a stylesheet, or utility classes (Tailwind). A large inline style object hand-written on every element is the JSX version of the same anti-pattern.
+
+---
+
+This skill is built to grow. Add a rule when a real styling-location decision has a stable, defensible answer.

package/.claude/skills/dev-pitfalls/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: dev-pitfalls
+description: Common pitfalls that are slow to troubleshoot and that tend to get "fixed" by going in circles, because the error message points nowhere near the actual cause. Use before and during git, project, and WSL work, checking a repo is initialized and node_modules is ignored, putting WSL projects on the right filesystem, opening a browser from WSL for auth, normalizing line endings, and matching import case. Check the layer here first instead of debugging the wrong one.
+when_to_use: |
+  - Starting git work in a directory (is it even a repo? is node_modules ignored?)
+  - A WSL project is slow, hot reload / file watchers miss changes, or chmod / ssh permissions misbehave
+  - A CLI needs to open a browser from WSL for an OAuth / SSO (Okta, Entra) login
+  - CRLF/LF symptoms: `^M`, `bad interpreter: /bin/bash^M`, a deploy failing with "expected string, got object" or unmarshal errors, YAML or shell scripts breaking on one platform only
+  - An import works locally but fails in CI (case sensitivity)
+  - Writing or editing Kubernetes, Helm, Terraform, or other structured config where a field name or path could be guessed wrong (`service.port` vs `spec.ports[0].port`)
+  - A cryptic error whose message misleads: `ENOSPC` (really the file-watcher limit), `exec format error` (really CPU arch mismatch), `dubious ownership` (really a UID mismatch), `EADDRINUSE` (really a leftover process), heap OOM
+  - Do NOT use for application-level config or secrets, this is dev-machine, repo, and project-state hygiene
+---
+
+# Common Dev Pitfalls (check the layer before debugging it)
+
+These cost hours because the symptom points at the wrong thing, and they're easy to "fix" by going in circles. When something matches below, check the cause here before debugging the code.
+
+## Check project state before acting
+
+Claude's frequent miss is assuming project state instead of verifying it. Two checks, stated plainly to the user:
+
+- **Is it even a git repo?** Before staging, committing, or diffing, confirm the repo exists (`git rev-parse --is-inside-work-tree`). If it doesn't, say so directly, "this directory isn't a git repository yet, run `git init` first", rather than running git commands that fail confusingly or silently acting on a parent repo.
+- **Is `node_modules` ignored?** Before the first commit, confirm `.gitignore` exists and lists `node_modules/`. Create `.gitignore` BEFORE `npm install` so it is never tracked. If it isn't ignored yet, say so before anything gets committed.
+
+**`.gitignore` only ignores UNtracked files.** If `node_modules` (or `.env`, or build output) was already committed, adding it to `.gitignore` changes nothing, git keeps tracking it, and this is a classic "my .gitignore isn't working" loop. Untrack it, then commit:
+
+```bash
+git rm -r --cached node_modules
+git commit -m "Stop tracking node_modules"
+```
+
+Confirm a rule actually bites with `git check-ignore -v node_modules`. Committed `node_modules` bloats the repo and breaks CI, its platform-specific compiled binaries fail on Linux runners. Same fix for anything that "won't stop showing up" after you ignored it.
+
+## WSL: put the project on the Linux filesystem, not /mnt/c
+
+The single biggest WSL pitfall, and Claude rarely thinks to check it. A project under `/mnt/c` (any Windows drive) is reached from Linux over a 9P bridge, so:
+
+- file operations run 10-100x slower, `npm install`, `git status`, and test runs crawl
+- `inotify` is flaky across the bridge, so file watchers fire intermittently, hot reload and test watchers "work randomly" then silently stop, which becomes a circular debugging session if you chase it as a config problem
+- Linux permission bits are only emulated, `chmod +x` can silently fail and ssh rejects keys as "bad permissions"
+- editor integration breaks: Claude often can't see your active selection or the code you've highlighted, so it's working blind on what you're pointing at
+
+Keep repos on the Linux side (`~/projects/...`, `~/code/...`) and open them with VS Code Remote-WSL. If a project sits on `/mnt/c` and shows any of the above, that location IS the bug, move it:
+
+```bash
+mv /mnt/c/Users/<you>/projects/my-app ~/projects/
+```
+
+Use `/mnt/c` only when a file genuinely needs to live on the Windows side for a Windows GUI app.
+
+**Don't chase this through settings.** The circular trap is treating intermittent watchers or a blind editor as a config problem and tweaking watcher polling, exclude globs, and a pile of VS Code settings. On a Windows machine showing these symptoms, check the path FIRST. If it's `/mnt/c`, the answer is almost always "you're on the Windows filesystem, open the folder in WSL (Remote-WSL) and move it to `~/`", say that before suggesting a single setting.
+
+## Opening a browser from WSL (auth / SSO)
+
+A CLI runs an OAuth/SSO login, tries to open a browser from WSL, and either nothing opens or it opens a browser that isn't signed into the corporate IdP (Okta, Entra), so the login fails. Why your own browser matters: the SSO session lives in your real Chrome profile, a fresh or other browser context doesn't have it.
+
+**Default to launching your real Chrome** via an executable shim on PATH (`~/.local/bin/chrome`, `chmod +x`):
+
+```sh
+#!/bin/sh
+exec "/mnt/c/Program Files/Google/Chrome/Application/chrome.exe" "$@"
+```
+
+```bash
+export BROWSER=chrome   # in ~/.bashrc
+```
+
+That opens your actual browser, your bookmarks and your live Okta session, which is what you want about 99% of the time.
+
+`wslview` (from the `wslu` package) is the alternative, but in a corporate setup the browser it routes to may not carry your IdP session, so the login page loads unauthenticated. Offer it as a fallback, not the default. If neither is configured, ask the user which they want (own Chrome vs wslview) before wiring it in.
+
+**Check `$BROWSER` hasn't been hijacked.** `BROWSER` has two unrelated meanings: the desktop convention (which browser opens URLs, used by auth flows) and Playwright's test-runner convention, where `BROWSER=chromium` selects which browser to run tests in. If a Playwright project exports `BROWSER=chromium` globally (in `~/.bashrc` or a sourced `.env`) instead of setting it inline on the test command, it overrides your desktop browser, so auth flows either fail outright (no executable named `chromium` on PATH) or open Playwright's bundled Chromium, a clean isolated context with none of your sessions. Same class of problem as VS Code's built-in browser. Diagnose with `echo $BROWSER`: if it shows `chromium`, `firefox`, or `webkit`, that's the hijack. Keep `BROWSER=chrome` (your shim) for desktop and auth, and scope Playwright's to the command only: `BROWSER=chromium npx playwright test`.
+
+**Use a shim, not a bash `alias`.** An alias exists only in interactive shells, so when a program execs `$BROWSER` it never sees the alias and the open silently fails, which is the exact programmatic case auth needs.
+
+## Line endings: LF everywhere (CRLF is the silent killer)
+
+Windows CRLF breaks things in ways that take forever to trace: YAML parsing wrong, shell scripts dying with `bad interpreter: /bin/bash^M`, Docker entrypoints not executing, diffs showing every line changed when nothing did. YAML and `.sh` scripts are the usual victims because a stray `\r` rides along invisibly.
+
+**The symptom that wastes the most time: a deploy failing with a type error.** A Kubernetes apply (or any YAML-driven deploy) that throws "expected a string, got a map/object" or "cannot unmarshal object into ... string" usually has nothing wrong with the field it names. A stray `\r` from CRLF has broken how the parser reads the value, so a scalar gets read as a structure. The manifest looks correct because the `\r` is invisible, which is exactly why this eats hours: the error points at the data, not the line ending. Before debugging the field, the schema, or the value, check the file's line endings, normalize to LF and re-apply.
+
+Make the repo LF-only with `.gitattributes` at the root:
+
+```
+* text=auto eol=lf
+```
+
+`text=auto` lets git detect text vs binary (binaries untouched); `eol=lf` forces LF in both the committed blob and the working tree, regardless of anyone's local `core.autocrlf`. For a repo that already committed CRLF, the attribute alone won't rewrite it, renormalize once: `git add --renormalize . && git commit -m "Normalize line endings to LF"`. Set `.editorconfig` `end_of_line = lf` so files are authored as LF too.
+
+## Case sensitivity: Linux is strict, Windows and macOS usually aren't
+
+`import './Button'` resolves on a case-insensitive Windows/macOS filesystem even when the file is `button.tsx`, then fails on Linux and CI with "module not found." Match import casing to the real filename exactly. The same trap hits two files differing only in case (`README.md` vs `Readme.md`): they coexist on Linux but collide or shadow each other on Windows/macOS.
+
+## Don't guess config field names, look them up (especially Kubernetes)
+
+Structured config (Kubernetes, Helm, Terraform, cloud CLIs) is a typed, nested schema of objects and arrays, not flat `KEY=VALUE`. Guessing a field path is how an hour disappears into `service.port` vs `spec.ports[0].port`. The exact path is one command away, so query it instead of guessing.
+
+- **`kubectl explain <resource>.<path>`** returns the real schema, including whether a field is an object or an array. `kubectl explain service.spec.ports` shows `ports` is a list, so the value lives at `spec.ports[0].port`, not `spec.port`. Add `--recursive` for the full nested tree.
+- **`kubectl get <resource> <name> -o yaml`** shows the actual structure and values of a live object. Read the path off that, then pull a value precisely with `-o jsonpath='{.spec.ports[0].port}'`.
+- **`KEY=VALUE` is not how Kubernetes models things.** Env vars are a list of objects, `env: [{name: FOO, value: bar}]`, not a map `env: {FOO: bar}`. Ports, containers, and volumes are arrays too (`spec.containers[0].image`). Flat-config instincts break here.
+- **Helm values are chart-specific.** `service.port` can be valid in one chart's `values.yaml` and meaningless in another, that structure is defined by the chart, not by Kubernetes. Run `helm show values <chart>` and read the real keys instead of carrying an assumed path between charts.
+
+General rule: when a tool ships an introspection command (`kubectl explain`, `kubectl get -o yaml`, `helm show values`, `terraform state show`, `aws ... describe-*`, `gh api`), use it to get the exact names the first time. A two-second lookup beats an hour on a path that "looked right."
+
+## Errors that lie about their cause
+
+The worst time-sinks are errors whose message points at the wrong thing, so you debug what the text says for hours. When you see one of these, check the real cause first.
+
+- **`ENOSPC: no space left on device`** from a dev server, `npm start`, Vite, nodemon, or VS Code is almost never disk space. It's the Linux inotify file-watcher limit (default ~8192), exhausted by a large project's file count. Confirm disk is fine with `df -h`, check the limit with `cat /proc/sys/fs/inotify/max_user_watches`, then raise it: `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`. Inside a container, set `CHOKIDAR_USEPOLLING=true` instead.
+- **`exec format error`** (`exec /entrypoint.sh: exec format error`, or `standard_init_linux.go: ... exec format error`) means the binary's CPU architecture doesn't match the host: an arm64 image on an amd64 host or the reverse. Common now that dev laptops are ARM (Apple Silicon) while prod or CI is x86 (or ARM Graviton). Image metadata can claim the right arch while the binary inside doesn't, so trust `file <binary>` run inside the container over `docker inspect`. Fix: pull/run with `--platform linux/amd64`, or build multi-arch with `docker buildx build --platform linux/amd64,linux/arm64`. Second possible cause: CRLF in the entrypoint script (see line endings above), check that too.
+- **`fatal: detected dubious ownership in repository`** is a UID mismatch, not corruption: the repo files are owned by a different user than the one running git. Classic on `/mnt/c` (Windows files look root-owned to WSL) and in containers (host UID does not match container UID). Git offers the band-aid (`git config --global --add safe.directory <path>`), but the durable fix is matching ownership: `chown -R $(whoami) <repo>`, moving the repo to `~/`, or running the container with `--user $(id -u):$(id -g)`.
+- **`EADDRINUSE: address already in use`** is a leftover process holding the port, usually a dev server that didn't exit. Find and kill it: `lsof -t -i:3000 | xargs kill`, or use another port. Don't reconfigure the app.
+- **`JavaScript heap out of memory`** is V8's default heap ceiling, not always a leak. For a heavy build, raise it: `NODE_OPTIONS=--max-old-space-size=4096`. If it recurs at low memory, then look for a real leak.
+
+---
+
+This skill is built to grow. Each new pitfall is another short section: the symptom you actually see, the cause, and the fix that ends the loop.

package/.claude/skills/docker/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: docker
+description: Production Docker best practices for writing Dockerfiles, Compose files, and Swarm stacks. Use whenever creating or editing a Dockerfile, a docker-compose / compose.yaml, or a stack file, or building and optimizing an image. Fixes the handful of things Claude reliably gets wrong: multi-stage builds, layer-cache ordering, exec-form ENTRYPOINT for correct signals and exit codes, init:true, keeping secrets and env out of the image, non-root users, and healthchecks. From production, not defaults.
+when_to_use: |
+  - Writing or editing a Dockerfile, a Compose file, or a Swarm stack file
+  - Building, slimming, or speeding up an image
+  - Debugging containers that won't stop gracefully, leave zombie processes, or ignore SIGTERM
+  - Deciding how config, env, and secrets reach a container
+  - Do NOT use for orchestration choices unrelated to packaging (cluster sizing, cloud provider selection)
+---
+
+# Docker: Production Image and Compose Rules
+
+From production, not defaults. Claude's Dockerfiles tend to be wrong in the same few ways. Fix them here.
+
+## Dockerfile
+
+- **Multi-stage builds, always.** Build in a stage that has the compilers and dev dependencies, then `COPY --from=build` only the artifacts into a slim runtime stage. The runtime image carries no build tools, which cuts size hard (a real build went from ~2GB to ~200MB) and removes a pile of CVEs.
+```dockerfile
+FROM node:22 AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-slim AS runtime
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY --from=build /app/dist ./dist
+USER node
+ENTRYPOINT ["node", "dist/server.js"]
+```
+
+- **Order layers by how often they change: stable first, source last.** Docker caches each layer and rebuilds every layer after the first one whose inputs changed. So copy the dependency manifest and install deps BEFORE copying source: `COPY package*.json ./` then `RUN npm ci` then `COPY . .`. Copy source first and a one-line code change reinstalls every dependency, every build.
+
+- **The runtime command is `ENTRYPOINT`/`CMD` in exec form, never `RUN`.** `RUN` executes at build time; the container's process belongs in `ENTRYPOINT ["node","server.js"]` (a JSON array). Use exec form, not shell form (`ENTRYPOINT node server.js`): shell form runs your app under `/bin/sh -c`, so `sh` is PID 1, it swallows `SIGTERM`, and your app never shuts down gracefully (Docker waits out the grace period then SIGKILLs it) and its exit code is lost. Exec form makes your process PID 1 so signals and exit codes propagate. `ENTRYPOINT` for the executable, `CMD` for default args.
+
+- **Pin base image versions.** `FROM node:22.3.0-slim`, not `node:latest`. `latest` makes builds non-reproducible and shifts under you silently. Pin a tag (or a digest for full reproducibility), and expose it as an `ARG` so it's easy to bump deliberately.
+
+- **Add a `.dockerignore`.** Exclude `node_modules`, `.git`, `.env`, `dist`, and local junk. Without it the whole directory ships as build context (slow), busts the cache on unrelated changes, and can bake a stale `node_modules` or a secret file into the image.
+
+- **Run as non-root.** Containers run as root by default. Add a `USER` (for example `USER node`) before the entrypoint so a container escape isn't root on the host.
+
+- **Add a `HEALTHCHECK`.** Swarm and Compose use it to know a container is actually ready, which is what makes rolling updates and automatic rollback work. Without it, "running" only means the process started, not that it serves traffic.
+
+- **Combine and clean in one `RUN`.** `apt-get update && apt-get install -y ... && rm -rf /var/lib/apt/lists/*` in a single layer. A separate `update` layer goes stale behind the cache, and the cleanup only shrinks the image if it happens in the same layer that added the files.
+
+## Compose and Swarm
+
+- **`init: true` on every service.** The one always missed. It runs a tiny init (tini) as PID 1 that forwards signals to your process and reaps zombie children. Without it, signal handling and zombie reaping become your app's problem and `docker stop` often hangs to the timeout. Pair it with an exec-form ENTRYPOINT.
+
+- **Set resource `limits` AND `reservations`.** Reservations make the scheduler place the container only where the resources exist; limits cap it so a runaway container can't take down the node. Both, not one.
+
+- **Configure rolling updates and rollback.** `update_config` with `parallelism: 1`, a `delay`, `order: stop-first` (or `start-first` for blue-green), and `failure_action: rollback`. Combined with a HEALTHCHECK, a bad deploy rolls itself back instead of taking the service down.
+
+- **Reference services by name, never by IP.** Container IPs change on every restart, scale, and update. Use the service name and let Docker DNS resolve it (`backend-service:8080`). A hardcoded IP is a guaranteed future outage.
+
+- **Substitute env with defaults.** `replicas: ${NGINX_REPLICAS:-2}` and `image: registry/app:${BUILD_VERSION:-latest}` keep one file working across environments through `.env`.
+
+## Secrets and config
+
+- **Never bake secrets into the image.** `ARG` and `ENV` values are stored in image layers and show up in `docker history`, so a secret written into the Dockerfile is a leaked secret. Use BuildKit build secrets (`RUN --mount=type=secret,id=...`) for build time, and Docker secrets (mounted at `/run/secrets/<name>`) or runtime env for run time. Docker secrets are encrypted at rest, never appear in `docker inspect`, and are scoped to the services that mount them.
+
+- **Secrets for sensitive, configs for the rest.** Docker `secret` for certs, keys, and passwords (encrypted); Docker `config` for non-sensitive files like an IP blocklist (not encrypted, but versioned and injected the same way). Neither goes in the image, both are injected at deploy.
+
+- **Log to stdout/stderr, not to files inside the container.** Write to `/dev/stdout` and `/dev/stderr` so Docker's logging driver and your aggregator collect them. Logging to a file inside the container hides the output and fills the writable layer.
+
+---
+
+This skill is built to grow. Add a rule when a real Dockerfile or stack failure has a stable, defensible fix.

package/.claude/skills/docker-swarm/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: docker-swarm
+description: Production Docker Swarm deployment rules: what changes when a compose file goes from a single node to a multi-node Swarm. Use when writing or reviewing a stack file, a deploy block, an overlay network, or anything deployed with docker stack deploy. Covers the directives Swarm silently ignores, why fixed IPs and bind mounts break, the deploy orchestration block, and the exit-code and healthcheck discipline that Swarm self-healing depends on. Complements the docker skill, which covers writing the image and compose file itself.
+when_to_use: |
+  - Writing or reviewing a stack file or a `deploy:` block, or running `docker stack deploy`
+  - Moving a compose file that works locally onto a multi-node Swarm
+  - A service behaves differently deployed than it did with `docker compose up`
+  - A rolling update hangs, a replica can't get an IP, or a service is "running" but dead
+  - Designing overlay networks, placement, rolling updates, or rollback
+  - Do NOT use for single-node Compose or image building, that is the docker skill
+---
+
+# Docker Swarm: Single Node to Multi-Node
+
+Compose and Swarm read the same file and interpret it differently. The trap is that Swarm fails silently: the stack deploys, containers start, and something just doesn't work the way it did locally. Write the compose file for the multi-node world from day one and the single-node case still works.
+
+## The mental model: a container is a process, not a computer
+
+Swarm tears down and recreates containers constantly, on every update, node failure, scale, and rebalance. The new container has a new ID, a new IP, a new hostname, and a blank filesystem. Treat the container as disposable and keep all state outside it: a database or Redis for sessions, a named volume or object storage for files, env or Docker secrets/configs for configuration, stdout/stderr for logs. The test: if Swarm kills this container right now and starts a new one, does the app work identically? If not, state is leaking into the container.
+
+## Directives Swarm silently ignores
+
+`docker stack deploy` reads these and skips them with no error. If you relied on one locally, you debug for hours before realizing Swarm never read it.
+
+`build` (Swarm only runs pre-built registry images), `container_name` (names collide with replicas), `depends_on` (no startup ordering, services start in parallel), `links`, `restart` (use `deploy.restart_policy`), `networks.ipv4_address` / `ipv6_address`, `network_mode`, `cap_add` / `cap_drop`, `devices`, `tmpfs`, `extra_hosts`, `sysctls`, `security_opt`, `cgroup_parent`, `userns_mode`. Capabilities, sysctls, and security options are set at the engine level on each node instead.
+
+## Directives that change behavior in Swarm
+
+- **`ports`** publish through the routing mesh: the port opens on every node, and traffic to any node is routed to a container wherever it runs. Publish the container port only (`- "61339"`) and let the mesh assign a host port, your reverse proxy reaches the service by name and never needs to know the host port.
+- **`volumes`**: named volumes work everywhere; bind mounts to host paths break the moment a container is scheduled on a different node, because that path doesn't exist there. Use named volumes for data and Docker configs/secrets for files.
+- **`networks`**: Compose defaults to `bridge` (single host). Swarm needs `overlay` (multi-host). A bridge network in a stack means services can't talk across nodes.
+
+## Never hardcode an IP, the service name is the identity
+
+Container IPs change on every restart, scale, and update. The service name is the one thing that never changes; Docker DNS resolves it to wherever the container currently lives. Hardcoding an IP breaks replicas, load balancing, and multi-node, but the worst case bites with a single replica during a routine rolling update: the new container needs an IP the dying old container hasn't released yet, and you can deadlock, the new one waits for the IP, the old one waits to be healthy, the update hangs, and rollback hits the same conflict. Connect by name (`mongodb://mongo:27017/mydb`) and none of it happens. A reverse proxy in the mesh needs a Docker-aware DNS resolver with a short TTL so it re-resolves names, see the nginx skill.
+
+## The deploy block (Swarm-only orchestration)
+
+These keys do nothing in plain Compose (except resource limits) but are what Swarm runs on:
+
+```yaml
+deploy:
+  mode: replicated
+  replicas: 6
+  placement:
+    max_replicas_per_node: 3        # 6 replicas then need 2+ nodes, spreads for HA
+    constraints:
+      - node.role == worker
+  update_config:
+    parallelism: 2
+    delay: 10s
+    order: start-first              # start new before stopping old, or stop-first
+    failure_action: rollback        # bad deploy rolls itself back
+  rollback_config:
+    parallelism: 2
+    delay: 10s
+  restart_policy:
+    condition: on-failure
+    delay: 5s
+    max_attempts: 3
+    window: 120s
+  resources:
+    limits:                         # cap so a runaway container can't starve the node
+      cpus: '0.50'
+      memory: 400M
+    reservations:                   # guarantee, scheduler places only where it fits
+      cpus: '0.20'
+      memory: 150M
+```
+
+## No `depends_on`, so the app must retry
+
+Swarm starts services in parallel with no ordering. The app must connect to its dependencies with retry and exponential backoff rather than assuming the database is up. This is good engineering anyway, databases restart and connections drop in any production system.
+
+## Self-healing depends on you, get exit codes and healthchecks right
+
+Swarm (like Kubernetes) is blind to a service it can't measure. The four failures that actually kill production are the same on both, and both depend entirely on you:
+
+- **Exit codes.** `restart_policy: on-failure` only restarts on a non-zero exit. An app that crashes but calls `exit(0)` is "success" and stays dead. Exit non-zero on failure.
+- **Meaningful healthchecks.** A `/health` that always returns 200 even when the database is down reports healthy while serving errors. The check must verify real dependencies. Without any healthcheck, Swarm treats a hung or deadlocked container as healthy and keeps routing traffic to it.
+- **Warm-up.** Use `start_period` so a slow-starting container isn't killed before it's ready.
+
+Write the healthcheck and set the exit codes; the orchestrator does exactly what you tell it and nothing you don't.
+
+## Overlay network and stack workflow
+
+Pre-create an encrypted overlay, and pick a subnet that won't clash with your cloud VPC or default Docker ranges:
+
+```bash
+docker network create --opt encrypted --attachable --driver overlay \
+  --subnet 172.240.0.0/24 awsnet
+```
+
+Reference it as `external: true` in the stack. Open Swarm ports between nodes: 2377/tcp (management), 7946/tcp+udp (node comms), 4789/udp (overlay). Note that `--opt encrypted` can fight cloud NAT, use internal VPC IPs when you enable it. Then build and push to a registry first (Swarm won't build), and deploy:
+
+```bash
+docker stack deploy -c docker-compose.yaml mystack
+docker stack services mystack
+docker service ps mystack_app --no-trunc   # full error text when a task won't start
+```
+
+---
+
+This skill is built to grow. Add a rule when a real Swarm deployment surprise has a stable, defensible fix.

package/.claude/skills/mdd-workflow/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: mdd-workflow
+description: Use in any project that uses MDD (a `.mdd/` directory exists) when editing source code, building a feature, fixing a bug, requesting an audit, or editing `.mdd/docs` files. Keeps feature docs in sync the moment their controlled source files change, recommends the `/mdd` workflow for substantial tasks, and conforms to `.mdd` doc conventions. Installed globally, so it self-gates: it does nothing in projects that don't use MDD.
+when_to_use: |
+  - About to edit source code in a project that has a `.mdd/` directory (drift check)
+  - User asks for a feature, a real bug fix, a meaningful refactor, or an audit (recommend `/mdd`)
+  - Editing a `.mdd/docs/*.md` file directly, outside a `/mdd` run (conventions)
+  - Do NOT act at all if the project has no `.mdd/` directory and no `/mdd` command — stay silent
+allowed-tools: "Read, Edit, Grep, Glob, Bash"
+---
+
+# MDD Workflow Companion
+
+This skill complements the `/mdd` command. The command **owns** the workflow; this skill keeps things honest **between** command runs. Its single most valuable job is preventing documentation drift the moment it would happen, before it accumulates.
+
+## Step 1 — Gate (do this first, every time)
+
+Act only if **this project uses MDD**. Check for any of:
+- a `.mdd/` directory in the project root, or
+- a resolvable `/mdd` command (`.claude/mdd/`, `~/.claude/mdd/`, `.claude/commands/mdd.md`).
+
+If none exist, **stop silently**. Do nothing, say nothing, never mention MDD. This skill is installed globally and will activate in projects that have never adopted MDD; in those projects it must be invisible.
+
+Two hard rules that hold for everything below:
+- **Never run the workflow yourself.** No branching, no `.mdd/` bootstrap, no phase execution. You recommend `/mdd` and let the user confirm. The command performs all side effects.
+- **Silence is the default.** When you activate but there is nothing controlled to sync and nothing substantial to recommend, produce no MDD output at all. Never narrate the gate or the check.
+
+## Step 2 — Job 1: Prevent doc drift when editing controlled code (priority)
+
+Feature docs declare the source they own in frontmatter (`source_files`, plus `routes` and `models`). When that source is edited outside a `/mdd` run, the doc silently goes stale. Catch it at the edit, not weeks later in `/mdd scan`.
+
+When you are about to edit (or have just edited) a source file in an MDD project:
+
+1. **Cheap controlled-file check.** Grep `.mdd/docs/*.md` for the file's path in `source_files` (and `routes`/`models` if the change adds or alters a route or model):
+   ```bash
+   grep -rl "<relative/path/to/file>" .mdd/docs/*.md
+   ```
+   No match → the file is not controlled. Stay silent and proceed normally.
+
+2. **If a doc controls the file**, name it and keep it in sync:
+   - Read `.mdd/docs/00-frontmatter-spec.md` first so any frontmatter edit conforms to the schema.
+   - Make the **lightweight, factual** updates inline: bump `last_synced` to today; add a new endpoint to `routes`; add a new model to `models`; append a genuinely new defect to `known_issues` (append-only — never remove entries).
+   - Tell the user in one line:
+     `📝 Edited <file>, controlled by .mdd/docs/<id>.md — synced last_synced and routes.`
+   - **If the change is structural** (behavior, business rules, contracts, or data flow changed, not just a field), don't try to re-derive the doc body yourself. Recommend the command that does a full resync:
+     `This change affects how <id> behaves. Run \`/mdd update <id>\` (or \`/mdd audit\`) for a full doc resync.`
+
+3. **If the user is mid-flow and declines the sync**, don't block their work. Note it once so it isn't lost:
+   `Leaving .mdd/docs/<id>.md unsynced — \`/mdd scan\` will flag it later.`
+
+This is real-time and pre-commit, which is precisely what `/mdd status` and `/mdd scan` cannot do (they detect drift retrospectively, from git history, only when invoked). Defer batch and historical drift detection to those commands; this skill catches the single edit as it lands.
+
+## Step 3 — Job 2: Recommend the workflow for substantial tasks (recommend, never run)
+
+When the user asks for work MDD is built for **and** it would genuinely benefit, offer the matching mode once, then defer to the user.
+
+**Nudge when** the task is a new feature, a real (non-trivial) bug, a meaningful refactor, or an audit — and **especially** when it will touch code controlled by an existing feature doc that would drift if done ad-hoc.
+
+**Do not nudge** for typos, formatting, renames, config tweaks, one-liners, or plain questions. Anything too small to deserve a doc is too small to nudge.
+
+The offer is one line, in the user's words, and waits:
+
+> You have MDD installed and this looks like a task that would benefit from it — `/mdd <feature>` documents it first, then builds against the doc. Want me to use it, or just proceed here?
+
+Pick the right invocation: feature → `/mdd <feature-slug>`; bug → `/mdd bug`; audit → `/mdd audit`; existing-doc drift → `/mdd update <id>`.
+
+**One offer per task.** If the user declines or says "just do it," proceed ad-hoc and don't ask again this task. Never run `/mdd` without an explicit yes — but Job 1 still applies, so keep any controlled doc in sync even while working ad-hoc.
+
+## Step 4 — Job 3: Keep `.mdd/docs` conventions correct
+
+When editing a `.mdd/docs/*.md` file directly (not through `/mdd`), read `.mdd/docs/00-frontmatter-spec.md` first and conform:
+- All required frontmatter fields present and correctly typed.
+- `satisfies_contracts` entries use the `from` / `function` / `when` / `status` (`pending`|`done`) / `verified_at` shape — the field is `verified_at`, not `verified`.
+- `relates` is symmetric: if doc A relates B, ensure B relates A.
+- `known_issues` is append-only.
+- Tags are domain concepts, technology names, or feature names — never file paths or generic words.
+
+## What this skill does NOT do
+
+- It does not execute, branch, bootstrap, or run any MDD phase — `/mdd` does that.
+- It does not re-derive doc bodies or do full resyncs — `/mdd update`, `/mdd audit`, and `/mdd scan` do that.
+- It does not act, or mention MDD, in projects that don't use MDD.