@codepassion/skills 1.2.0 → 1.5.0

package/README.md

@@ -8,8 +8,13 @@ Agent skills (SKILL.md) based on the CodePassion (C9N) conventions.
     npx @codepassion/skills install codex      # ~/.codex/skills
     npx @codepassion/skills install project    # ./.agents/skills
     npx @codepassion/skills install combined   # one combined skill
+    npx @codepassion/skills install cowork     # zip skills for claude.ai/Cowork upload (UI, no API)
 
-Or: ./install.sh {claude|codex|project|combined}
+Or: ./install.sh {claude|codex|project|combined|cowork}
+
+claude.ai and Claude Cowork share a personal skill library with no upload API, so `cowork`
+packages upload-ready zips into dist/cowork/ — upload them at
+claude.ai → Settings → Capabilities → Upload skill.
 
 ## Edit
 

package/SKILLS.md

@@ -8,8 +8,13 @@ Agent skills (SKILL.md) based on the CodePassion (C9N) conventions.
     npx @codepassion/skills install codex      # ~/.codex/skills
     npx @codepassion/skills install project    # ./.agents/skills
     npx @codepassion/skills install combined   # one combined skill
+    npx @codepassion/skills install cowork     # zip skills for claude.ai/Cowork upload (UI, no API)
 
-Or: ./install.sh {claude|codex|project|combined}
+Or: ./install.sh {claude|codex|project|combined|cowork}
+
+claude.ai and Claude Cowork share a personal skill library with no upload API, so `cowork`
+packages upload-ready zips into dist/cowork/ — upload them at
+claude.ai → Settings → Capabilities → Upload skill.
 
 ## Edit
 

package/bin/c9n-skills.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { cp, mkdir, readdir, stat } from 'node:fs/promises'
+import { cp, mkdir, readdir, rm, stat } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { execFile } from 'node:child_process'
 const SRC = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
 const [,, cmd='install', target='claude', ...rest] = process.argv
 if (cmd==='help'||cmd==='--help'||cmd==='-h'){ help(); process.exit(0) }
@@ -12,7 +13,12 @@ const flags={dest:null,force:false,dryRun:false}
 for (let i=0;i<rest.length;i++){ const a=rest[i]
   if (a==='--force') flags.force=true
   else if (a==='--dry-run') flags.dryRun=true
-  else if (a==='--dest') flags.dest=resolve(rest[++i]??'') }
+  else if (a==='--dest'){ const v=rest[++i]
+    if (!v){ console.error('--dest requires a value'); process.exit(1) }
+    flags.dest=resolve(v) } }
+// cowork: claude.ai / Cowork share a personal skill library with NO upload API —
+// this packages upload-ready zips for manual drag-drop in Settings → Capabilities.
+if (target==='cowork'){ await packageForCowork(flags); process.exit(0) }
 const dest = flags.dest ?? defaultDest(target)
 if (!dest){ help(); process.exit(1) }
 const sources = await resolveSources(target)
@@ -33,4 +39,23 @@ function defaultDest(t){ const h=homedir()
   if (t==='codex') return join(h,'.codex','skills')
   if (t==='project') return join(process.cwd(),'.agents','skills')
   return null }
-function help(){ console.log('c9n-skills install [claude|codex|project|combined] [--dest <dir>] [--force] [--dry-run]') }
+async function packageForCowork(flags){
+  const ROOT=resolve(SRC,'..')
+  // only auto-clean the default output dir — never delete a user-supplied --dest
+  const isDefaultOut=!flags.dest
+  const out=flags.dest ?? join(ROOT,'dist','cowork')
+  const sources=[...await resolveSources('combined'), ...await resolveSources('cowork')]
+  if (!sources.length){ console.error('No skills found'); process.exit(1) }
+  console.log(`Packaging ${sources.length} skill zip(s) into ${out}${flags.dryRun?' (dry-run)':''}`)
+  if (!flags.dryRun){ if (isDefaultOut) await rm(out,{recursive:true,force:true}); await mkdir(out,{recursive:true}) }
+  for (const src of sources){ const n=src.split(/[\\/]/).pop()
+    console.log(`  zip   ${n}.zip`)
+    if (!flags.dryRun) await zipDir(SRC,n,join(out,`${n}.zip`)) }
+  console.log('Done. Upload at claude.ai → Settings → Capabilities → Upload skill (shared with Cowork).')
+  console.log('Action skills (c9n-spec, c9n-deliverables) bundle their templates/scripts in the zip.')
+}
+function zipDir(cwd,name,outFile){
+  return new Promise((res,rej)=>{ execFile('zip',['-qr',outFile,name],{cwd},(e)=>{
+    if (e && e.code==='ENOENT') rej(new Error("'zip' command not found — install zip and retry"))
+    else if (e) rej(e); else res() }) }) }
+function help(){ console.log('c9n-skills install [claude|codex|project|combined|cowork] [--dest <dir>] [--force] [--dry-run]') }

package/install.sh

@@ -1,13 +1,36 @@
 #!/usr/bin/env bash
 set -euo pipefail
-SRC="$(cd "$(dirname "$0")" && pwd)/skills"
+ROOT="$(cd "$(dirname "$0")" && pwd)"
+SRC="$ROOT/skills"
 MODE="${1:-claude}"
+
+# cowork: claude.ai / Cowork share a personal skill library with NO upload API —
+# package upload-ready zips for manual drag-drop in Settings → Capabilities.
+if [ "$MODE" = "cowork" ]; then
+  command -v zip >/dev/null || { echo "error: 'zip' not found — install zip and retry"; exit 1; }
+  DEST="${TARGET_DIR:-$ROOT/dist/cowork}"
+  # only auto-clean the default output dir — never delete a user-supplied TARGET_DIR
+  if [ -z "${TARGET_DIR:-}" ]; then rm -rf "$DEST"; fi
+  mkdir -p "$DEST"
+  count=0
+  for d in "$SRC"/c9n "$SRC"/c9n-*; do
+    [ -d "$d" ] || continue
+    name="$(basename "$d")"
+    (cd "$SRC" && zip -qr "$DEST/$name.zip" "$name")
+    count=$((count + 1))
+  done
+  echo "Packaged $count skill zip(s) into $DEST"
+  echo "Upload at claude.ai → Settings → Capabilities → Upload skill (shared with Cowork)."
+  command -v open >/dev/null && open "$DEST" 2>/dev/null || true
+  exit 0
+fi
+
 case "$MODE" in
   claude)   DEST="${TARGET_DIR:-$HOME/.claude/skills}" ;;
   codex)    DEST="${TARGET_DIR:-$HOME/.codex/skills}" ;;
   project)  DEST="${TARGET_DIR:-$PWD/.agents/skills}" ;;
   combined) DEST="${TARGET_DIR:-$HOME/.claude/skills}" ;;
-  *) echo "Use: claude | codex | project | combined"; exit 1 ;;
+  *) echo "Use: claude | codex | project | combined | cowork"; exit 1 ;;
 esac
 mkdir -p "$DEST"
 if [ "$MODE" = "combined" ]; then cp -R "$SRC/c9n" "$DEST/"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepassion/skills",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "description": "Agent skills (SKILL.md) for CodePassion (C9N) engineering conventions.",
   "license": "MIT",
   "type": "module",

package/skills/c9n/SKILL.md

@@ -237,3 +237,325 @@ These ALWAYS run, in order — never skip them:
 - **Redoc/Swagger UI → PDF**: they lazy-render; printing truncates. Use `openapi-to-pdf.mjs`.
 - See [REFERENCE.md](../c9n-deliverables/REFERENCE.md) for the ISO/IEC 29110 layout and per-artifact recipes.
 
+
+
+---
+
+## Pipeline
+
+Bootstraps the Code Passion (C9N) CI/CD pipeline into a target repo so a new project deploys the
+same way as the reference implementation (Smiley): **one image per app, built once at the Alpha
+tag, redeployed to Beta/Production by base tag**, env injected at runtime by Coolify. The heavy
+lifting lives in the org reusable workflows `codepassion-team/cicd/.github/workflows/{build,deploy}.yml`
+— the per-repo files this skill generates just call them. The skill's real value is **Phase 3**:
+the interactive ops checklist that encodes every footgun the Smiley setup hit.
+
+Bundled `templates/` are the source skeleton. **Copy them, then substitute tokens** — never edit
+the templates in place for a specific project. The Next.js wiring is an **edit** of files the dev
+already owns, not a file drop (see Phase 2).
+
+## What gets generated
+
+| Path | Template | When |
+|------|----------|------|
+| `<app>/Dockerfile` | `Dockerfile.api` | app has `elysia` |
+| `<app>/Dockerfile` | `Dockerfile.web` | app has `next` |
+| `<app>/Dockerfile` | `Dockerfile.service` | any other deployable app (worker, plain Bun) |
+| `.dockerignore` | `dockerignore` | always (repo root) |
+| `.github/workflows/ci.yml` | `workflows/ci.yml` (+ `_migration-check.partial` if DB) | always |
+| `.github/workflows/deployment.yml` | `workflows/deployment.yml` (+ `_build-job`/`_deploy-job` partials) | always |
+| `<web>/next.config.js` | **edit, not copy** | per web app |
+| `<web>/app/layout.tsx` | **edit, not copy** | per web app |
+
+## Workflow
+
+Run in order; this is a table of contents — rules are below.
+
+1. **Detect (Phase 1).** First decide the repo shape:
+   - **Monorepo** — `apps/` and/or `turbo.json` exist. Scan `apps/*/package.json`, classify each:
+     `next`→web, `elysia`→api, else→service. `{{APP_DIR}}` = `apps/<name>`.
+   - **Single-app** — no `apps/`, no `turbo.json`; the deployable app is the repo root. Classify the
+     root `package.json` (`next`→web, etc.). `{{APP_DIR}}` = `.`, `{{PACKAGE_NAME}}` = the repo name
+     (no `-web` suffix needed), and the **single-app template variants** apply (see "Single-app repos"
+     below) — drop the workspace-manifest copies, `outputFileTracingRoot`, `transpilePackages`, and
+     the `apps/web/` path segments. The generated `ci.yml` also drops Turbo (see that template's note).
+
+   Then detect DB by **real artifacts** — a migration-generate script in some `package.json` AND a
+   migrations dir on disk — capture their actual names; never assume `drizzle:generate` /
+   `packages/supabase/migrations`. Read the app's `package.json` for the Bun version / lockfile name
+   (but **pin ≥ 1.3.10** — see `{{BUN_VERSION}}`). Ask which environments exist (Alpha / Beta /
+   Production). **Print the detected plan and confirm before writing anything.**
+2. **Generate (Phase 2).** Copy templates with tokens substituted. **Diff/confirm per file** — if a
+   target exists, show the diff and ask overwrite/skip/merge; never blind-clobber; leave unrelated
+   files (a hand-kept `staging.yaml`) alone. Then do the **web edits** (below). Run the web build
+   once to prove nothing is baked.
+3. **Checklist (Phase 3).** Walk the dev interactively through the out-of-repo ops (below). This is
+   the deliverable.
+4. **Verify (Phase 4).** After the dev confirms the ops are done, push a tag (or reuse one), watch
+   the Actions run, then `curl` each deployed URL per environment and report pass/fail per app.
+
+## Token substitution
+
+| Token | Source |
+|-------|--------|
+| `{{PACKAGE_NAME}}` | `<project>-<appkey>`, e.g. `smiley-web`. Lowercase. This is the ghcr image name and the `package_name` workflow input. |
+| `{{APP_DIR}}` | The app's path, e.g. `apps/web`. **Single-app repo: `.`** (the app is the repo root — this leaves valid `./.next/...` paths in the template). |
+| `{{APP_KEY}}` | Short lowercase id unique per app: `api`, `web`, `worker`. Used in job names. |
+| `{{APP_PORT}}` | `3001` api · `3000` web · service's listen port (drop `EXPOSE` for a portless worker). |
+| `{{BUN_VERSION}}` | **Pin ≥ 1.3.10** (same across all Dockerfiles). Do **not** copy the host's `bun --version` — 1.2.x breaks `next build` on Linux with `TypeError: Expected CommonJS module to have a function wrapper` (edge/jest-worker; only shows on Linux, not macOS). |
+| `{{WORKSPACE_MANIFEST_COPIES}}` | **web template only:** one `COPY <app>/package.json ./<app>/package.json` line **per app** — the `deps` stage runs `bun install` before `COPY . .`, so it needs every workspace manifest to resolve the graph. The api/service compile templates copy only the built app's manifest (matches Smiley's api Dockerfile; avoids pulling a sibling app's postinstall without its src). **Single-app repo: empty string** (root `package.json` + `bun.lock` are already copied; there is no `packages/` — also delete the `COPY packages/ ./packages/` line). |
+| `{{MIGRATION_CHECK}}` | `_migration-check.partial.yml` with `{{MIGRATION_SCRIPT}}`/`{{MIGRATIONS_DIR}}` filled, **or empty string** if no DB. |
+| `{{ORG_REF}}` | The org reusable-workflow ref — currently `turborepo`. One place; bump here if the org repo retags. |
+| `{{BUILD_JOBS}}` / `{{DEPLOY_JOBS}}` | Stamp `_build-job.partial` once per app (Alpha only) and `_deploy-job.partial` once per app per environment, pruning unused envs. |
+| `{{DEPLOY_NAME}}` | The org `deploy.yml` `name` input → uppercased to `<NAME>_UUID`. **Only `API` and `WEB` are wired** in the org deploy.yml (see Gotchas). |
+
+## Web edits (surgical — not a file drop)
+
+For each **web** app, edit the files the dev owns; fail loudly if they can't be parsed rather than
+overwrite:
+
+- `next.config.js` — add `output: "standalone"`. **Monorepo only:** also add `outputFileTracingRoot`
+  (monorepo root) and `transpilePackages` for the workspace packages the app imports. **Single-app:
+  omit both** (root app traces natively; no workspace packages).
+- `app/layout.tsx` — add `<head><PublicEnvScript /></head>` (`import { PublicEnvScript } from
+  "next-runtime-env"`).
+- **Convert EVERY `process.env.NEXT_PUBLIC_*` read to `env("NEXT_PUBLIC_X")`** — not just client
+  components. Next **inlines every `process.env.NEXT_PUBLIC_*` literal at build time in SERVER code and
+  middleware too**, so any read left as `process.env` bakes the build value (or a build-time
+  placeholder) into the server/middleware bundle and runtime injection can't override it. This is the
+  #1 time-sink: a stray `process.env.NEXT_PUBLIC_SUPABASE_URL` in `middleware.ts` bakes the placeholder
+  → `supabase.auth.getUser()` fails → **auth redirect loop** that only shows in the container, not
+  locally. Convert: client components, **server components, route handlers (`app/api/**`), middleware,
+  and any t3-env `runtimeEnv` mapping**. Non-public server vars (`DATABASE_URL`, `*_SERVICE_KEY`) stay
+  on `process.env` — they aren't inlined and are present at runtime.
+- **Phase-2 gate — must pass before you call the web edits done:**
+  `grep -rn 'process.env.NEXT_PUBLIC' {{APP_DIR}}` (the app dir — `.` for single-app, `apps/web` for a
+  monorepo app; not every repo has a `src/`) returns **nothing**. Any hit is a latent runtime bug.
+- Flag `next-runtime-env` as a dependency to add — **do not run `bun add` yourself**; tell the dev.
+- **Caveat:** runtime values only reach the browser on non-statically-prerendered pages. A page that
+  reads runtime public env must opt out of static caching (`export const dynamic = "force-dynamic"`)
+  or rely on `<PublicEnvScript>` keeping the document dynamic. Note this so future feature work
+  doesn't silently bake a static page.
+
+## Single-app repos (no `apps/`, no `turbo.json`)
+
+The templates are monorepo-shaped; one set of token substitutions makes them serve a root-level single
+app. Apply these deltas (verified on `ddg-jewelry-admin`):
+
+- **Tokens:** `{{APP_DIR}}` = `.`, `{{PACKAGE_NAME}}` = repo name (no `-web` suffix),
+  `{{WORKSPACE_MANIFEST_COPIES}}` = empty.
+- **`Dockerfile.web`:** delete the `COPY packages/ ./packages/` line (no `packages/`). The runner
+  `COPY` lines collapse to `.next/standalone ./`, `.next/static ./.next/static`, `public ./public`
+  (the `{{APP_DIR}}=.` substitution yields valid `./.next/...` — fine to simplify).
+- **`next.config`:** `output: "standalone"` only — no `outputFileTracingRoot`, no `transpilePackages`.
+- **`ci.yml`:** drop the Turbo `env:`, the `.turbo` cache step, and swap `bun run check-types` for
+  `bunx tsc --noEmit` if the repo has no `check-types` script (single apps usually don't).
+- **Runner (optional but recommended):** a single Next app deploys cleanly on a Node runner
+  (`node:22-alpine` or `gcr.io/distroless/nodejs22-debian12`, `CMD ["server.js"]`). Distroless cuts the
+  image ~4× and drops the runner CVEs (seen on `ddg-jewelry-admin`).
+
+## Phase 3 — interactive ops checklist (the deliverable)
+
+Derived from the actual `codepassion-team/cicd` reusable workflows. Walk these one at a time:
+
+**Repo prerequisites**
+- A **`develop` branch must exist** — `build.yml` commits the version bump and does
+  `git pull --rebase origin develop` / `push HEAD:develop`. No develop branch → build fails.
+- Tags drive deploys; the exact tag→env mapping is **c9n-semver-deployment** (don't restate it).
+
+**Per environment** — create a GitHub **Environment** named exactly `Alpha` / `Beta` / `Production`:
+- Variables: `COOLIFY_RESOURCE_API_UUID`, `COOLIFY_RESOURCE_WEB_UUID` (the Coolify app UUIDs;
+  `deploy.yml` resolves `${NAME}_UUID`), and `TURBO_TEAM`.
+- Secrets: `COOLIFY_TOKEN` (Coolify API bearer) and `TURBO_TOKEN`. `GITHUB_TOKEN` is automatic
+  (ghcr push uses it; the build job already declares `packages: write`).
+
+**Coolify** (one resource per app per env): source = Docker image
+`ghcr.io/codepassion-team/{{PACKAGE_NAME}}:<base_tag>`; copy each resource's UUID into the matching
+env variable above. Caddy `reverse_proxy <app>:<port>` (api `:3001`, web `:3000`).
+
+**ghcr** — packages are **private**: give Coolify a registry pull credential (or set package
+visibility), or the image pull silently fails.
+
+**Web runtime env in Coolify** (the scars):
+- `PORT=3000` — Next standalone obeys `PORT`; Coolify defaults it to `80`, which 502s behind a
+  Caddy `:3000` proxy. This is the single most common web-deploy failure.
+- **Coolify `Ports Exposes` (General page) is a SEPARATE setting from the `PORT` env** — it defaults
+  to `80` and must be set to the app port (`3000`). With `PORT=3000` but Ports Exposes still `80`, the
+  deploy log warns `PORT (3000) does not match configured ports_exposes: 80` and the proxy 502s. Fix
+  both.
+- `HOSTNAME=0.0.0.0` — the Dockerfile already bakes this; only set it if something overrides it.
+- The app's `NEXT_PUBLIC_*` values — injected here at runtime, not baked into the image.
+- **Set ALL env values UNQUOTED** (public and server alike) — Coolify passes values literally, so a
+  quoted `DATABASE_URL="…"` keeps the quotes and breaks `new URL()` (`ERR_INVALID_URL`).
+
+## Phase 4 — verify
+
+Push a `v*.*.*` tag (or reuse one), watch the run (`gh run watch`), then for each app per env
+`curl -so /dev/null -w "%{http_code}"` the deployed URL (e.g. `https://api.<proj>.alpha.c9n.co`,
+`https://<proj>.alpha.c9n.co`) and confirm `200`. Report a clean pass/fail table. Don't call it done
+on a green Actions run alone — the 502 class only shows at the live URL.
+
+## Gotchas
+
+- **Combined install mode does not carry `templates/`.** `install.sh combined` copies only the
+  generated `skills/c9n` SKILL.md body. Install via `install.sh claude` (or `project`/`codex`) so the
+  templates come along — same limitation as `c9n-spec`/`c9n-deliverables`.
+- **Org deploy.yml wires only `API_UUID` + `WEB_UUID`.** A third app type (worker) needs a PR to
+  `codepassion-team/cicd` adding `COOLIFY_RESOURCE_<NAME>_UUID` to deploy.yml's `env:` block. Flag
+  this; don't generate a deploy job that silently can't resolve its UUID.
+- **Build once, deploy by base tag.** build.yml strips `-alpha`/`-rc.*`; deploy.yml also strips
+  `-beta.*`. So `v1.2.3` (Alpha) and a later `v1.2.3-beta.1` release both resolve base tag `v1.2.3`
+  and redeploy the same image. Beta/Prod must have an Alpha build of that base version in ghcr first.
+- **`.dockerignore` matters.** Without it, the host's `node_modules` (wrong platform) leaks into the
+  build context and clobbers the linux deps → "failed to load next.config". The template ships it.
+- **Don't touch `.env*`.** Generate `.dockerignore` to exclude them; never read or write env files.
+
+
+
+---
+
+## Sentry
+
+## Sentry — Bun + Elysia + Next.js
+
+## Three landmines (check first)
+
+1. **`@sentry/node` under `bun --compile` fails silently** — valid DSN, zero events. Use `@sentry/elysia` (built on `@sentry/bun`). Never let `@sentry/node` load on the API.
+2. **Runtime public env** — if the project uses `next-runtime-env` (ADR 0005 pattern), the browser DSN MUST use `env("NEXT_PUBLIC_SENTRY_DSN")` not `process.env`. Server/edge/api use `process.env`. Wrong = undefined DSN in prod = dead Sentry.
+3. **PDPA / PII** — add `beforeSend` scrubber + `sendDefaultPii: false`. Strip request body/query/cookies, drop auth headers, recursively redact PII keys. See [REFERENCE.md](REFERENCE.md#pdpa-scrubber).
+
+## Quick start
+
+```
+packages/sentry/          ← @repo/sentry (shared)
+  src/pdpa.ts             ← beforeSend scrubber (shared by all inits)
+  src/bun.ts              ← initBun() for apps/api
+  src/client.ts           ← initClient() for browser (uses env() not process.env)
+  src/server.ts           ← initServer() for Next.js server runtime
+  src/edge.ts             ← initEdge() for Next.js edge runtime
+  package.json            ← exports map: ./bun ./client ./server ./edge ./pdpa
+apps/api/src/lib/sentry.ts   ← import { initBun } from "@repo/sentry/bun"; initBun()
+apps/api/src/index.ts        ← first import: "./lib/sentry.js", then withElysia(new Elysia())
+apps/web/instrumentation.ts  ← register() → dynamic import server/edge config
+apps/web/instrumentation-client.ts ← initClient()
+apps/web/sentry.server.config.ts / sentry.edge.config.ts
+apps/web/next.config.js      ← withSentryConfig + transpilePackages: ["@repo/sentry"]
+```
+
+## Env vars
+
+| Service | Key | Read by |
+|---------|-----|---------|
+| API (Coolify) | `SENTRY_DSN`, `ENVIRONMENT` | `process.env` |
+| Web (Coolify) | `NEXT_PUBLIC_SENTRY_DSN`, `NEXT_PUBLIC_ENVIRONMENT` | `env()` from next-runtime-env (client) / `process.env` (server/edge) |
+
+One Sentry project, same DSN in both vars. Add `initialScope: { tags: { app: "api" } }` to `initBun()` so api vs web events are distinguishable in the shared project.
+
+## Verification checklist
+
+- [ ] `bun install --frozen-lockfile` clean
+- [ ] `bun run check-types` (api + web) clean
+- [ ] `bun run build --compile` on API — confirms `@sentry/node` never loaded (the landmine test)
+- [ ] Web Sentry bundle builds green
+- [ ] After deploy: `window.__ENV.NEXT_PUBLIC_SENTRY_DSN` populated in devtools (runtime env proof)
+- [ ] Trigger a test error → event appears in Sentry tagged correct environment
+- [ ] Open event payload — no phone/otp/lat/lng/member_id (PDPA proof)
+
+## Reference
+
+See [REFERENCE.md](REFERENCE.md) for full file contents, PDPA scrubber code, and `turbo.json` config.
+
+
+
+---
+
+## Spec
+
+Bootstraps the Code Passion (C9N) spec-driven development doc system into a target repo. Drops
+a self-contained, agent-readable documentation skeleton so a fresh project starts with the same
+approval gates, traceability, and glossary discipline as the reference implementation
+(ddg-jewelry). Fully generic — adapt the placeholders to whatever stack the project uses.
+
+Bundled `templates/` are the source skeleton. **Copy them, then substitute tokens** — never edit
+the templates in place for a specific project.
+
+## What gets scaffolded
+
+| File | Role |
+|------|------|
+| `AGENTS.md` | **Canonical** agent context: the full ISO/IEC 29110 spec-driven protocol (inlined, so the repo is self-contained) + C9N stack + module patterns. References the sibling `c9n-*` convention skills rather than copying them. |
+| `CLAUDE.md` | Bridge that `@AGENTS.md`-imports the canonical file (so Claude Code's memory auto-loads the protocol; other tools read AGENTS.md directly). |
+| `CONTEXT.md` | Ubiquitous-language glossary skeleton (no implementation detail). |
+| `DESIGN.md` | Visual design-system rules — **only if the repo has a frontend.** |
+| `docs/SRS.md` | Requirements master registry (feature short-codes + system NFRs). |
+| `docs/architecture.md` | Software-design as-is map. |
+| `docs/traceability.md` | Requirement → design → test master index. |
+| `docs/test-plan.md` | Master test strategy. |
+| `docs/adr/0001-spec-driven-iso29110-docs.md` | Seed ADR: why this doc system exists. |
+| `docs/adr/_TEMPLATE.md` | ADR format for future decisions. |
+| `docs/features/_TEMPLATE.md` | Per-feature deep-doc stub (Requirements · Design · Test Plan · Test Cases · Traceability). |
+| `docs/agents/{issue-tracker,triage-labels,domain}.md` | Agent-process docs (GitHub `gh`, triage vocab, domain-doc consumption). |
+| `.github/pull_request_template.md` | The Definition-of-Done merge gate. |
+
+## Workflow
+
+Run each step in order; this is a table of contents — the rules are below.
+
+1. **Detect repo shape.** Read the target's root `package.json`/workspaces. Decide:
+   monorepo vs single app; **frontend present?** (`apps/web`, or `next`/`astro`/`vite`/`react`
+   in any `package.json`) → include `DESIGN.md`. **Backend/API present?** → keep the API
+   module-patterns section in AGENTS.md; otherwise tell the user it's deletable.
+2. **No-clobber.** For every target path, **skip if it already exists** — never overwrite. Collect
+   skipped paths for the final report. (Re-running the skill must be safe and idempotent.)
+3. **Copy templates** into the target repo, substituting tokens (below). Skip `DESIGN.md` if no
+   frontend. Skip the API section guidance if no backend.
+4. **Optional scan — OFF by default.** Only if the user **explicitly** asks to seed from code
+   ("scan the codebase", "seed the glossary", "reverse-document"): read the codebase and fill
+   - `CONTEXT.md` — first real glossary terms (actors, core entities) from the domain;
+   - `docs/architecture.md` — the actual module map + data-model relationships;
+   - `docs/features/` — one as-built stub per shipped module (low-confidence, no test cases),
+     and register each in `docs/SRS.md` with a fresh short-code.
+   Without this request, leave the placeholders untouched.
+5. **Report.** Print created vs skipped files, then next steps: pick the first feature, write its
+   SRS section (Gate 1), get sign-off, then Design + Test Plan (Gate 2) — no production code
+   before Gate 2.
+
+## Token substitution
+
+When copying, replace these placeholders:
+
+| Token | Source |
+|-------|--------|
+| `{{PROJECT_NAME}}` | Target root dir name, or `package.json` `name` (humanized). |
+| `{{YEAR}}` / `{{DATE}}` | Current year / ISO date (for the seed ADR). |
+| `{{DECIDER}}` | Ask, or default to the repo owner. |
+| Stack rows in AGENTS.md | Keep C9N defaults; trim rows the detected stack doesn't use. |
+
+## Conventions (referenced, not copied)
+
+The scaffolded `AGENTS.md` points at the sibling C9N skills for engineering conventions — it does
+**not** inline them, so they have a single source of truth:
+
+- Commits → `c9n-commit-messages` · Branching → `c9n-git-branching` · PRs → `c9n-pull-requests`
+- Clean code → `c9n-clean-code-typescript` · Lint/types → `c9n-typescript-eslint`
+- Formatting → `c9n-code-formatting` · Review → `c9n-code-review`
+
+For C9N-internal repos every dev has these installed, so the references always resolve. If you
+scaffold into a repo where they may not be installed, tell the user to
+`npx @codepassion/skills install claude`.
+
+## Gotchas
+
+- **Combined install mode does not carry `templates/`.** `install.sh combined` copies only the
+  generated `skills/c9n` SKILL.md body; the bundled templates are absent. Install `c9n-spec` via
+  `install.sh claude` (or `project`/`codex`) so the templates come along. Same limitation as
+  `c9n-deliverables`' scripts.
+- **AGENTS.md vs CLAUDE.md.** AGENTS.md is the real file. CLAUDE.md exists only so Claude Code's
+  memory auto-load reaches the protocol — it does so via the **`@AGENTS.md` import** (Claude Code's
+  memory-import syntax), not a markdown link (a link is inert and pulls nothing into context). Don't
+  duplicate content into CLAUDE.md. If a target tool doesn't support `@`-imports, it reads AGENTS.md
+  directly anyway, so nothing is lost.
+- **Don't grade the stubs.** If you run the optional scan, as-built stubs describe *current*
+  behavior at low confidence with **no** test cases — deepen on touch, per the protocol. Don't
+  invent acceptance criteria for code you only read.
+

package/skills/c9n-pipeline/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: c9n-pipeline
+description: Bootstrap the C9N CI/CD pipeline INTO a Turborepo/Bun monorepo — generates the per-repo GitHub Actions (CI + tag-driven Deployment that call the org codepassion-team/cicd reusable workflows), per-app Dockerfiles (Elysia→bun-compile, Next.js standalone+runtime-env, generic service), and .dockerignore; then walks the developer through the out-of-repo ops (GitHub Environments, Coolify resources, ghcr pull, the PORT=3000 web footgun) and verifies the live deploy. Use when setting up CI/CD on a new C9N project, "add github actions", "set up deployment", "wire up Coolify", or porting the Smiley pipeline to another repo. Complements c9n-semver-deployment (owns the tag->env mapping) and c9n-spec (scaffolds docs, not pipelines).
+---
+
+Bootstraps the Code Passion (C9N) CI/CD pipeline into a target repo so a new project deploys the
+same way as the reference implementation (Smiley): **one image per app, built once at the Alpha
+tag, redeployed to Beta/Production by base tag**, env injected at runtime by Coolify. The heavy
+lifting lives in the org reusable workflows `codepassion-team/cicd/.github/workflows/{build,deploy}.yml`
+— the per-repo files this skill generates just call them. The skill's real value is **Phase 3**:
+the interactive ops checklist that encodes every footgun the Smiley setup hit.
+
+Bundled `templates/` are the source skeleton. **Copy them, then substitute tokens** — never edit
+the templates in place for a specific project. The Next.js wiring is an **edit** of files the dev
+already owns, not a file drop (see Phase 2).
+
+## What gets generated
+
+| Path | Template | When |
+|------|----------|------|
+| `<app>/Dockerfile` | `Dockerfile.api` | app has `elysia` |
+| `<app>/Dockerfile` | `Dockerfile.web` | app has `next` |
+| `<app>/Dockerfile` | `Dockerfile.service` | any other deployable app (worker, plain Bun) |
+| `.dockerignore` | `dockerignore` | always (repo root) |
+| `.github/workflows/ci.yml` | `workflows/ci.yml` (+ `_migration-check.partial` if DB) | always |
+| `.github/workflows/deployment.yml` | `workflows/deployment.yml` (+ `_build-job`/`_deploy-job` partials) | always |
+| `<web>/next.config.js` | **edit, not copy** | per web app |
+| `<web>/app/layout.tsx` | **edit, not copy** | per web app |
+
+## Workflow
+
+Run in order; this is a table of contents — rules are below.
+
+1. **Detect (Phase 1).** First decide the repo shape:
+   - **Monorepo** — `apps/` and/or `turbo.json` exist. Scan `apps/*/package.json`, classify each:
+     `next`→web, `elysia`→api, else→service. `{{APP_DIR}}` = `apps/<name>`.
+   - **Single-app** — no `apps/`, no `turbo.json`; the deployable app is the repo root. Classify the
+     root `package.json` (`next`→web, etc.). `{{APP_DIR}}` = `.`, `{{PACKAGE_NAME}}` = the repo name
+     (no `-web` suffix needed), and the **single-app template variants** apply (see "Single-app repos"
+     below) — drop the workspace-manifest copies, `outputFileTracingRoot`, `transpilePackages`, and
+     the `apps/web/` path segments. The generated `ci.yml` also drops Turbo (see that template's note).
+
+   Then detect DB by **real artifacts** — a migration-generate script in some `package.json` AND a
+   migrations dir on disk — capture their actual names; never assume `drizzle:generate` /
+   `packages/supabase/migrations`. Read the app's `package.json` for the Bun version / lockfile name
+   (but **pin ≥ 1.3.10** — see `{{BUN_VERSION}}`). Ask which environments exist (Alpha / Beta /
+   Production). **Print the detected plan and confirm before writing anything.**
+2. **Generate (Phase 2).** Copy templates with tokens substituted. **Diff/confirm per file** — if a
+   target exists, show the diff and ask overwrite/skip/merge; never blind-clobber; leave unrelated
+   files (a hand-kept `staging.yaml`) alone. Then do the **web edits** (below). Run the web build
+   once to prove nothing is baked.
+3. **Checklist (Phase 3).** Walk the dev interactively through the out-of-repo ops (below). This is
+   the deliverable.
+4. **Verify (Phase 4).** After the dev confirms the ops are done, push a tag (or reuse one), watch
+   the Actions run, then `curl` each deployed URL per environment and report pass/fail per app.
+
+## Token substitution
+
+| Token | Source |
+|-------|--------|
+| `{{PACKAGE_NAME}}` | `<project>-<appkey>`, e.g. `smiley-web`. Lowercase. This is the ghcr image name and the `package_name` workflow input. |
+| `{{APP_DIR}}` | The app's path, e.g. `apps/web`. **Single-app repo: `.`** (the app is the repo root — this leaves valid `./.next/...` paths in the template). |
+| `{{APP_KEY}}` | Short lowercase id unique per app: `api`, `web`, `worker`. Used in job names. |
+| `{{APP_PORT}}` | `3001` api · `3000` web · service's listen port (drop `EXPOSE` for a portless worker). |
+| `{{BUN_VERSION}}` | **Pin ≥ 1.3.10** (same across all Dockerfiles). Do **not** copy the host's `bun --version` — 1.2.x breaks `next build` on Linux with `TypeError: Expected CommonJS module to have a function wrapper` (edge/jest-worker; only shows on Linux, not macOS). |
+| `{{WORKSPACE_MANIFEST_COPIES}}` | **web template only:** one `COPY <app>/package.json ./<app>/package.json` line **per app** — the `deps` stage runs `bun install` before `COPY . .`, so it needs every workspace manifest to resolve the graph. The api/service compile templates copy only the built app's manifest (matches Smiley's api Dockerfile; avoids pulling a sibling app's postinstall without its src). **Single-app repo: empty string** (root `package.json` + `bun.lock` are already copied; there is no `packages/` — also delete the `COPY packages/ ./packages/` line). |
+| `{{MIGRATION_CHECK}}` | `_migration-check.partial.yml` with `{{MIGRATION_SCRIPT}}`/`{{MIGRATIONS_DIR}}` filled, **or empty string** if no DB. |
+| `{{ORG_REF}}` | The org reusable-workflow ref — currently `turborepo`. One place; bump here if the org repo retags. |
+| `{{BUILD_JOBS}}` / `{{DEPLOY_JOBS}}` | Stamp `_build-job.partial` once per app (Alpha only) and `_deploy-job.partial` once per app per environment, pruning unused envs. |
+| `{{DEPLOY_NAME}}` | The org `deploy.yml` `name` input → uppercased to `<NAME>_UUID`. **Only `API` and `WEB` are wired** in the org deploy.yml (see Gotchas). |
+
+## Web edits (surgical — not a file drop)
+
+For each **web** app, edit the files the dev owns; fail loudly if they can't be parsed rather than
+overwrite:
+
+- `next.config.js` — add `output: "standalone"`. **Monorepo only:** also add `outputFileTracingRoot`
+  (monorepo root) and `transpilePackages` for the workspace packages the app imports. **Single-app:
+  omit both** (root app traces natively; no workspace packages).
+- `app/layout.tsx` — add `<head><PublicEnvScript /></head>` (`import { PublicEnvScript } from
+  "next-runtime-env"`).
+- **Convert EVERY `process.env.NEXT_PUBLIC_*` read to `env("NEXT_PUBLIC_X")`** — not just client
+  components. Next **inlines every `process.env.NEXT_PUBLIC_*` literal at build time in SERVER code and
+  middleware too**, so any read left as `process.env` bakes the build value (or a build-time
+  placeholder) into the server/middleware bundle and runtime injection can't override it. This is the
+  #1 time-sink: a stray `process.env.NEXT_PUBLIC_SUPABASE_URL` in `middleware.ts` bakes the placeholder
+  → `supabase.auth.getUser()` fails → **auth redirect loop** that only shows in the container, not
+  locally. Convert: client components, **server components, route handlers (`app/api/**`), middleware,
+  and any t3-env `runtimeEnv` mapping**. Non-public server vars (`DATABASE_URL`, `*_SERVICE_KEY`) stay
+  on `process.env` — they aren't inlined and are present at runtime.
+- **Phase-2 gate — must pass before you call the web edits done:**
+  `grep -rn 'process.env.NEXT_PUBLIC' {{APP_DIR}}` (the app dir — `.` for single-app, `apps/web` for a
+  monorepo app; not every repo has a `src/`) returns **nothing**. Any hit is a latent runtime bug.
+- Flag `next-runtime-env` as a dependency to add — **do not run `bun add` yourself**; tell the dev.
+- **Caveat:** runtime values only reach the browser on non-statically-prerendered pages. A page that
+  reads runtime public env must opt out of static caching (`export const dynamic = "force-dynamic"`)
+  or rely on `<PublicEnvScript>` keeping the document dynamic. Note this so future feature work
+  doesn't silently bake a static page.
+
+## Single-app repos (no `apps/`, no `turbo.json`)
+
+The templates are monorepo-shaped; one set of token substitutions makes them serve a root-level single
+app. Apply these deltas (verified on `ddg-jewelry-admin`):
+
+- **Tokens:** `{{APP_DIR}}` = `.`, `{{PACKAGE_NAME}}` = repo name (no `-web` suffix),
+  `{{WORKSPACE_MANIFEST_COPIES}}` = empty.
+- **`Dockerfile.web`:** delete the `COPY packages/ ./packages/` line (no `packages/`). The runner
+  `COPY` lines collapse to `.next/standalone ./`, `.next/static ./.next/static`, `public ./public`
+  (the `{{APP_DIR}}=.` substitution yields valid `./.next/...` — fine to simplify).
+- **`next.config`:** `output: "standalone"` only — no `outputFileTracingRoot`, no `transpilePackages`.
+- **`ci.yml`:** drop the Turbo `env:`, the `.turbo` cache step, and swap `bun run check-types` for
+  `bunx tsc --noEmit` if the repo has no `check-types` script (single apps usually don't).
+- **Runner (optional but recommended):** a single Next app deploys cleanly on a Node runner
+  (`node:22-alpine` or `gcr.io/distroless/nodejs22-debian12`, `CMD ["server.js"]`). Distroless cuts the
+  image ~4× and drops the runner CVEs (seen on `ddg-jewelry-admin`).
+
+## Phase 3 — interactive ops checklist (the deliverable)
+
+Derived from the actual `codepassion-team/cicd` reusable workflows. Walk these one at a time:
+
+**Repo prerequisites**
+- A **`develop` branch must exist** — `build.yml` commits the version bump and does
+  `git pull --rebase origin develop` / `push HEAD:develop`. No develop branch → build fails.
+- Tags drive deploys; the exact tag→env mapping is **c9n-semver-deployment** (don't restate it).
+
+**Per environment** — create a GitHub **Environment** named exactly `Alpha` / `Beta` / `Production`:
+- Variables: `COOLIFY_RESOURCE_API_UUID`, `COOLIFY_RESOURCE_WEB_UUID` (the Coolify app UUIDs;
+  `deploy.yml` resolves `${NAME}_UUID`), and `TURBO_TEAM`.
+- Secrets: `COOLIFY_TOKEN` (Coolify API bearer) and `TURBO_TOKEN`. `GITHUB_TOKEN` is automatic
+  (ghcr push uses it; the build job already declares `packages: write`).
+
+**Coolify** (one resource per app per env): source = Docker image
+`ghcr.io/codepassion-team/{{PACKAGE_NAME}}:<base_tag>`; copy each resource's UUID into the matching
+env variable above. Caddy `reverse_proxy <app>:<port>` (api `:3001`, web `:3000`).
+
+**ghcr** — packages are **private**: give Coolify a registry pull credential (or set package
+visibility), or the image pull silently fails.
+
+**Web runtime env in Coolify** (the scars):
+- `PORT=3000` — Next standalone obeys `PORT`; Coolify defaults it to `80`, which 502s behind a
+  Caddy `:3000` proxy. This is the single most common web-deploy failure.
+- **Coolify `Ports Exposes` (General page) is a SEPARATE setting from the `PORT` env** — it defaults
+  to `80` and must be set to the app port (`3000`). With `PORT=3000` but Ports Exposes still `80`, the
+  deploy log warns `PORT (3000) does not match configured ports_exposes: 80` and the proxy 502s. Fix
+  both.
+- `HOSTNAME=0.0.0.0` — the Dockerfile already bakes this; only set it if something overrides it.
+- The app's `NEXT_PUBLIC_*` values — injected here at runtime, not baked into the image.
+- **Set ALL env values UNQUOTED** (public and server alike) — Coolify passes values literally, so a
+  quoted `DATABASE_URL="…"` keeps the quotes and breaks `new URL()` (`ERR_INVALID_URL`).
+
+## Phase 4 — verify
+
+Push a `v*.*.*` tag (or reuse one), watch the run (`gh run watch`), then for each app per env
+`curl -so /dev/null -w "%{http_code}"` the deployed URL (e.g. `https://api.<proj>.alpha.c9n.co`,
+`https://<proj>.alpha.c9n.co`) and confirm `200`. Report a clean pass/fail table. Don't call it done
+on a green Actions run alone — the 502 class only shows at the live URL.
+
+## Gotchas
+
+- **Combined install mode does not carry `templates/`.** `install.sh combined` copies only the
+  generated `skills/c9n` SKILL.md body. Install via `install.sh claude` (or `project`/`codex`) so the
+  templates come along — same limitation as `c9n-spec`/`c9n-deliverables`.
+- **Org deploy.yml wires only `API_UUID` + `WEB_UUID`.** A third app type (worker) needs a PR to
+  `codepassion-team/cicd` adding `COOLIFY_RESOURCE_<NAME>_UUID` to deploy.yml's `env:` block. Flag
+  this; don't generate a deploy job that silently can't resolve its UUID.
+- **Build once, deploy by base tag.** build.yml strips `-alpha`/`-rc.*`; deploy.yml also strips
+  `-beta.*`. So `v1.2.3` (Alpha) and a later `v1.2.3-beta.1` release both resolve base tag `v1.2.3`
+  and redeploy the same image. Beta/Prod must have an Alpha build of that base version in ghcr first.
+- **`.dockerignore` matters.** Without it, the host's `node_modules` (wrong platform) leaks into the
+  build context and clobbers the linux deps → "failed to load next.config". The template ships it.
+- **Don't touch `.env*`.** Generate `.dockerignore` to exclude them; never read or write env files.