start-vibing-stacks 2.14.0 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/commands/feature.md

@@ -1,13 +1,25 @@
+---
+name: feature
+description: Start a new feature with the full workflow (research → plan → implement → test → security → quality → commit → docs).
+version: 1.0.0
+---
+
 # /feature — Start New Feature
 
-Execute in order:
+Always read `.claude/config/active-project.json` first to know the active stack.
+
+Execute in order — do not skip steps. Steps 5–6 have **VETO power** over commit.
 
-1. **Research** → research-web agent (if new tech)
-2. **Plan** → Break into tasks, create TODO list
-3. **Implement** → Write code following stack patterns
-4. **Test** → tester agent (PHPUnit / Vitest / pytest)
-5. **Document** → documenter agent
-6. **Update domains** → domain-updater agent
-7. **Commit** → commit-manager agent
+| # | Step | Agent / Skill |
+|---|---|---|
+| 1 | **Research** (only for new tech / patterns) | `research-web` |
+| 2 | **Plan** — break into tasks, create TODO list | (you, in plan mode) |
+| 3 | **Implement** — follow stack patterns + strict types | (you) |
+| 4 | **Test** — unit + e2e | `tester` |
+| 5 | **Security** — adversarial audit | `security-auditor` (VETO) |
+| 6 | **Quality** — typecheck → lint → test → build | `quality-gate` |
+| 7 | **Commit** — gate-aware, diff-driven message | `commit-manager` |
+| 8 | **Map** — files + commits → domains | `documenter` |
+| 9 | **Wisdom + Last Change** — record learnings, refresh `CLAUDE.md` | `domain-updater` |
 
-Always read `.claude/config/active-project.json` first.
+If `security-auditor` returns CRITICAL/HIGH/MEDIUM, fix before re-running step 5. Steps 8–9 run AFTER push and never before.

package/stacks/_shared/commands/fix.md

@@ -1,9 +1,23 @@
+---
+name: fix
+description: Fix a bug — reproduce, isolate, minimal fix, regression test, security check, commit, record wisdom.
+version: 1.0.0
+---
+
 # /fix — Fix Bug
 
-Execute in order:
+Always read `.claude/config/active-project.json` first.
+
+| # | Step | Agent / Skill |
+|---|---|---|
+| 1 | **Reproduce** — read the error, reproduce locally, isolate the root cause (NOT the symptom) | (you) |
+| 2 | **Failing test first** — write a regression test that proves the bug | `tester` |
+| 3 | **Apply minimal fix** — do not refactor adjacent code in the same commit | (you) |
+| 4 | **Verify** — re-run the regression test + the wider suite | `tester` |
+| 5 | **Security** — only if the bug touched auth / input / secrets / SSRF surface | `security-auditor` (VETO) |
+| 6 | **Quality gate** — typecheck → lint → test → build | `quality-gate` |
+| 7 | **Commit** — `fix(scope): <subject>`, diff-driven body | `commit-manager` |
+| 8 | **Map** — files + commit → domain | `documenter` |
+| 9 | **Wisdom** — append to domain `## Problems & Solutions` (symptom + root cause + fix + prevention + skill ref) | `domain-updater` |
 
-1. **Analyze** → Read error, reproduce, isolate
-2. **Fix** → Apply minimal fix
-3. **Test** → Add regression test (tester agent)
-4. **Document** → Record in domain Problems & Solutions
-5. **Commit** → commit-manager agent
+`domain-updater` deduplicates by symptom/root-cause. If the same bug recurred, it appends a "Recurrence" note instead of a duplicate entry.

package/stacks/_shared/commands/research.md

@@ -1,10 +1,21 @@
+---
+name: research
+description: Research best practices using research-web (MCP-first) with cache lookup before any web call.
+version: 1.0.0
+---
+
 # /research — Research Best Practices
 
-Execute in order:
+Always read `.claude/config/active-project.json` first to know the active stack.
+
+| # | Step | Tool / Skill |
+|---|---|---|
+| 1 | **Cache lookup** — check `.claude/skills/research-cache/cache/<topic>.md` first. If fresh (≤ 30 days), use it and skip steps 2–5 | `research-cache` |
+| 2 | **MCP probe** — detect `mcp__web-scraper__*` availability (one-shot per session) | `research-web` |
+| 3 | **Search** — Tier 1: `unified_search` (Brave + Vertex AI + Grok, dedupe + scoring). Tier 2 fallback: built-in `WebSearch` | `research-web` |
+| 4 | **Source ranking** — official docs > engineering blogs > GitHub issues > Stack Overflow. Reject anything > 18 months old without re-validation | (you) |
+| 5 | **Deep read** — Tier 1: `scrape_url` (stealth + proxy). Tier 2 fallback: built-in `WebFetch` | `research-web` |
+| 6 | **Document** — write `.claude/skills/research-cache/cache/<topic>.md` with: date · expiry (now + 30 days) · sources · TL;DR · actionable rules | `research-cache` |
+| 7 | **Promote** — if any rule applies project-wide, propose adding it to `CLAUDE.md` (do NOT auto-edit; surface the proposal) | (you) |
 
-1. **Check cache** → `.claude/skills/research-cache/cache/`
-2. **Search web** → "[topic] best practices [year] [stack]"
-3. **Sources**: Official docs > Engineering blogs > OWASP > GitHub issues
-4. **Document** → Create `.claude/skills/research-cache/cache/[topic].md`
-5. **Extract rules** → Add actionable rules to CLAUDE.md if applicable
-6. **Update cache** → Date + expiry (30 days)
+Each cache entry has frontmatter `expires_on:` so a future session can detect stale notes without re-reading the body.

package/stacks/_shared/commands/validate.md

@@ -1,10 +1,37 @@
+---
+name: validate
+description: Run the full quality gate (typecheck → lint → test → build) using the stack's commands from active-project.json.
+version: 1.0.0
+---
+
 # /validate — Run Full Validation
 
-Read quality gates from `.claude/config/active-project.json` and run all:
+Read the quality gates from `.claude/config/active-project.json#qualityGates` and run them in order. Stop at the first failure.
 
 ```bash
-# Read stack commands
-cat .claude/config/active-project.json | jq '.qualityGates'
+jq -r '.qualityGates' .claude/config/active-project.json
+```
+
+Execution order (each step blocks the next):
+
+| # | Gate | Typical commands |
+|---|---|---|
+| 1 | **Typecheck** | `npx tsc --noEmit` · `mypy .` · `vendor/bin/phpstan analyse` |
+| 2 | **Lint** | `npx eslint .` · `ruff check .` · `vendor/bin/pint --test` |
+| 3 | **Unit tests** | `npx vitest run` · `pytest` · `vendor/bin/phpunit` |
+| 4 | **E2E** (only if configured) | `npx playwright test` |
+| 5 | **Build** | `npm run build` · `composer dump-autoload --optimize` |
+
+Output format (one line per gate):
+
+```
+typecheck: PASS  (1.4s)
+lint:      PASS  (0.8s)
+tests:     PASS  (45/45 in 6.2s)
+e2e:       SKIP  (not configured)
+build:     PASS  (3.1s)
+
+✅ All gates passed — safe to invoke commit-manager
 ```
 
-Then execute each gate in order. Report pass/fail for each.
+If any gate fails, print the failure output and exit non-zero. `commit-manager` will refuse to commit while validation is failing.

package/stacks/_shared/skills/codebase-knowledge/SKILL.md

@@ -1,71 +1,68 @@
 ---
 name: codebase-knowledge
-version: 1.0.0
+version: 2.0.0
+description: "Cached domain knowledge consumed BEFORE implementing any feature. Reads `.claude/skills/codebase-knowledge/_index.json` (machine-readable, regenerated by `documenter`) for fast filter, then reads only the affected `domains/<slug>.md` files. Avoids re-exploring the codebase every session."
 ---
 
-# Codebase Knowledge — Domain Mapping System
+# Codebase Knowledge — Domain Knowledge Reader (v2.0.0)
 
 **ALWAYS invoke BEFORE implementing any feature.**
 
-## Purpose
+This skill is the **read side** of the project memory layer maintained by the `documenter` and `domain-updater` agents. Its job is to load just enough context for the next change without re-discovering the whole codebase.
 
-Maps files by domain, tracks connections, caches architecture decisions.
-
-## Domain Files Location
+## Storage layout (maintained by `documenter` v2.0.0)
 
 ```
-.claude/skills/codebase-knowledge/domains/
-├── authentication.md
-├── api.md
-├── database.md
-├── ui-components.md
-└── [domain-name].md
+.claude/skills/codebase-knowledge/
+├── SKILL.md                  # this file
+├── TEMPLATE.md               # template for new domain files (no version — it is a template)
+├── _INDEX.md                 # human-readable list of all domains
+├── _index.json               # machine-readable index — SOURCE OF TRUTH for filter
+└── domains/
+    ├── <slug>.md             # one file per domain. ≤ 8 KB / ~2k tokens / 200 lines
+    └── <slug>.archive.md     # commits/wisdom older than the cap (read on demand only)
 ```
 
-## Domain File Template
-
-```markdown
-# {Domain Name}
+## Read protocol (token-efficient)
 
-## Last Update
-- **Date:** YYYY-MM-DD
-- **Commit:** abc123
-- **Summary:** What changed
+| # | Step | Tool |
+|---|---|---|
+| 1 | **Resolve which domain(s) you need** by glob/grep on the affected file paths against `.claude/config/domain-mapping.json` | Bash + jq |
+| 2 | **Read `_index.json` first** — one query gives you `last_commit`, `tags`, `connections` for every domain | `jq '.domains[] \| select(.slug == "auth")' _index.json` |
+| 3 | **Read only the matched `domains/<slug>.md`** files — never `cat domains/*.md` (that defeats the budget) | Read |
+| 4 | **Follow `connections`** if the change crosses a domain boundary; read those neighbours too | Read |
+| 5 | **Skip `<slug>.archive.md`** unless `_index.json` flags `status: archived` and you actually need history | Read |
 
-## Files
-| File | Purpose |
-|------|---------|
-| `path/file.ext` | Description |
+## Domain file shape
 
-## Connections
-| Domain | How They Connect |
-|--------|-----------------|
-| auth | Validates tokens before API calls |
+Defined by `documenter` v2.0.0 — see `TEMPLATE.md` in this folder for the canonical layout. Required sections:
 
-## Recent Commits
-| Hash | Date | Description |
-|------|------|-------------|
-| abc123 | YYYY-MM-DD | feat: description |
-
-## Attention Points
-- Important gotcha or consideration
-
-## Problems & Solutions
-### Problem Title
-**Problem:** What went wrong
-**Solution:** How it was fixed
-**Prevention:** How to avoid in future
-```
+- YAML frontmatter (`domain · tags · owner · last_commit · last_date · files_count · connections · status`)
+- TL;DR (≤ 3 lines, front-loads boundary)
+- Files table (path → role)
+- Connections table (bidirectional: → and ← rows)
+- Recent Commits (capped at 20)
+- Attention Points (capped at 10)
+- Problems & Solutions (capped at 5, append-only)
 
 ## Workflow
 
-1. **Before coding** → Read relevant domain files
-2. **During coding** → Note connections and gotchas
-3. **After coding** → documenter + domain-updater agents update these files
+1. **Before coding** — read this skill, then `_index.json`, then the affected `domains/<slug>.md` files.
+2. **During coding** — note any new connection, gotcha, or non-obvious decision (you do not write here directly).
+3. **After commit** — `documenter` maps files+commits, `domain-updater` records the wisdom you collected.
 
 ## Rules
 
-1. **CHECK BEFORE IMPLEMENTING** — always read affected domains first
-2. **BIDIRECTIONAL CONNECTIONS** — if A connects to B, update both
-3. **INCLUDE COMMIT HASHES** — traceability
-4. **RECORD PROBLEMS** — future sessions benefit from lessons learned
+1. **READ `_index.json` FIRST** — it is regenerated each commit; it is the cheapest way to filter.
+2. **NEVER `cat domains/*.md`** — you will blow the context budget.
+3. **BIDIRECTIONAL CONNECTIONS** — if `auth.md` lists `→ api`, then `api.md` MUST list `← auth`. If you spot a missing reverse edge, surface it for `domain-updater`.
+4. **ARCHIVE FILES ARE OPT-IN** — read `<slug>.archive.md` only when `_index.json` shows `status: archived` or when you need pre-cap history.
+5. **DO NOT EDIT DOMAIN FILES DIRECTLY** — only `documenter` and `domain-updater` write here. If something is wrong, fix the agent or report drift.
+6. **TRUST `last_commit`** — if `_index.json#last_commit` ≠ HEAD, the documenter forgot to run; pause and fix instead of working with stale knowledge.
+
+## See Also
+
+- `documenter` v2.0.0 — writes to this layout (after every commit)
+- `domain-updater` v2.0.0 — writes session wisdom (Problems & Solutions, Attention Points)
+- `docs-tracker` v2.0.0 — file → domain mapping rules
+- `claude-md-compactor` v2.0.0 — keeps `CLAUDE.md` ≤ 20 KB; this layer keeps each domain ≤ 8 KB

package/stacks/_shared/skills/codebase-knowledge/TEMPLATE.md

@@ -1,23 +1,44 @@
-# {Domain Name}
+---
+domain: <slug>
+tags: [tag1, tag2]
+owner: <team or "shared">
+last_commit: <short-sha>
+last_date: YYYY-MM-DD
+files_count: 0
+connections: []
+status: active
+---
 
-## Last Update
-- **Date:** YYYY-MM-DD
-- **Commit:** 
-- **Summary:** 
+# <Title> Domain
+
+> **TL;DR** (≤ 3 lines). What lives here, where the boundary is, who calls it.
+> Example: "User session lifecycle. Owns Sanctum cookie, login, password reset.
+> Does NOT own user profile data (see `users` domain)."
 
 ## Files
-| File | Purpose |
-|------|---------|
+
+| Path | Role |
+|---|---|
 
 ## Connections
-| Domain | How They Connect |
-|--------|-----------------|
 
-## Recent Commits
-| Hash | Date | Description |
-|------|------|-------------|
+| Direction | Domain | What flows |
+|---|---|---|
+
+## Recent Commits (capped at 20 — oldest auto-archived)
+
+| Hash | Date | Subject |
+|---|---|---|
 
 ## Attention Points
-- 
 
-## Problems & Solutions
+(≤ 10 entries; oldest beyond 10 → `<slug>.archive.md`)
+
+## Problems & Solutions (append-only)
+
+(≤ 5 entries; oldest beyond 5 → `<slug>.archive.md`)
+
+## See Also
+
+- Skill: `<skill-name §section>`
+- Domain: `<related-slug>`

package/stacks/_shared/skills/docker-patterns/SKILL.md

@@ -1,52 +1,205 @@
 ---
 name: docker-patterns
-version: 1.0.0
+version: 2.0.0
+description: "Docker patterns for 2026: BuildKit + Buildx Bake (default builder for Docker Compose since June 2025), multi-stage builds, distroless / chiseled bases (90% size reduction, no shell), non-root users, .dockerignore, healthchecks, additional_contexts for service deps, secrets via build mounts (not COPY), reproducible builds. Stack examples: Node 22, Python 3.13 (uv), PHP 8.4 (FPM + Nginx)."
 ---
 
-# Docker Patterns
+# Docker Patterns (2026)
 
-## PHP (PHP-FPM + Nginx)
+**Invoke when writing or modifying any `Dockerfile`, `docker-compose.yml`, `docker-bake.hcl`, or container build config.**
 
-```dockerfile
-FROM php:8.3-fpm-alpine
+> 2026 reality: BuildKit is the only builder; Bake is the default for Compose multi-image projects (since June 2025); distroless / chiseled bases are the default for production runtime; non-root + readonly rootfs is the default. **Anything else needs justification.**
 
-RUN apk add --no-cache \
-    libzip-dev \
-    && docker-php-ext-install pdo_mysql zip opcache
+## 1. The four non-negotiables
 
-COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
-COPY . /var/www/html
-WORKDIR /var/www/html
+1. **Multi-stage build** — separate build deps from runtime deps. No exceptions.
+2. **Distroless or chiseled runtime** — no shell, no package manager, no curl. ~2 MB instead of ~120 MB.
+3. **Non-root user** — `USER 10001:10001` in the runtime stage. Never `root`.
+4. **`.dockerignore`** — at minimum: `node_modules`, `vendor`, `.git`, `.env*`, `*.log`, `dist`, `build`, `coverage`, `__pycache__`, `.venv`.
 
-RUN composer install --no-dev --optimize-autoloader
-RUN chown -R www-data:www-data /var/www/html
+## 2. Node.js 22 — production-grade Dockerfile
 
-EXPOSE 9000
-CMD ["php-fpm"]
+```dockerfile
+# syntax=docker/dockerfile:1.7
+ARG NODE_VERSION=22.11.0
+
+# ---------- builder ----------
+FROM node:${NODE_VERSION}-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN --mount=type=cache,target=/root/.npm \
+    npm ci --ignore-scripts
+COPY . .
+RUN npm run build && npm prune --omit=dev
+
+# ---------- runtime: distroless, no shell ----------
+FROM gcr.io/distroless/nodejs22-debian12:nonroot AS runtime
+WORKDIR /app
+COPY --from=builder --chown=nonroot:nonroot /app/node_modules ./node_modules
+COPY --from=builder --chown=nonroot:nonroot /app/dist         ./dist
+COPY --from=builder --chown=nonroot:nonroot /app/package.json ./
+USER nonroot
+EXPOSE 3000
+ENV NODE_ENV=production
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD ["/nodejs/bin/node", "-e", "fetch('http://127.0.0.1:3000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+CMD ["dist/server.js"]
 ```
 
-## Node.js (Multi-stage)
+Key 2026 patterns: `--mount=type=cache` for npm, `--ignore-scripts` (supply-chain hardening — see `secrets-management` §2025-A03), distroless `nonroot` tag, `--chown` on COPY, healthcheck against `/healthz`.
+
+## 3. Python 3.13 + `uv` — production-grade Dockerfile
 
 ```dockerfile
-FROM node:20-alpine AS builder
+# syntax=docker/dockerfile:1.7
+FROM python:3.13-slim-bookworm AS builder
+COPY --from=ghcr.io/astral-sh/uv:0.5 /uv /usr/local/bin/uv
 WORKDIR /app
-COPY package*.json ./
-RUN npm ci
+COPY pyproject.toml uv.lock ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-install-project
 COPY . .
-RUN npm run build
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
 
-FROM node:20-alpine
+FROM gcr.io/distroless/python3-debian12:nonroot AS runtime
 WORKDIR /app
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/node_modules ./node_modules
-EXPOSE 3000
-CMD ["node", "dist/index.js"]
+COPY --from=builder --chown=nonroot:nonroot /app /app
+USER nonroot
+EXPOSE 8000
+ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
+CMD ["/app/.venv/bin/uvicorn", "myapp.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+## 4. PHP 8.4 (FPM + Nginx) with Composer install in builder
+
+```dockerfile
+# syntax=docker/dockerfile:1.7
+FROM composer:2 AS vendor
+WORKDIR /app
+COPY composer.json composer.lock ./
+RUN composer install --no-dev --no-interaction --no-scripts --prefer-dist --optimize-autoloader
+
+FROM php:8.4-fpm-alpine AS runtime
+RUN apk add --no-cache libzip-dev oniguruma-dev icu-dev \
+ && docker-php-ext-install pdo_mysql zip opcache intl bcmath \
+ && rm -rf /var/cache/apk/*
+WORKDIR /var/www/html
+COPY --from=vendor /app/vendor ./vendor
+COPY --chown=www-data:www-data . .
+USER www-data
+EXPOSE 9000
+HEALTHCHECK --interval=30s --timeout=3s CMD php-fpm-healthcheck || exit 1
+CMD ["php-fpm"]
+```
+
+## 5. Compose with `additional_contexts` — service deps without sequential builds
+
+For a project where service B depends on service A's image, **don't** rely on `depends_on` for build order — declare a build-time dependency:
+
+```yaml
+# docker-compose.yml
+services:
+  api:
+    build:
+      context: ./api
+      dockerfile: Dockerfile
+
+  worker:
+    build:
+      context: ./worker
+      dockerfile: Dockerfile
+      additional_contexts:
+        api: "service:api"          # build worker AFTER api, with api's image as a context
+```
+
+## 6. Bake — the default Compose builder (since Jun 2025)
+
+Compose v2 now invokes Buildx Bake by default for multi-service projects. Opt out with `COMPOSE_BAKE=false` only if you need a feature Bake doesn't support (rare).
+
+```hcl
+# docker-bake.hcl — explicit form for CI / multi-arch
+variable "TAG" { default = "latest" }
+
+group "default" {
+  targets = ["api", "worker"]
+}
+
+target "api" {
+  context    = "./api"
+  dockerfile = "Dockerfile"
+  platforms  = ["linux/amd64", "linux/arm64"]
+  tags       = ["myorg/api:${TAG}"]
+  cache-from = ["type=gha"]
+  cache-to   = ["type=gha,mode=max"]
+}
+
+target "worker" {
+  inherits  = ["api"]
+  context   = "./worker"
+  tags      = ["myorg/worker:${TAG}"]
+}
+```
+
+```bash
+# Build everything in parallel, push to registry, with cache shared via GitHub Actions
+TAG=v1.2.3 docker buildx bake --push
 ```
 
-## Rules
+## 7. Build-time secrets — `--mount=type=secret`, never `COPY .env`
+
+```dockerfile
+# syntax=docker/dockerfile:1.7
+RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
+    npm ci
+```
+
+```bash
+docker buildx build --secret id=npmrc,src=$HOME/.npmrc .
+```
+
+The secret never lands in any image layer. **Never** `COPY .env` or `ENV API_KEY=...`. See `secrets-management`.
+
+## 8. Healthchecks — match the orchestrator's expectation
+
+```dockerfile
+# Application-level check; fast; idempotent.
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD wget -qO- http://127.0.0.1:3000/healthz || exit 1
+```
+
+For Kubernetes the Dockerfile HEALTHCHECK is informational only — the cluster uses `livenessProbe` / `readinessProbe`. See `observability` §7.
+
+## 9. Image hardening checklist
+
+- [ ] Multi-stage build present
+- [ ] Runtime stage is distroless / chiseled / scratch (no shell, no package manager)
+- [ ] `USER` directive set to non-root before `CMD`
+- [ ] `.dockerignore` excludes `.env*`, `node_modules`, `.git`, build outputs
+- [ ] No secrets baked into layers (`docker history --no-trunc IMAGE` clean)
+- [ ] `HEALTHCHECK` directive present
+- [ ] Image pinned by digest in production manifests (`image@sha256:...`)
+- [ ] `docker scout cves IMAGE` (or `trivy image IMAGE`) clean of HIGH/CRITICAL
+- [ ] Build is reproducible — same input → same digest
+
+## FORBIDDEN
+
+| Pattern | Why |
+|---|---|
+| `FROM ubuntu:latest` (or any `latest`) | Unpinned, unreproducible |
+| `RUN apt-get install ...` without `--no-install-recommends` and `rm -rf /var/lib/apt/lists/*` | Bloated layers, stale package cache |
+| `COPY .env .` | Secrets in image layer forever |
+| `ENV API_KEY=...` in Dockerfile | Same |
+| `USER root` in runtime stage | Container escape blast radius |
+| `chmod 777` on app dirs | Privilege escalation in shared envs |
+| `--privileged` containers without explicit security review | Almost always wrong |
+| `curl ... | sh` in RUN | Unverifiable supply chain |
+| Single-stage build with dev deps in final image | Bloated, exposes build tools |
+| `HEALTHCHECK NONE` | Orchestrator can't tell if app is wedged |
+
+## See Also
 
-1. **Multi-stage builds** — smaller images
-2. **Alpine base** — minimal attack surface
-3. **.dockerignore** — exclude node_modules, .git
-4. **Non-root user** — security
-5. **Health checks** — always include
+- `secrets-management` — build-time secret mounts, OIDC for registry push
+- `security-baseline` (2025-A03) — supply chain: pin actions by SHA, sign images (Sigstore/cosign)
+- `observability` — `/healthz` + `/readyz` semantics
+- `ci-pipelines` — building & pushing in CI