@codepassion/skills 1.4.0 → 1.6.0

package/README.md

@@ -1,21 +1,57 @@
 # C9N Agent Skills
 
-Agent skills (SKILL.md) based on the CodePassion (C9N) conventions.
+Agent skills (SKILL.md) based on the CodePassion (C9N) conventions, plus the `c9n` CLI
+that installs them and drives tag-based deployments.
 
 ## Install
 
-    npx @codepassion/skills install claude     # ~/.claude/skills
-    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)
+    npm i -g @codepassion/skills   # provides the c9n command
+    c9n skill install claude       # ~/.claude/skills (default target)
+
+Or without a global install:
+
+    npx -p @codepassion/skills c9n skill install claude
 
 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
+## CLI
+
+### c9n skill
+
+    c9n skill install   [target]   # copy package skills into the target (skips existing; --force overwrites)
+    c9n skill list      [target]   # per-skill state: ok | drift | missing
+    c9n skill update    [target]   # overwrite drifted skills from the package (confirms; --yes skips)
+    c9n skill uninstall [target]   # remove installed c9n skills (confirms; --yes skips)
+    c9n skill doctor    [target]   # diagnose skills dirs, drift, frontmatter, gh/zip tooling
+
+Targets: `claude` (default, ~/.claude/skills) | `codex` (~/.codex/skills) |
+`project` (./.agents/skills) | `combined` (one merged skill) | `cowork` (upload zips).
+`--dest <dir>` overrides the directory; `--dry-run` previews any write.
+
+State is a runtime content-hash comparison against the package — "drift" covers both
+stale and hand-edited copies (see docs/adr/0001). `update` treats the package as the
+source of truth; skill edits belong in this repo, not in installed copies.
+
+claude.ai and Claude Cowork share a personal skill library with no upload API, so
+`c9n skill install cowork` packages upload-ready zips into dist/cowork/ — upload them at
 claude.ai → Settings → Capabilities → Upload skill.
 
+`c9n-skills` (the old bin) still works as a deprecated alias for `c9n skill`.
+
+### c9n deploy
+
+Creates and pushes an annotated tag in any C9N project with a tag-driven pipeline —
+the CLI never builds or ships artifacts itself.
+
+    c9n deploy -e alpha                # tags vX.Y.Z-alpha.N (version from package.json, N auto-increments)
+    c9n deploy -e alpha -v 1.2.3       # explicit version — always bare X.Y.Z, never the -alpha.N suffix
+    c9n deploy -e production -v 1.2.3  # tags v1.2.3 (requires a prior alpha of the same version)
+
+Guards (all must pass before the tag is pushed): clean working tree, on `main` and in
+sync with origin, tag ordering (production requires a prior alpha; versions must move
+forward), CI green on HEAD via `gh` (`--skip-ci` to bypass), and a confirmation prompt
+(`--yes` for CI). `--dry-run` runs every guard and shows the tag without creating it.
+
 ## Edit
 
 Per-topic SKILL.md files in skills/c9n-* are the source of truth.

package/SKILLS.md

@@ -1,21 +1,57 @@
 # C9N Agent Skills
 
-Agent skills (SKILL.md) based on the CodePassion (C9N) conventions.
+Agent skills (SKILL.md) based on the CodePassion (C9N) conventions, plus the `c9n` CLI
+that installs them and drives tag-based deployments.
 
 ## Install
 
-    npx @codepassion/skills install claude     # ~/.claude/skills
-    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)
+    npm i -g @codepassion/skills   # provides the c9n command
+    c9n skill install claude       # ~/.claude/skills (default target)
+
+Or without a global install:
+
+    npx -p @codepassion/skills c9n skill install claude
 
 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
+## CLI
+
+### c9n skill
+
+    c9n skill install   [target]   # copy package skills into the target (skips existing; --force overwrites)
+    c9n skill list      [target]   # per-skill state: ok | drift | missing
+    c9n skill update    [target]   # overwrite drifted skills from the package (confirms; --yes skips)
+    c9n skill uninstall [target]   # remove installed c9n skills (confirms; --yes skips)
+    c9n skill doctor    [target]   # diagnose skills dirs, drift, frontmatter, gh/zip tooling
+
+Targets: `claude` (default, ~/.claude/skills) | `codex` (~/.codex/skills) |
+`project` (./.agents/skills) | `combined` (one merged skill) | `cowork` (upload zips).
+`--dest <dir>` overrides the directory; `--dry-run` previews any write.
+
+State is a runtime content-hash comparison against the package — "drift" covers both
+stale and hand-edited copies (see docs/adr/0001). `update` treats the package as the
+source of truth; skill edits belong in this repo, not in installed copies.
+
+claude.ai and Claude Cowork share a personal skill library with no upload API, so
+`c9n skill install cowork` packages upload-ready zips into dist/cowork/ — upload them at
 claude.ai → Settings → Capabilities → Upload skill.
 
+`c9n-skills` (the old bin) still works as a deprecated alias for `c9n skill`.
+
+### c9n deploy
+
+Creates and pushes an annotated tag in any C9N project with a tag-driven pipeline —
+the CLI never builds or ships artifacts itself.
+
+    c9n deploy -e alpha                # tags vX.Y.Z-alpha.N (version from package.json, N auto-increments)
+    c9n deploy -e alpha -v 1.2.3       # explicit version — always bare X.Y.Z, never the -alpha.N suffix
+    c9n deploy -e production -v 1.2.3  # tags v1.2.3 (requires a prior alpha of the same version)
+
+Guards (all must pass before the tag is pushed): clean working tree, on `main` and in
+sync with origin, tag ordering (production requires a prior alpha; versions must move
+forward), CI green on HEAD via `gh` (`--skip-ci` to bypass), and a confirmation prompt
+(`--yes` for CI). `--dry-run` runs every guard and shows the tag without creating it.
+
 ## Edit
 
 Per-topic SKILL.md files in skills/c9n-* are the source of truth.

package/bin/c9n-skills.js

@@ -1,61 +1,5 @@
 #!/usr/bin/env node
-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) }
-if (cmd!=='install'){ help(); process.exit(1) }
-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'){ 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)
-if (!sources.length){ console.error('No skills found'); process.exit(1) }
-console.log(`Installing ${sources.length} skill(s) into ${dest}${flags.dryRun?' (dry-run)':''}`)
-if (!flags.dryRun) await mkdir(dest,{recursive:true})
-for (const src of sources){ const n=src.split(/[\\/]/).pop(); const t=join(dest,n)
-  if (existsSync(t) && !flags.force){ console.log(`  skip  ${n}`); continue }
-  console.log(`  copy  ${n}`); if (!flags.dryRun) await cp(src,t,{recursive:true,force:true}) }
-console.log('Done.')
-async function resolveSources(t){
-  if (t==='combined'){ const c=join(SRC,'c9n'); return existsSync(c)?[c]:[] }
-  const out=[]; for (const e of await readdir(SRC)){ if (!e.startsWith('c9n-')) continue
-    const f=join(SRC,e); if ((await stat(f)).isDirectory()) out.push(f) }
-  return out }
-function defaultDest(t){ const h=homedir()
-  if (t==='claude'||t==='combined') return join(h,'.claude','skills')
-  if (t==='codex') return join(h,'.codex','skills')
-  if (t==='project') return join(process.cwd(),'.agents','skills')
-  return null }
-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]') }
+// Deprecated alias: `c9n-skills <cmd> ...` → `c9n skill <cmd> ...`
+console.error('note: `c9n-skills` is deprecated — use `c9n skill <command>` instead')
+process.argv.splice(2, 0, 'skill')
+await import('./c9n.js')

package/bin/c9n.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { skillCommand, skillHelp } from './skill.js'
+import { deployCommand, deployHelp } from './deploy.js'
+
+const [, , cmd, ...rest] = process.argv
+try {
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') help(cmd ? 0 : 1)
+  else if (cmd === 'skill') await skillCommand(rest)
+  else if (cmd === 'deploy') await deployCommand(rest)
+  else { console.error(`unknown command: ${cmd}`); help(1) }
+} catch (e) {
+  console.error(`error: ${e.message}`)
+  process.exit(1)
+}
+
+function help(code) {
+  console.log(`c9n — CodePassion (C9N) engineering CLI
+
+Usage:
+  c9n skill <install|list|update|uninstall|doctor> [target] [options]
+  c9n deploy -e <alpha|production> [-v <X.Y.Z>] [options]
+
+Run \`c9n skill help\` or \`c9n deploy help\` for details.`)
+  process.exit(code)
+}

package/bin/deploy.js

@@ -0,0 +1,114 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { confirm, has, parseArgs, run } from './util.js'
+
+const RELEASE_BRANCH = 'main'
+
+export async function deployCommand(argv) {
+  if (['help', '--help', '-h'].includes(argv[0])) return deployHelp(0)
+  const flags = parseArgs(argv, { flags: ['yes', 'skip-ci', 'dry-run'], values: { env: 'e', version: 'v' } })
+  if (flags._.length) return deployHelp(1)
+  const env = flags.env
+  if (!env) throw new Error('missing -e <alpha|production>')
+  if (env !== 'alpha' && env !== 'production') throw new Error(`unknown environment: ${env} (use alpha | production)`)
+
+  const root = await git('rev-parse', '--show-toplevel').catch(() => { throw new Error('not inside a git repository') })
+  const version = await resolveVersion(flags.version, root)
+
+  // Guards: clean tree, on release branch, in sync with origin
+  const branch = await git('rev-parse', '--abbrev-ref', 'HEAD')
+  if (branch !== RELEASE_BRANCH) throw new Error(`deploy runs from ${RELEASE_BRANCH} — you are on ${branch}`)
+  if (await git('status', '--porcelain')) throw new Error('working tree is not clean — commit or stash first')
+  await git('fetch', 'origin', RELEASE_BRANCH, '--tags')
+  const head = await git('rev-parse', 'HEAD')
+  const remote = await git('rev-parse', `origin/${RELEASE_BRANCH}`)
+  if (head !== remote) throw new Error(`${RELEASE_BRANCH} is not in sync with origin/${RELEASE_BRANCH} — pull or push first`)
+
+  // Guard: tag ordering
+  const tags = (await git('tag', '-l', 'v*')).split('\n').filter(Boolean)
+  const prod = tags.filter((t) => /^v\d+\.\d+\.\d+$/.test(t)).map((t) => t.slice(1))
+  const latestProd = prod.sort(cmpVer).at(-1)
+  let tag
+  if (env === 'alpha') {
+    if (prod.includes(version)) throw new Error(`v${version} is already released to production — bump the version`)
+    if (latestProd && cmpVer(version, latestProd) < 0) throw new Error(`v${version} is older than latest production release v${latestProd}`)
+    const ns = tags.map((t) => t.match(new RegExp(`^v${version.replaceAll('.', '\\.')}-alpha\\.(\\d+)$`))).filter(Boolean).map((m) => Number(m[1]))
+    tag = `v${version}-alpha.${Math.max(0, ...ns) + 1}`
+  } else {
+    tag = `v${version}`
+    if (tags.includes(tag)) throw new Error(`${tag} already exists`)
+    if (!tags.some((t) => t.startsWith(`${tag}-alpha.`))) throw new Error(`no alpha of ${version} found — deploy \`-e alpha\` first`)
+    if (latestProd && cmpVer(version, latestProd) <= 0) throw new Error(`v${version} is not newer than latest production release v${latestProd}`)
+  }
+
+  // Guard: CI green on HEAD
+  if (!flags['skip-ci']) await checkCi(head)
+  else console.log('· CI check skipped (--skip-ci)')
+
+  const subject = await git('log', '-1', '--format=%h %s')
+  console.log(`\nDeploy ${env}`)
+  console.log(`  tag     ${tag}`)
+  console.log(`  commit  ${subject}`)
+  if (flags['dry-run']) { console.log('\n(dry-run) would create and push the tag.'); return }
+  if (!flags.yes && !(await confirm(`\nCreate and push ${tag}?`))) { console.log('Aborted.'); return }
+
+  await git('tag', '-a', tag, '-m', tag)
+  try {
+    await git('push', 'origin', tag)
+  } catch (e) {
+    throw new Error(`tag ${tag} created locally but push failed — retry with \`git push origin ${tag}\`\n${e.stderr ?? e.message}`)
+  }
+  console.log(`Pushed ${tag} — the pipeline takes it from here.`)
+}
+
+async function resolveVersion(raw, root) {
+  let v = raw
+  if (!v) {
+    const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8').catch(() => { throw new Error('no -v given and no package.json at repo root') }))
+    v = pkg.version
+    if (!v) throw new Error('no -v given and package.json has no version')
+  }
+  v = v.replace(/^v/, '')
+  if (!/^\d+\.\d+\.\d+$/.test(v)) throw new Error(`version must be bare X.Y.Z (got ${raw ?? v}) — the CLI appends -alpha.N itself`)
+  return v
+}
+
+async function checkCi(sha) {
+  if (!(await has('gh'))) throw new Error('gh CLI required for the CI check — install GitHub CLI or pass --skip-ci')
+  let runs
+  try {
+    runs = JSON.parse(await run('gh', ['run', 'list', '--commit', sha, '--json', 'name,status,conclusion', '--limit', '50']))
+  } catch (e) {
+    throw new Error(`could not query CI runs via gh — ${String(e.stderr ?? e.message).trim()} (or pass --skip-ci)`)
+  }
+  if (!runs.length) throw new Error('no CI runs found for HEAD — wait for CI to start or pass --skip-ci')
+  const pending = runs.filter((r) => r.status !== 'completed')
+  if (pending.length) throw new Error(`CI still running for HEAD: ${pending.map((r) => r.name).join(', ')}`)
+  const failed = runs.filter((r) => !['success', 'skipped', 'neutral'].includes(r.conclusion))
+  if (failed.length) throw new Error(`CI not green for HEAD: ${failed.map((r) => `${r.name} (${r.conclusion})`).join(', ')}`)
+  console.log(`· CI green on HEAD (${runs.length} run(s))`)
+}
+
+function cmpVer(a, b) {
+  const [ax, ay, az] = a.split('.').map(Number); const [bx, by, bz] = b.split('.').map(Number)
+  return ax - bx || ay - by || az - bz
+}
+
+function git(...args) {
+  return run('git', args)
+}
+
+export function deployHelp(code) {
+  console.log(`Usage: c9n deploy -e <alpha|production> [-v <X.Y.Z>] [options]
+
+Creates and pushes an annotated tag — the tag-driven pipeline does the rest.
+  alpha       tags vX.Y.Z-alpha.N (N auto-increments)
+  production  tags vX.Y.Z (requires a prior alpha of the same version)
+
+Options:
+  -v <X.Y.Z>  version to deploy (default: package.json version; never include -alpha.N)
+  --yes       skip the confirmation prompt
+  --skip-ci   skip the CI-green check (no gh needed)
+  --dry-run   run all guards, show the tag, don't create it`)
+  process.exit(code)
+}

package/bin/skill.js

@@ -0,0 +1,207 @@
+import { cp, mkdir, readdir, readFile, rm, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execFile } from 'node:child_process'
+import { confirm, has, parseArgs } from './util.js'
+
+const SRC = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
+const TARGETS = ['claude', 'codex', 'project', 'combined', 'cowork']
+
+export async function skillCommand(argv) {
+  if (['help', '--help', '-h'].includes(argv[0])) return skillHelp(0)
+  const flags = parseArgs(argv, { flags: ['force', 'dry-run', 'yes'], values: { dest: null } })
+  const [sub = 'install', target = 'claude'] = flags._
+  if (!TARGETS.includes(target)) throw new Error(`unknown target: ${target} (use ${TARGETS.join(' | ')})`)
+  const cmds = { install, list, update, uninstall, doctor }
+  if (!cmds[sub]) { console.error(`unknown skill command: ${sub}`); return skillHelp(1) }
+  if (sub !== 'install' && target === 'cowork') {
+    throw new Error(`cowork is packaged as zips, not installed — only \`c9n skill install cowork\` applies`)
+  }
+  await cmds[sub](target, { ...flags, dryRun: flags['dry-run'], dest: flags.dest ? resolve(flags.dest) : null })
+}
+
+async function install(target, flags) {
+  if (target === 'cowork') return packageForCowork(flags)
+  const dest = flags.dest ?? defaultDest(target)
+  const sources = await resolveSources(target)
+  if (!sources.length) throw new Error('No skills found')
+  console.log(`Installing ${sources.length} skill(s) into ${dest}${flags.dryRun ? ' (dry-run)' : ''}`)
+  if (!flags.dryRun) await mkdir(dest, { recursive: true })
+  for (const src of sources) {
+    const n = src.split(/[\\/]/).pop(); const t = join(dest, n)
+    if (existsSync(t) && !flags.force) { console.log(`  skip  ${n}`); continue }
+    console.log(`  copy  ${n}`)
+    if (!flags.dryRun) await cp(src, t, { recursive: true, force: true })
+  }
+  console.log('Done.')
+}
+
+async function list(target, flags) {
+  const dest = flags.dest ?? defaultDest(target)
+  const rows = await status(target, dest)
+  console.log(`Skills in ${dest}:`)
+  for (const r of rows) console.log(`  ${r.state.padEnd(9)} ${r.name}`)
+  const drifted = rows.filter((r) => r.state === 'drift').length
+  if (drifted) console.log(`\n${drifted} skill(s) differ from the package — \`c9n skill update ${target}\` overwrites them.`)
+}
+
+async function update(target, flags) {
+  const dest = flags.dest ?? defaultDest(target)
+  const drifted = (await status(target, dest)).filter((r) => r.state === 'drift')
+  if (!drifted.length) { console.log('All installed skills match the package — nothing to update.'); return }
+  console.log(`Package differs from ${drifted.length} installed skill(s) in ${dest}:`)
+  for (const r of drifted) console.log(`  ${r.name}`)
+  console.log('Local edits will be overwritten — the package is the source of truth.')
+  if (flags.dryRun) { console.log('(dry-run) no changes made.'); return }
+  if (!flags.yes && !(await confirm(`Overwrite ${drifted.length} skill(s)?`))) { console.log('Aborted.'); return }
+  for (const r of drifted) {
+    console.log(`  copy  ${r.name}`)
+    await cp(join(SRC, r.name), join(dest, r.name), { recursive: true, force: true })
+  }
+  console.log('Done.')
+}
+
+async function uninstall(target, flags) {
+  const dest = flags.dest ?? defaultDest(target)
+  const installed = (await status(target, dest)).filter((r) => r.state !== 'missing')
+  if (!installed.length) { console.log(`No c9n skills installed in ${dest}.`); return }
+  console.log(`Removing ${installed.length} skill(s) from ${dest}:`)
+  for (const r of installed) console.log(`  ${r.name}`)
+  if (flags.dryRun) { console.log('(dry-run) no changes made.'); return }
+  if (!flags.yes && !(await confirm(`Remove ${installed.length} skill(s)?`))) { console.log('Aborted.'); return }
+  for (const r of installed) await rm(join(dest, r.name), { recursive: true, force: true })
+  console.log('Done.')
+}
+
+async function doctor(target, flags) {
+  const dest = flags.dest ?? defaultDest(target)
+  let problems = 0
+  const check = (ok, label, hint) => {
+    console.log(`  ${ok ? '✓' : '✗'} ${label}${ok || !hint ? '' : ` — ${hint}`}`)
+    if (!ok) problems++
+  }
+  console.log(`Doctor (target: ${target})`)
+  check(existsSync(dest), `skills dir exists: ${dest}`, `run \`c9n skill install ${target}\``)
+  if (existsSync(dest)) {
+    const rows = await status(target, dest)
+    const fresh = rows.filter((r) => r.state === 'ok').length
+    const drift = rows.filter((r) => r.state === 'drift')
+    const missing = rows.filter((r) => r.state === 'missing')
+    check(!drift.length, `installed skills match package (${fresh}/${rows.length} fresh)`,
+      `${drift.length} differ (${drift.map((r) => r.name).join(', ')}) — \`c9n skill update ${target}\``)
+    if (missing.length) console.log(`  · ${missing.length} not installed (${missing.map((r) => r.name).join(', ')})`)
+    for (const r of rows) {
+      if (r.state === 'missing') continue
+      const f = join(dest, r.name, 'SKILL.md')
+      const ok = existsSync(f) && /^---\r?\n[\s\S]*?\bname:/.test(await readFile(f, 'utf8'))
+      if (!ok) check(false, `${r.name}/SKILL.md has valid frontmatter`, 'reinstall with --force')
+    }
+  }
+  check(await has('gh'), 'gh CLI available (needed by `c9n deploy` CI check)', 'install GitHub CLI or use --skip-ci')
+  check(await hasZip(), 'zip available (needed by `c9n skill install cowork`)', 'install zip')
+  if (problems) { console.log(`\n${problems} problem(s) found.`); process.exitCode = 1 }
+  else console.log('\nAll good.')
+}
+
+async function status(target, dest) {
+  const rows = []
+  for (const src of await resolveSources(target)) {
+    const name = src.split(/[\\/]/).pop(); const t = join(dest, name)
+    if (!existsSync(t)) { rows.push({ name, state: 'missing' }); continue }
+    rows.push({ name, state: (await hashDir(src)) === (await hashDir(t)) ? 'ok' : 'drift' })
+  }
+  return rows
+}
+
+async function hashDir(dir) {
+  const h = createHash('sha256')
+  for (const rel of (await walk(dir)).sort()) {
+    h.update(rel); h.update('\0'); h.update(await readFile(join(dir, rel))); h.update('\0')
+  }
+  return h.digest('hex')
+}
+
+async function walk(dir, prefix = '') {
+  const out = []
+  for (const e of await readdir(dir)) {
+    if (e === '.DS_Store') continue
+    const f = join(dir, e); const rel = prefix ? `${prefix}/${e}` : e
+    if ((await stat(f)).isDirectory()) out.push(...await walk(f, rel))
+    else out.push(rel)
+  }
+  return out
+}
+
+async function resolveSources(t) {
+  if (t === 'combined') { const c = join(SRC, 'c9n'); return existsSync(c) ? [c] : [] }
+  const out = []
+  for (const e of await readdir(SRC)) {
+    if (!e.startsWith('c9n-')) continue
+    const f = join(SRC, e); if ((await stat(f)).isDirectory()) out.push(f)
+  }
+  return out
+}
+
+function defaultDest(t) {
+  const h = homedir()
+  if (t === 'claude' || t === 'combined') return join(h, '.claude', 'skills')
+  if (t === 'codex') return join(h, '.codex', 'skills')
+  if (t === 'project') return join(process.cwd(), '.agents', 'skills')
+  return null
+}
+
+// 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.
+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) throw new Error('No skills found')
+  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()
+    })
+  })
+}
+
+async function hasZip() {
+  return new Promise((res) => execFile('zip', ['-v'], (e) => res(!e || e.code !== 'ENOENT')))
+}
+
+export function skillHelp(code) {
+  console.log(`Usage: c9n skill <command> [target] [options]
+
+Commands:
+  install    copy package skills into the target (default command)
+  list       show installed/missing/drift state per skill
+  update     overwrite drifted installed skills from the package
+  uninstall  remove installed c9n skills from the target
+  doctor     diagnose skills dirs and required tooling
+
+Targets: ${TARGETS.join(' | ')}   (default: claude)
+
+Options:
+  --dest <dir>   override the target directory
+  --force        install: overwrite existing skills
+  --yes          update/uninstall: skip confirmation
+  --dry-run      show what would happen without writing`)
+  process.exit(code)
+}

package/bin/util.js

@@ -0,0 +1,45 @@
+import { execFile } from 'node:child_process'
+import { createInterface } from 'node:readline'
+
+export function run(cmd, args, opts = {}) {
+  return new Promise((res, rej) => {
+    execFile(cmd, args, opts, (e, stdout, stderr) => {
+      if (e) { e.stdout = stdout; e.stderr = stderr; rej(e) }
+      else res(String(stdout).trim())
+    })
+  })
+}
+
+export async function has(cmd) {
+  try { await run(cmd, ['--version']); return true } catch { return false }
+}
+
+export async function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await new Promise((r) => rl.question(`${question} [y/N] `, r))
+  rl.close()
+  return /^y(es)?$/i.test(answer.trim())
+}
+
+export function parseArgs(argv, spec) {
+  // spec: { flags: ['force', ...], values: { dest: null, env: 'e', version: 'v' } }
+  const out = { _: [] }
+  for (const k of spec.flags ?? []) out[k] = false
+  for (const k of Object.keys(spec.values ?? {})) out[k] = null
+  const shorts = Object.fromEntries(Object.entries(spec.values ?? {}).filter(([, s]) => s).map(([k, s]) => [`-${s}`, k]))
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    const flag = a.startsWith('--') ? a.slice(2) : null
+    if (flag && (spec.flags ?? []).includes(flag)) { out[flag] = true; continue }
+    const key = flag && flag in (spec.values ?? {}) ? flag : shorts[a]
+    if (key) {
+      const v = argv[++i]
+      if (v === undefined) throw new Error(`${a} requires a value`)
+      out[key] = v
+      continue
+    }
+    if (a.startsWith('-')) throw new Error(`unknown option: ${a}`)
+    out._.push(a)
+  }
+  return out
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@codepassion/skills",
-  "version": "1.4.0",
-  "description": "Agent skills (SKILL.md) for CodePassion (C9N) engineering conventions.",
+  "version": "1.6.0",
+  "description": "Agent skills (SKILL.md) for CodePassion (C9N) engineering conventions, plus the c9n CLI for skill installs and tag-based deploys.",
   "license": "MIT",
   "type": "module",
   "bin": {
+    "c9n": "./bin/c9n.js",
     "c9n-skills": "./bin/c9n-skills.js"
   },
   "files": [

package/skills/c9n/SKILL.md

@@ -271,12 +271,20 @@ already owns, not a file drop (see Phase 2).
 
 Run in order; this is a table of contents — rules are below.
 
-1. **Detect (Phase 1).** Scan `apps/*/package.json`. Classify each: `next`→web, `elysia`→api, else
-   →service. 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 root `package.json` for the Bun version / lockfile name.
-   Ask which environments exist (Alpha / Beta / Production). **Print the detected plan and confirm
-   before writing anything.**
+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
@@ -291,11 +299,11 @@ Run in order; this is a table of contents — rules are below.
 | 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`. |
+| `{{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 from root toolchain, e.g. `1.3.10`. Same across all Dockerfiles. |
-| `{{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). |
+| `{{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. |
@@ -306,17 +314,46 @@ Run in order; this is a table of contents — rules are below.
 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"`, `outputFileTracingRoot` (monorepo root), and
-  `transpilePackages` for the workspace packages the app imports.
+- `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"`). Client code reads public config with `env("NEXT_PUBLIC_X")`, **not**
-  `process.env` (which bakes at build → undefined at runtime).
+  "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:
@@ -342,8 +379,14 @@ 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.
-- `HOSTNAME=0.0.0.0`.
+- **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
 

package/skills/c9n-pipeline/SKILL.md

@@ -31,12 +31,20 @@ already owns, not a file drop (see Phase 2).
 
 Run in order; this is a table of contents — rules are below.
 
-1. **Detect (Phase 1).** Scan `apps/*/package.json`. Classify each: `next`→web, `elysia`→api, else
-   →service. 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 root `package.json` for the Bun version / lockfile name.
-   Ask which environments exist (Alpha / Beta / Production). **Print the detected plan and confirm
-   before writing anything.**
+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
@@ -51,11 +59,11 @@ Run in order; this is a table of contents — rules are below.
 | 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`. |
+| `{{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 from root toolchain, e.g. `1.3.10`. Same across all Dockerfiles. |
-| `{{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). |
+| `{{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. |
@@ -66,17 +74,46 @@ Run in order; this is a table of contents — rules are below.
 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"`, `outputFileTracingRoot` (monorepo root), and
-  `transpilePackages` for the workspace packages the app imports.
+- `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"`). Client code reads public config with `env("NEXT_PUBLIC_X")`, **not**
-  `process.env` (which bakes at build → undefined at runtime).
+  "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:
@@ -102,8 +139,14 @@ 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.
-- `HOSTNAME=0.0.0.0`.
+- **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
 

package/skills/c9n-pipeline/templates/Dockerfile.web

@@ -3,6 +3,11 @@
 # Public env is read at RUNTIME via next-runtime-env (<PublicEnvScript>), so this
 # image bakes no NEXT_PUBLIC_* — Coolify injects them at run, like the API image.
 # Generated by c9n-pipeline; see the ADR this skill points you to.
+#
+# {{BUN_VERSION}} must be >= 1.3.10 — 1.2.x breaks `next build` on Linux.
+# Single-app repo: {{APP_DIR}}=. and {{WORKSPACE_MANIFEST_COPIES}}= empty; also
+# delete the `COPY packages/ ./packages/` line below (no packages/ dir). See the
+# "Single-app repos" section in SKILL.md.
 # -----------------------------------------------------------------------------
 
 FROM oven/bun:{{BUN_VERSION}} AS base

package/skills/c9n-pipeline/templates/workflows/ci.yml

@@ -34,5 +34,17 @@ jobs:
       - name: Check types
         run: bun run check-types
       - name: Build
-        run: bun run build
+        # Placeholder NEXT_PUBLIC_* values satisfy module-init that reads them at import
+        # time (e.g. Supabase clients) — CI has no .env files, so without these
+        # `next build` throws "Error: supabaseUrl is required" collecting page
+        # data. Real values are injected at runtime via next-runtime-env, never
+        # baked. Mirrors the Dockerfile build stage. Add one line per public var
+        # the app constructs a client from at import.
+        run: SKIP_ENV_VALIDATION=1 bun run build
+        env:
+          NEXT_PUBLIC_SUPABASE_URL: http://placeholder.invalid
+          NEXT_PUBLIC_SUPABASE_ANON_KEY: placeholder
 {{MIGRATION_CHECK}}
+# Single-app repos (no turbo.json): remove the TURBO_TOKEN/TURBO_TEAM `env:` and
+# the `.turbo` cache step above, and swap `bun run check-types` for
+# `bunx tsc --noEmit` if the repo has no check-types script.